Attach

Watch, steer, or interrupt a live session running on the warm runtime

praisonai attach connects a second terminal to a live agent session on the warm runtime. By default it streams events read-only; with --message it steers the live turn, and with --interrupt it cancels it — both as one-shot sends that exit without streaming.

Quick Start

1. Start the warm runtime

   praisonai daemon start --background

2. Run an agent with a session id (terminal A)

   praisonai run "Research topic X" --attach my-session

3. Attach from another terminal (terminal B)

   praisonai attach my-session

4. Steer the live turn from another terminal

   praisonai attach -m "also update the tests" my-session

   Sends the steering message and exits. The running agent picks it up on its next tool-loop iteration.

5. Interrupt the live turn from another terminal

   praisonai attach --interrupt my-session

   Requests a cooperative cancel and exits. The run stops at the next safe boundary.

Usage

praisonai attach [--json] [--message TEXT] [--interrupt] <session-id>

Steering a live turn

Send mid-run guidance to a session that is already executing on the warm runtime; it lands on the agent’s next tool-loop iteration without restarting the run.

# Terminal A — start a long-running agent on the warm runtime
praisonai run "Research solar market trends and write a 500-word summary" --attach my-session

# Terminal B — steer it mid-run
praisonai attach -m "Focus on the EU market only" my-session

# Terminal B (optional) — stop it early
praisonai attach --interrupt my-session

User (Term A):  praisonai run "research solar market trends..." --attach my-session
Agent:          (searching → reading → summarising …)
User (Term B):  praisonai attach -m "focus on the EU market only" my-session
Agent:          (next iteration picks up guidance, re-scopes the next search)
User (Term B):  praisonai attach --interrupt my-session
Agent:          ■ run.interrupt requested — stops at next safe boundary

Interrupting a live turn

--interrupt requests a cooperative cancel; the agent stops at the next safe boundary, so partial progress and conversation history stay intact.

praisonai attach --interrupt my-session

Which flag do I want?

Both flags can be combined (-m "focus" --interrupt <id>): the message is sent first, then the interrupt.

How It Works

Attaching never starts execution; plain attach only observes, while -m and --interrupt act on a turn already in flight (not gated by the run lock). Detaching (Ctrl-C) does not stop the run on terminal A.

Event Reference

Attached to session 'my-session'. Ctrl-C to detach.
▶ run.start: Research topic X
✓ run.result
Here is the summary...

praisonai attach my-session --json | jq 'select(.type=="run.result")'

{"type": "run.start", "session_id": "my-session", "prompt": "Research topic X"}
{"type": "run.steer", "session_id": "my-session", "message": "Focus on the EU market only"}
{"type": "run.interrupt", "session_id": "my-session", "reason": "attach"}
{"type": "run.result", "session_id": "my-session", "ok": true, "result": "..."}

Exit Codes

Common Patterns

Watch a long-running agent from a second terminal — start with --attach, observe progress without blocking terminal A.

Pipe JSON into jq — praisonai attach my-session --json | jq 'select(.type=="run.result")'.

Multiple observers — several terminals can attach to the same session concurrently; all receive the same events.

Observe without persisting — praisonai run "..." --no-save --attach obs-1 streams events under obs-1 for observers while keeping the run on the anonymous, non-persisted path.

Steer a long multi-tool run from a second terminal — praisonai attach -m "focus on the EU market only" my-session lands on the next tool-loop iteration without restarting the run.

Stop a stuck turn without losing the session — praisonai attach --interrupt my-session cancels the current turn only; the next run --session my-session continues from where it left off.

Best Practices

Related