[irvingouj@Devolutions (irvingoujAtDevolution)]

AI analysis of a recording, started by DVLS with a plain HTTP request (no new token type), tracked as a provisioner Task and run as a job on the existing job queue.

Provisioner tasks run through a ProvisionerTaskRunner, the one place that keeps a task's record (#2041's ProvisionerTaskRecord) and its job in step. Each kind of work is a ProvisionerTask (what one attempt does, what to drop once its record ends); the runner creates the record, queues its job, runs each attempt with its timeout, retries transient failures and records how the Task ends. The Task is the source of truth and the job only wakes it up: each Task names the one job allowed to run it (#2041), so a stale or duplicate job does nothing. A Task is reported created only once its job is stored in the job queue. At startup, before the job runner claims anything, an unfinished Task whose job is no longer stored (such as after a crash between recording the Task and storing its job) gets a new one; a Task whose job is still stored keeps it. The analysis itself is the AI crate's analyze_recording (#2043); Gateway hands it the manifest of the finished recording and the language of the request, and adds the log it returns to the session as its own file.

API (stable, no enable_unstable)

• POST /jet/jrec/{session_id}/ai-analysis, scope gateway.tasks.recording-ai-analysis.start. Body: taskId, provider, model, baseUrl (needed for openai-compatible), maxOutputTokens, language, apiKey.
  • 202 + Task when created, 200 + Task for the same request again
  • 400 bad settings, body or language, 404 no recording
  • 409 task_id_conflict / recording_active (a clip is still pushed) / analysis_in_progress (+ the running taskId)
• GET /jet/jrec/{session_id}/ai-analysis/{task_id}, scope gateway.tasks.recording-ai-analysis.read: the Task (state, payload, attempts, times), or 404. The 202 answer of the POST names it in its Location header. A Task of another kind, or the analysis of another session, is not found under that path.

Each provisioner task declares its own scopes, gateway.tasks.<kind>.start and gateway.tasks.<kind>.read, so a token for one kind of Task can neither start nor read another kind. The kind of AI analysis is recording-ai-analysis.

The two new scopes in Devolutions.Gateway.Utils and the regenerated OpenAPI clients are in #2054, stacked on this PR.

The first commit hands the provisioner task store (#2041) to DgwState on its own gateway.db connection; DgwState::mock becomes async for that, hence the .await in a few tests. It also passes job_queue::MAX_ATTEMPTS (5, same as the current default) to the job queue explicitly, so the retry check in the AI analysis job can't drift from it.

How it behaves

• The API key and base URL live in memory only, encrypted, as the Task's secret in the SecretStore (feat(dgw): add an encrypted in-memory secret store #2058); never in the job, gateway.db or our logs. After a Gateway restart the Task fails with "the API key is no longer available".
• Transient provider errors are retried by the job queue (up to 5 attempts); permanent ones fail the Task. 30 min per attempt, 2 h per Task.
• Terminal (.cast, .trp) and video (.webm) recordings are analyzed (feat(dgw): analyze any recording in the AI crate #2043); video needs XMF v2026.9.25.0 or later.
• language is any text of 1 to 10 characters, such as fr-CA or français; anything else is a 400. Without it the analysis is in English. It's part of the Task parameters, so the same taskId with another language is a task_id_conflict.
• The result is its own log, ai-analysis-0.slog under artifacts.ai-analysis, with the summary on its session.end (feat(ai): write the AI analysis in the requested language, with a summary #2118). Gateway reads nothing the producer pushed.
• Every attempt of a new Task first takes the session lock and removes the earlier AI analysis, even a succeeded one. So a session holds at most one, and a Task that fails, even on a lost key, leaves none.
• The Task params keep the AI settings without the key and the base URL, plus the language; the OpenAPI document describes them as AiAnalysisParams.
• The Task payload names the log, the model, the prompt versions and the token usage.

Where to look hardest

• provisioner_tasks/runner/mod.rs: run_attempt (cancel on timeout, retry vs. fail, on_end on every end) and resume (called from service.rs before the job runner starts)
• provisioner_tasks/recording_ai_analysis/mod.rs: the AI ProvisionerTask, and lock_session: the working files belong to the session, so analyses of one session run one at a time (a Task past its deadline may still have an attempt running when the next Task starts)
• start() in the same file: the order of the checks

Known, accepted

• At VerbosityProfile All, reqwest/hyper's own TRACE lines show the provider's address (not the key). Our code never logs it.
• If Gateway crashes right after adding the log to the manifest, and before moving it in, the manifest lists a missing ai-analysis-0.slog.
• A Task that fails before any attempt runs (its job can't be queued, or no time is left for one) keeps the earlier analysis, since only an attempt holds the session lock.

Tests

• cargo test -p devolutions-gateway --lib: 249 passed.
• cargo test -p testsuite --test integration_tests ai_analysis: 10 passed. These endpoint tests drive the Gateway binary with a mock AI provider, and check that the key and the base URL reach neither the logs nor gateway.db. The testsuite gains a time dev-dependency to check the RFC 3339 times.
• clippy (--features openapi --tests) and nightly rustfmt are clean.
• Not run against a real AI provider at this head.

🤖 Generated with Claude Code

[github-actions]

Let maintainers know that an action is required on their side

• Add the label release-required Please cut a new release (Devolutions Gateway, Devolutions Agent, Jetsocat, PowerShell module) when you request a maintainer to cut a new release (Devolutions Gateway, Devolutions Agent, Jetsocat, PowerShell module)

• Add the label release-blocker Follow-up is required before cutting a new release if a follow-up is required before cutting a new release

• Add the label publish-required Please publish libraries (`Devolutions.Gateway.Utils`, OpenAPI clients, etc) when you request a maintainer to publish libraries (Devolutions.Gateway.Utils, OpenAPI clients, etc.)

• Add the label publish-blocker Follow-up is required before publishing libraries if a follow-up is required before publishing libraries

[irvingouj@Devolutions (irvingoujAtDevolution)]

Intent drafts: handoff

Read at a10bbd6b0 (feat/recording-ai-analysis), written in b1318c855.

Provenance

#	Commitment as written	Human's words (if tidied)	Level
1	They are kept encrypted in memory, in the SecretStore, until the Task ends or reaches its deadline.	Chose to name the standalone store, then adopted the candidate sentence with "good".	3

Left out on purpose

• Lines 23 and 25 of the Secrets section (never on disk; gone after a restart) still match the code, so they were not reopened.
• Who holds the store (DgwState.secrets) is wiring, recorded in DECISIONS.md, not intent.

Placement

devolutions-gateway/src/provisioner_tasks/INTENT.md, section "Secrets", line 24, replacing "in the provisioning store".

Pending experiments

None.

Note

Human-tuned, LLM-assisted content.