Interactive Chat

Prompt and stop sessions via rensei CLI/TUI - with idempotency-key retries and durable prompt receipt fields.

Interactive chat uses the same session wire format as the OSS runtime's TUI. The runner's session model is documented at donmai.dev/docs.

Interactive Chat lets you steer a running agent session with a text prompt - or stop it cleanly - without leaving your terminal. It is the primary interface for engineers who want to collaborate with an agent mid-run: redirect a working session, add a new requirement, or halt an agent that has gone off course.

Quick Start

Find the session's public ID from the session list:

rensei session list --project my-project
# or: rensei agent list --project my-project

The ID column shows 16-character hashed IDs like a1b2c3d4e5f6a7b8. rensei session and rensei agent expose the same prompt/chat surface; session prompt is the canonical spelling, agent chat is the legacy alias - both accept the flags below.

Send a follow-up prompt:

rensei session prompt a1b2c3d4e5f6a7b8 "Please also add unit tests for the auth module"
# legacy alias - same endpoint, same flags
rensei agent chat a1b2c3d4e5f6a7b8 "Please also add unit tests for the auth module"

Watch the activity stream to see the agent pick up the new directive:

rensei session stream a1b2c3d4e5f6a7b8

Stop the session when you are done or if it goes off-track:

rensei session stop a1b2c3d4e5f6a7b8

How Prompting Works

rensei session prompt sends POST /api/public/sessions/[id]/prompt with a JSON body:

{
  "prompt": "Please also add unit tests for the auth module"
}

The platform resolves the 16-character public ID to the full session, then re-queues work with the new prompt text. The behavior mirrors what an inbound Linear agent_session.prompted webhook with signal: continue does on the server side - the running or paused agent picks up the directive on its next poll cycle.

The prompt is dispatched at priority 2 (standard interactive priority), so it enters the queue ahead of lower-priority background work but behind any already-running claims. The agent's original system card prompt and credential tool restrictions are re-applied automatically - you cannot change the agent's identity or permissions via a prompt.

If the session is already in a terminal state (completed, failed, or stopped), the platform resets it to pending and re-dispatches before queuing the prompt. This lets you restart a finished session with new instructions without creating a new issue.

The endpoint returns immediately after queuing - it does not wait for the agent to act:

{
  "delivered": true,
  "promptId": "550e8400-e29b-41d4-a716-446655440000",
  "sessionId": "a1b2c3d4e5f6a7b8",
  "status": "queued"
}

Safe retries with `--idempotency-key` (v0.14.22 / Donmai v0.72.8)

Both spellings accept a stable idempotency key for safe retries:

rensei session prompt a1b2c3d4e5f6a7b8 "retry-safe prompt" --idempotency-key prompt-retry-1 --json
rensei agent chat a1b2c3d4e5f6a7b8 "retry-safe prompt" --idempotency-key prompt-retry-1 --json

When --idempotency-key is supplied the client sends { prompt, idempotencyKey } (donmai/afclient.ChatSessionRequest). The server echoes durable receipt fields on every response - see Durable prompt receipt fields below - and the CLI prints the receipt's disposition in its status line when present (queued / delivered / held, etc.). Replaying the same key returns the prior receipt without enqueuing a duplicate prompt. The --json form emits the full typed response, including deliveryTier, disposition, idempotencyKey, code, error, recoveryAction, and missingProjectionFields when the server provides them.

How Stopping Works

rensei session stop sends POST /api/public/sessions/[id]/stop. The platform runs the same handleStopSignal handler that an inbound signal: stop from Linear would trigger:

Resolves the public ID to the session
Flips the Redis status to stopped
Removes the session from the work queue and any parked-work slots
Releases the claim lock
Releases the issue lock and promotes the next queued work item for that issue
Emits a stop activity to the tracker (Linear, GitHub Issues, etc.)

{
  "stopped": true,
  "sessionId": "a1b2c3d4e5f6a7b8",
  "previousStatus": "working",
  "newStatus": "stopped"
}

The agent process receives a stop signal on its next heartbeat cycle and terminates cleanly.

Stopping a queued (not yet started) session

If the session is still pending when you stop it, the queued work is cancelled and the Linear thread receives: "Stop signal received. Queued work has been cancelled." This is useful when you realize a dispatched task is no longer needed before any agent picks it up.

Streaming Activities

To follow along in real time, stream the session's activity feed:

rensei session stream a1b2c3d4e5f6a7b8

This connects to GET /api/public/session-activities?sessionId=<id> with cursor-based polling. See Activities API for the full polling contract.

Common Patterns

Send prompts in sequence to guide the agent through multi-step work:

# Step 1: initial task is dispatched automatically by your workflow
# Step 2: once the agent completes the first pass, add a refinement
rensei session prompt a1b2c3d4e5f6a7b8 "The PR looks good, but please also update the CHANGELOG"

# Step 3: after the agent acts, review and close
rensei session stream a1b2c3d4e5f6a7b8
rensei session stop a1b2c3d4e5f6a7b8

Correcting a wrong direction

If rensei session stream shows the agent heading the wrong way, stop and re-prompt in one step:

rensei session stop a1b2c3d4e5f6a7b8
rensei session prompt a1b2c3d4e5f6a7b8 "Ignore the previous direction. Focus only on the login page, not the signup flow."

Stopping then prompting resets the session to pending and queues the corrective instruction. The agent starts fresh with the new directive - but the full prior activity history is still visible in the Session Inspector for post-mortem review.

Watching a fleet of sessions

To see all active sessions before choosing which one to prompt:

# List active sessions in your project
rensei session list --project my-project

# Open the topology view in your browser for a graph overview
# /[orgSlug]/[projectSlug]/sessions (topology tab)

See Session Topology for the fleet graph view.

Durable prompt receipt fields

Since Donmai v0.72.8 (shipped in rensei v0.14.22), ChatSessionResponse carries typed durable receipt fields in addition to delivered:

Field	Meaning
`deliveryTier`	Delivery tier of the persisted prompt (e.g. `interactive`).
`disposition`	Terminal disposition when known (e.g. `held`, `queued`, `delivered`). The CLI prints this value in its human status line when present.
`idempotencyKey`	Echo of the key you sent, when the server stored one.
`code` / `error`	Machine and human error detail when the prompt was not accepted.
`recoveryAction`	Suggested recovery when the server can name one.
`missingProjectionFields`	Projection fields the server found absent.

These fields are additive and typed. A gray rectangle with only delivered: true remains valid from older servers; newer servers populate the additional fields. See the Donmai v0.72.8 notes for the client change and donmai/afclient/types.go:ChatSessionResponse for the wire shape.

API: Direct HTTP Access

You can call the prompt and stop endpoints directly with a rsk_* Bearer token or session cookie. The [id] path segment is the 16-character public hash from the session list.

curl -X POST \
  https://app.rensei.ai/api/public/sessions/a1b2c3d4e5f6a7b8/prompt \
  -H "Authorization: Bearer rsk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Add integration tests for the checkout flow"}'
# with a stable retry key - same wire `donmai` uses for `agent chat --idempotency-key`
curl -X POST \
  https://app.rensei.ai/api/public/sessions/a1b2c3d4e5f6a7b8/prompt \
  -H "Authorization: Bearer rsk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Add integration tests for the checkout flow", "idempotencyKey": "prompt-retry-1"}'

Response:

{
  "delivered": true,
  "promptId": "550e8400-e29b-41d4-a716-446655440000",
  "sessionId": "a1b2c3d4e5f6a7b8",
  "status": "queued"
}

With idempotencyKey the response may also include deliveryTier, disposition, idempotencyKey, code, error, recoveryAction, and missingProjectionFields - see Durable prompt receipt fields.

curl -X POST \
  https://app.rensei.ai/api/public/sessions/a1b2c3d4e5f6a7b8/stop \
  -H "Authorization: Bearer rsk_live_…"

Response:

{
  "stopped": true,
  "sessionId": "a1b2c3d4e5f6a7b8",
  "previousStatus": "working",
  "newStatus": "stopped"
}

Authentication

Both endpoints accept:

rsk_* Bearer token - Authorization: Bearer rsk_live_… - org-scoped; the token must belong to the same org as the session.
Session cookie - set automatically when authenticated in the browser.

Unauthenticated requests return 401. Requests for sessions in a different org return 404 (the platform never leaks cross-org session existence).

Behavior on Terminal Sessions

If a session is already completed, failed, or stopped when you call /prompt, the platform resets it automatically:

Releases the existing claim lock
Sets status back to pending
Queues the new prompt

This is useful for iterative work - you can continue a session that completed a task by prompting it with the next step.

Resetting a terminal session restarts it with the same agent card, model profile, and project context. The prior activity history is preserved and visible in the Session Inspector, but the agent does not retain in-process memory across the reset.

Program - canonical multi-session program ledger reads (v0.14.21+)
Capacity - receipt forwarding - per-pool receiptForwarding opt-in
Upgrade - v0.14.21 / v0.14.22 release notes and the Donmai v0.72.8 changelog
Session List - find session IDs
Session Detail - view activity stream and health
Session Inspector - full tool call history and context browser for a session
Activities API - poll or stream activities programmatically
Session Topology - fleet-wide graph of all active sessions
Linear Agent Session - how platform prompts relate to Linear's agent_session.prompted trigger