Session operations

Once a session exists, use these operations to drive, read, control, or remove it. See Sessions for creating one and its lifecycle.

Retrieve a session

vetta session get $SID

const s = await vetta.sessions.get(sessionId);
console.log(s.status, s.consumed_micro_usd, s.stop_reason); // cost in integer micro-USD

List sessions

Results are paginated. Filter by agent or by deployment_id (each scheduled fire is a session tagged with its deployment), and sort by creation time. Each response includes has_more and a next_cursor; pass next_cursor back as after to fetch the next page. The cursor is null at the end.

vetta session list --agent Refunder --limit 20
vetta session list --deployment-id dep_9f... --limit 20     # fires from one deployment

for await (const s of vetta.sessions.list({ agentId: agent.id, limit: 20 })) {
  console.log(s.id, s.status);
}

// Or page manually with cursors:
const page = await vetta.sessions.list({ deploymentId: "dep_9f...", limit: 20 });
console.log(page.data.length, page.has_more, page.next_cursor);

Sending input

You drive a session by sending it input. Every input is recorded on the event stream, and if the session is idle it wakes into running. There are four input types:

Input	What it does
User message	Ordinary text (or structured content) for the agent to act on.
Interrupt	Stops the current turn at the next commit boundary.
Tool confirmation	Allows or denies a tool call the agent is waiting on (see policies). A deny can carry a reason.
Answer	Supplies what the agent asked for when it parked on a question — a payload and no verb, where a confirmation is a verb and no payload. See the awaiting-answer loop.

vetta session send      --session $SID --message "Refund order #4821"
vetta session interrupt --session $SID
vetta session confirm --session $SID --tool-call $CALL_ID --allow
vetta session confirm --session $SID --tool-call $CALL_ID --deny --reason "wrong account"
vetta session answer  $SID

await vetta.sessions.send(sessionId, { message: "Refund order #4821" });
await vetta.sessions.interrupt(sessionId);
await vetta.sessions.confirmTool(sessionId, { tool_call_id: callId, decision: "allow" });
await vetta.sessions.confirmTool(sessionId, { tool_call_id: callId, decision: "deny", reason: "wrong account" });
await vetta.sessions.answer(sessionId, { tool_call_id: askId, answers: { mailbox: "hello@acme.com" } });

Stream the session to watch it react to input — reconnect with fromSeq to resume from the last seq you handled without gaps or duplicates. See Events & streaming.

Interrupt and redirect in one call

Inputs can be batched so they land atomically. The common case is steering a running agent: send an interrupt together with a new message. The agent wraps up the current turn cleanly at the next commit boundary — the interrupted turn ends with stop_reason: "end_turn" — and then picks up the redirect.

vetta session send --session $SID --interrupt --message "Stop — issue a store credit instead."

await vetta.sessions.send(sessionId, {
  interrupt: true,
  message: "Stop — the customer wants a store credit instead.",
});

Awaiting-approval loop

When the agent calls a tool governed by an ask policy, the runtime does not run the tool. Instead the session goes idle with stop_reason: "awaiting_approval" and exposes the waiting call(s) on pending_actions[]. You resolve each one with an allow/deny confirmation; once the last pending action is answered, the session resumes automatically.

{
  "id": "ses_4a...",
  "status": "idle",
  "stop_reason": "awaiting_approval",
  "pending_actions": [
    {
      "kind": "tool",
      "tool_call_id": "call_8Q...",
      "name": "refund",
      "args": { "order_id": "4821", "amount_micro_usd": 42000000 }
    }
  ]
}

vetta session get $SID              # stop_reason=awaiting_approval, lists pending_actions
vetta session confirm --session $SID --tool-call call_8Q... --allow
vetta session confirm --session $SID --tool-call call_8Q... --deny --reason "not this account"

const s = await vetta.sessions.get(sessionId);
for (const a of s.pending_actions) {
  if (a.kind !== "tool") continue;       // a question is answered, not approved — see below
  await vetta.sessions.confirmTool(sessionId, {
    tool_call_id: a.tool_call_id,
    decision: a.name === "refund" ? "allow" : "deny",
    reason: "out of policy",
  });
}

Branch on kind, not on name, and not on stop_reason alone. pending_actions[] holds both kinds of park, and a session that stopped on a mix of the two reports awaiting_approval while still carrying question rows — awaiting_answer means every parked row is a question. A loop that sends every entry to tool_confirmations gets a validation_failed on each question, and one that reads only the stop reason silently never asks them.

A held tool consumes no budget while it waits — a session can sit on a confirmation for hours at storage cost only. See Policies for how a tool resolves to ask, and Events & streaming for the tool.confirm event shape.

Awaiting-answer loop

The mirror of the loop above, for the park the agent starts itself. When an agent calls ask_operator the turn stops the same way — idle, rows on pending_actions[], no budget burning — but the row is tagged kind: "question" and carries a question object: the sentence the agent wrote, and one to three fields to fill in.

{
  "id": "ses_4a...",
  "status": "idle",
  "stop_reason": "awaiting_answer",
  "pending_actions": [
    {
      "kind": "question",
      "tool_call_id": "call_9F...",
      "name": "ask_operator",
      "question": {
        "prompt": "Which mailbox should the crew send from?",
        "fields": [
          { "key": "mailbox", "label": "Mailbox", "type": "text", "placeholder": "hello@acme.com" },
          { "key": "tone", "label": "Tone", "type": "choice", "options": ["formal", "warm"], "other": true }
        ]
      }
    }
  ]
}

