Interactive Chat

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

The ID column shows 16-character hashed IDs like a1b2c3d4e5f6a7b8.

Send a follow-up prompt:

rensei session prompt 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"
}

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 --status working

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

See Session Topology for the fleet graph view.

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"}'

Response:

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

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.

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