Work Session tools

A Work Session is the approval-gated unit that scopes infrastructure-mutating MCP actions to an auditable record. When a caller authenticates through MCP OAuth or a browser session, the Alpacon server requires every execute_command call and file transfer to be linked to an active Work Session; static API tokens and service tokens bypass this requirement. These tools cover the full session lifecycle—create, inspect, update, extend, and close—plus the AI-based security analysis that runs on completed sessions. They back requests like “start a session so I can restart nginx on prod-web-1” or “show me what happened in that session yesterday.”

An AI agent cannot approve or reject a Work Session; a human must approve it. When a session is created it commonly lands in pending and needs a human to approve it out-of-band, in the Alpacon web console or via Slack; a Work Session update can also be queued as a modification request that needs the same kind of approval. In both cases the affected tool returns a structured pending-approval result instead of failing outright—surface it to a human, then retry once approved.

Tools elsewhere that accept a work_session_id argument, such as execute_command, fall back to the ALPACON_WORK_SESSION environment variable when the argument is omitted; an explicit argument always wins.

For the equivalent CLI workflow, see alpacon work-session. For the underlying concept, see the Work Sessions overview.

Summary

Creating and viewing

work_session_create

Creates a Work Session that scopes subsequent infrastructure actions to an auditable, approval-gated record. description should say what the work is and why—a vague one-liner like “maintenance” is hard for a human to approve; Markdown is supported. scopes declares which operations the session allows: command (execute_command), webftp (file transfers), tunnel (port forwarding), or sudo (privilege elevation). servers lists the target server UUIDs.

A session created this way commonly lands in pending—it needs human approval before any scoped action runs. When that happens, the tool returns a structured pending-approval result instead of the raw session object; poll work_session_get and wait for active status before proceeding.

Access: Additive

Parameters

Example

“Start a work session to restart nginx on prod-web-1, command access only, expiring in 2 hours”

The agent calls work_session_create with scopes=["command"], servers set to prod-web-1’s UUID, and a descriptive description, then waits for human approval before running the restart.

work_session_get

Gets the current status, scopes, servers, requester type, and expiry of a Work Session. Use this to check whether a session created or updated by work_session_create / work_session_update has moved past pending into active.

Access: Read-only

Parameters

Example

“Is my work session active yet?”

The agent calls work_session_get with the session ID and reports its current status.

work_session_list

Lists Work Sessions in the workspace. Filter by status (pending, approved, active, completed, rejected, cancelled, expired, revoked) or by requester_type (user for human-requested sessions, agent for AI-requested sessions).

Access: Read-only

Parameters

Example

“Show me all pending work sessions opened by agents”

The agent calls work_session_list with status="pending" and requester_type="agent".

work_session_timeline

Gets the unified, chronological timeline of a Work Session: commands, file transfers, Websh activity, and sudo grants in execution order. Set include_records=false to omit Websh terminal records for a lighter response.

Access: Read-only

Parameters

Example

“What happened in that work session, in order?”

The agent calls work_session_timeline with the session ID and walks through the returned activity in execution order.

Modifying

work_session_update

Partially updates a Work Session—only the fields you provide are sent, and passing an empty string clears a text field such as title. A pending session updates immediately. An approved or active session goes through the modification flow instead: when the server queues the change for approval, this tool returns a status="pending_approval" result, and the update only takes effect once a human approves it out-of-band.

expires_at is only honored for pending sessions; for approved or active sessions it is ignored, so use work_session_extend instead. A terminal session (completed, rejected, cancelled, expired, revoked) cannot be updated.

Access: Idempotent write

Parameters

Example

“Add db-02 to my active work session’s server list”

The agent calls work_session_update with servers set to the expanded list. Since the session is active, the change is queued as a modification request pending human approval.

work_session_extend

Extends the expiry of an approved or active Work Session. The new expires_at must be later than the current expiry. Any sudo policy bound to the session is extended together with it.

Access: Idempotent write

Parameters

Example

“Extend my work session by another hour”

The agent calls work_session_extend with expires_at set to the new expiry time.

Analysis and closing

work_session_analyze

Manually triggers AI security analysis for a terminal Work Session (completed, expired, or revoked—rejected and cancelled sessions never activated, so there’s nothing to analyze). Analysis normally runs automatically when a session is closed with work_session_close; use this tool to re-run one that failed. Set force=true to retry an analysis stuck in pending or processing—the server still enforces a minimum age guard and never discards a completed result.

Access: Idempotent write

Parameters

Example

“That session’s security analysis failed—try it again”

The agent calls work_session_analyze with force=true to retry the stuck analysis.

work_session_close

Marks a Work Session as completed and triggers AI security analysis (Pass 1–4). Call this after all commands and file transfers for the session are done.

Access: Destructive

Parameters

Example

“I’m done with the nginx fix, close the work session”

The agent calls work_session_close with the session ID, ending the session and kicking off its AI security analysis.

Related

• Command execution tools: pass work_session_id to link a command to a session
• Audit tools: review session analyses and activity logs after a session closes
• alpacon work-session: the equivalent CLI commands
• Work Sessions overview: the underlying concept and approval workflow