vetta session inbox                 # every session waiting on a person, both kinds
vetta session answer $SID           # prints the question, asks for each field in turn

const s = await vetta.sessions.get(sessionId);
for (const a of s.pending_actions) {
  if (a.kind !== "question") continue;
  await vetta.sessions.answer(sessionId, {
    tool_call_id: a.tool_call_id,
    answers: { mailbox: "hello@acme.com", tone: "warm" },
  });
}

Four rules a surface that renders a question has to keep:

Render from question, never from args. They hold the same content — args is what the model called with and what replays byte-identically — but question is the shape a renderer reads, and it is the one that will keep its meaning if the tool’s arguments ever change.
Every field must be answered, with a non-empty value, unless it is marked optional: an agent that could proceed without one of them would not have asked it. A partial answer is validation_failed (400) naming answers.<key>. The escape a person needs is the free-text arm, which is on by default.
A field with optional: true may be skipped, by leaving its key out. That is the only way to say “no answer”: omit the key entirely. A key that is present is checked like every other one, so sending "", [] or an unlisted option for an optional field is still validation_failed — an answer that was given is an answer that was meant.
A choice answer is the option’s words, never an index. The model reads them back as prose. Send string[] for a multiple: true field and a plain string for everything else; the route enforces the arity.

The answer folds into the next turn as the result of the call that asked, carrying the question with it — so the model sees what it asked and what came back, not a bare set of words against an id it no longer remembers.

Not every agent can ask. ask_operator is offered only on a harness that can hold a call open for a person — see Harness capabilities — and an agent whose toolset denies it cannot park this way at all.

Approver

Each resolved confirmation records who answered it — the approving principal (a user or API key id) is written to the event and audit trail alongside the decision and any deny reason. This is what lets you prove, after the fact, that a payout or destructive action was signed off by a person rather than silently auto-run. An unanswered ask waits until someone answers it. Watch for session.idle with stop_reason: "awaiting_approval", or run vetta session inbox, so every parked call reaches a person.

Plan mode

Send with mode: "plan" — or create the session with it — and the session plans before it builds. It researches read-only, asks what it cannot look up, and keeps a living Markdown plan with - [ ] to-dos. When the plan is ready it proposes it, and the session parks on one card: allow it to build the plan, or deny it — with an optional reason — to keep planning.

Read-only is enforced, not asked for. In plan mode the agent is offered reads, web search, the board read, ask_operator and the two plan tools. Shell, file writes, the browser, generators, metered tools and anything that starts other sessions are not offered at all.
Only a person leaves plan mode. Allow on the plan card, or a send with mode: "build". The agent has no way out.
The plan is its own record. Read it with GET /v1/sessions/{id}/plan. Edit it with PUT /v1/sessions/{id}/plan and the base_version you read; a stale version is version_conflict. The agent sees the edit on its next turn, and after the allow it ticks each to-do as it builds.
The stream says so. session.mode marks each change, and plan.updated carries the plan on every write. Both are opt-in on the events list (include_accepted=true).

A harness that cannot hold a call for approval cannot plan: mode: "plan" there is validation_failed.

TypeScript

await vetta.sessions.send(sessionId, { message: "Plan the launch post", mode: "plan" });
const plan = await vetta.sessions.plan(sessionId);
await vetta.sessions.writePlan(sessionId, { markdown: `${plan.markdown}\n- [ ] Check the price`, base_version: plan.version });

Interrupting

A running session must be interrupted before you can update its agent, archive it, or delete it. An interrupt is delivered as an event and stops the current turn at the next commit boundary — you lose at most one turn, never the run. On its own, an interrupt lands the session at idle with stop_reason: "interrupted".

vetta session interrupt --session $SID

await vetta.sessions.interrupt(sessionId);

Archiving

Cancelling stops a session and releases its sandbox while preserving its record and its events.

CLI

vetta session cancel --session $SID

A session cannot be archived or deleted. There is no vetta session archive and no vetta session delete, and no DELETE /v1/sessions/{id} route behind them — cancel is the only terminal operation. A session’s record and event history are permanent; the sandbox and the files scoped to it are released on cancel.Files the session produced go with the sandbox. Files promoted with publish_file or uploaded to the Files API are organization-scoped and survive. Skills, deployments, webhooks, identities and vaults are independent resources and are unaffected. Publish anything you need to keep before cancelling.

Next: events & streaming

The resumable event model behind every session.

Agent

Running an agent

Agent capabilities

Computer

Identity

Team

Session operations

Retrieve a session

List sessions

Sending input

Interrupt and redirect in one call

Awaiting-approval loop

Awaiting-answer loop

Approver

Plan mode

Interrupting

Archiving

Next: events & streaming

​Retrieve a session

​List sessions

​Sending input

​Interrupt and redirect in one call

​Awaiting-approval loop

​Awaiting-answer loop

​Approver

​Plan mode

​Interrupting

​Archiving

Next: events & streaming

Retrieve a session

List sessions

Sending input

Interrupt and redirect in one call

Awaiting-approval loop

Awaiting-answer loop

Approver

Plan mode

Interrupting

Archiving