Attach - PraisonAI

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.

Live-turn steering (-m / --message) and interrupt (--interrupt) landed in PR #5847 (release after 2026-10-15). Earlier releases supported read-only observation only. If attach -m or attach --interrupt prints runtime does not support …, the warm daemon is older than your CLI — restart it with praisonai daemon stop && praisonai daemon start.

Quick Start

Start the warm runtime

praisonai daemon start --background

Run an agent with a session id (terminal A)

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

Attach from another terminal (terminal B)

praisonai attach my-session

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.

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.

What --attach <id> really tags. --attach <id> is an event-stream label, not a session identity. Two things happen independently:

Persistence / continuity is driven by --session <id> or --continue (a --no-save run has no session identity, so no history is loaded or saved).
Live event fan-out to praisonai attach <id> clients is driven by --attach <id> (falls back to the session id when --attach is omitted).

So praisonai run "..." --no-save --attach obs-1 streams events to observers under obs-1 but persists nothing; praisonai run "..." --session s1 (no --attach) is observable under s1 and its history is retained across turns; praisonai run "..." --session s1 --attach obs-1 runs the stateful s1 conversation but publishes its events under obs-1.

Usage

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

Options must come before the session id. praisonai attach <id> --json and praisonai attach <id> -m "..." do not parse due to a Typer group-callback limitation. Always write praisonai attach -m "..." <id>.

Argument / Option	Type	Default	Description
`session_id`	positional	required	Session id to attach to
`--json`	flag	`false`	Emit raw NDJSON events instead of human-readable output
`--message`, `-m`	string	`None`	Steer the live turn with this message, then exit (no streaming)
`--interrupt`	flag	`false`	Request a cooperative cancel of the live turn, then exit (no streaming)

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

The CLI always sends priority 5 (NORMAL). For URGENT (20) or INTERRUPT (30) priorities, call agent.steer(message, priority=…) from Python. See Message Steering.

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

--interrupt only cancels the currently running turn. The session stays warm — the next praisonai run --session my-session "..." continues from where the interrupted turn left off.

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.

Events arrive over Server-Sent Events at GET /sessions/{session_id}/events with Bearer auth from the runtime lockfile. Session ids are percent-encoded on the wire. A : keep-alive comment is sent every ~15s and ignored.

Event Reference

Type	Fields	Human render
`run.start`	`session_id`, `prompt`	`▶ run.start: <prompt>`
`run.result`	`session_id`, `ok`, `result`	`✓ run.result` then result text
`run.error`	`session_id`, `error`	`✗ run.error: <error>`
`run.steer`	`session_id`, `message`	`↪ run.steer: <message>`
`run.interrupt`	`session_id`, `reason`	`■ run.interrupt requested`

Human output
--json (NDJSON)

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

Code	Meaning
`0`	Clean detach (Ctrl-C), or steer/interrupt sent
`1`	No compatible warm runtime, runtime lacks steer/interrupt support, or stream lost mid-attach
`4`	Runtime module not importable

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

Start the daemon first

Run praisonai daemon start before run --attach. Without a warm runtime, attach exits with code 1.

Use direct prompt runs only

--attach on praisonai run works for direct prompts only — not YAML files, --agent, or --command.

Detaching is safe

Ctrl-C in an attach terminal never cancels the underlying agent run.

One-shot steer and interrupt, not an interactive loop

-m and --interrupt send one request and exit. Run them again from a second terminal as needed; there is no persistent input loop inside attach.

Older daemon? Restart it after upgrading

If attach -m or attach --interrupt prints runtime does not support …, the warm daemon pre-dates PR #5847. Run praisonai daemon stop && praisonai daemon start to pick up the new routes.

Version mismatch after upgrade

If CLI and daemon major versions differ, attach refuses to connect. Run praisonai daemon stop && praisonai daemon start after upgrading.

Run

--attach flag for tagging warm-runtime sessions

Daemon

Warm runtime lifecycle and version handshake

Message Steering

Send guidance from Python with priority levels (URGENT / INTERRUPT)

​Quick Start

​Usage

​Steering a live turn

​Interrupting a live turn

​Which flag do I want?

​How It Works

​Event Reference

​Exit Codes

​Common Patterns

​Best Practices

​Related

Run

Daemon

Message Steering

Quick Start

Usage

Steering a live turn

Interrupting a live turn

Which flag do I want?

How It Works

Event Reference

Exit Codes

Common Patterns

Best Practices

Related