Attach

Stream live events from a session running on the warm runtime

praisonai attach subscribes to a live agent session on the warm runtime and streams its events in real time from a second terminal — read-only, with multiple observers supported.

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
   

---

Usage

praisonai attach <session-id> [--json]

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

---

How It Works

Attaching never starts execution — it only observes. 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>

Human output

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

--json (NDJSON)

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

{"type": "run.start", "session_id": "my-session", "prompt": "Research topic X"}
{"type": "run.result", "session_id": "my-session", "ok": true, "result": "..."}

---

Exit Codes

Code	Meaning
0	Clean detach (Ctrl-C)
1	No compatible warm runtime, 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.

---

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.

Version mismatch after upgrade

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

---

Related

Run

--attach flag for tagging warm-runtime sessions

Daemon

Warm runtime lifecycle and version handshake