@plori/cli 0.3.2 → 0.4.0

package/README.md

@@ -135,9 +135,11 @@ plori attach mate                        # open the live session (interactive)
 plori create mate                        # get-or-create an agent named "mate"
 plori run mate "clone repo X and run the tests"
 plori run mate "long job" --no-wait      # returns a run id immediately
-plori result mate <run-id> --wait        # poll it later
+plori result mate <run-id> --wait        # wait for it later
 plori run mate "build it" --follow       # stream the turn live (tools on stderr)
 echo "summarize this" | plori run mate -  # message from stdin
+plori watch --agent mate                 # one JSON line per run ending
+plori inbox                              # what ended, and what waits on you
 plori schedule mate "daily report" --in 86400
 plori inputs mate                        # runs paused on a human question
 plori answer <run-id> <tool-call-id> --approve
@@ -155,26 +157,108 @@ Agents are addressed by name or UUID. Every command accepts `--json`; when
 stdout is not a TTY the output is JSON automatically, so scripts and agents
 can parse without flags. `plori attach` is the one exception: it is a live
 stream rather than a single result, so it always writes plain text, and a
-redirected stream turns it into a read-only tail. Errors go to stderr; exit
-codes: 0 success, 1 API failure, 2 usage error.
+redirected stream turns it into a read-only tail. `plori watch` is the other:
+its output is a stream of JSON lines in every mode. Errors go to stderr, and
+the exit codes are listed under [Agent-driven use](#agent-driven-use).
 
-## For agent authors
+## Agent-driven use
 
 The reply text of `plori run` is the only thing written to stdout (tool
-narration streams to stderr), so a calling agent can pipe it directly. A run
-that pauses on a human approval reports `status: "awaiting_input"`; surface
-it and answer with `plori answer`. An approval that gates an outward-facing
-write carries a `consent_tool` (visible in `plori inputs --json`); answering it
-with `--always-allow` also grants a standing consent so the agent stops asking
-for that tool. That is the human's call to make, not the calling agent's; on a
-row without a `consent_tool` the flag grants nothing. Prefer one long-lived
-agent (`create` returns the existing agent for a reused name) over creating
-new ones.
+narration streams to stderr), so a calling agent can pipe it directly. Prefer
+one long-lived agent (`create` returns the existing agent for a reused name)
+over creating new ones.
+
+### Start a run and keep working
+
+A local agent (a Claude Code or Codex shell, an orchestrator) does not have to
+wait out a run. Start it, go on to something else, and let the CLI report the
+ending:
+
+```sh
+plori run mate "long job" --no-wait   # returns the run id at once
+plori watch --agent mate              # one JSON line per ending; run it in the background
+plori inbox                           # what ended since you last acknowledged
+```
+
+`plori watch` holds a connection to the run-event feed and prints one JSON
+object per line, unchanged, until you stop it with Ctrl-C or SIGTERM (exit 0).
+A dropped connection is reopened with a delay that starts at one second and
+doubles to thirty, and the reconnect asks for everything after the last line it
+printed, so a restart neither loses a line nor repeats one.
+
+```json
+{"event":"run.completed","status":"completed","run_id":"…","agent_id":"…","agent_name":"mate","session_id":"…","seq":41,"at":"2026-09-11T10:00:00Z","url":"https://plori.ai/agent/…?session=…"}
+{"event":"run.awaiting_input","status":"awaiting_input","run_id":"…","pending_inputs":[{"tool_call_id":"…","kind":"approval","prompt":"…"}]}
+{"event":"run.error","status":"error","run_id":"…","error":"…"}
+```
+
+`event` is one of `run.completed`, `run.error`, `run.cancelled` and
+`run.awaiting_input`, plus `run.event` under `--events all`, which carries every
+event of every selected run in a `data` field. The flags:
+
+- `--agent <name|id>`, repeatable. Without it, every agent on the account,
+  including agents created after the watch started.
+- `--since <rfc3339>`: before the live lines, replay what ended after that
+  time. A replayed line carries `"replay": true`.
+- `--events terminal,input` (the default) or `--events all`.
+
+### Catch up in one shot
+
+`plori inbox` is the same information without a long-lived process: the runs
+that ended since your last acknowledgement, plus everything waiting on a human.
+`plori inbox --ack <run-id>` moves the watermark to that run's ending, so the
+next inbox starts after it. The watermark is local and per account, stored next
+to your credentials in `~/.config/plori/inbox.json`.
+
+### Answer what is waiting
+
+A run that pauses on a human approval reports `status: "awaiting_input"` and
+carries the rows to answer in its `pending_inputs`; `plori inputs <agent>` lists
+them per agent. An approval that gates an outward-facing write carries a
+`consent_tool` (visible in `plori inputs --json`); answering it with
+`--always-allow` also grants a standing consent so the agent stops asking for
+that tool. That is the human's call to make, not the calling agent's; on a row
+without a `consent_tool` the flag grants nothing.
+
+### Machine-readable streams
+
+`plori run --jsonl` replaces the rendered stream with one JSON object per line
+(`message_delta`, `tool_call`, `tool_result`, `step`, `awaiting_input`, `done`,
+`error`), and ends with the run result on one more line, tagged
+`"type":"result"`.
+
+`--json` (automatic when stdout is not a terminal) uses the field names the MCP
+tools return: `run_id`, `status`, `session_id`, `url`, `pending_inputs`.
+
+### Exit codes
+
+| code | meaning |
+| ---- | ------- |
+| 0 | the command succeeded; a run that was waited for completed |
+| 1 | API or runtime failure |
+| 2 | usage error |
+| 3 | missing, rejected, or expired credentials |
+| 4 | the control plane could not be reached |
+| 10 | the run is waiting on a human answer |
+| 20 | the run ended in error |
+| 30 | the run was cancelled |
+| 40 | the wait ran out with the run still going |
+
+`plori run`, `plori result --wait` (bounded by `--wait-seconds`) and
+`plori watch` all report these codes. Waiting goes through the session socket,
+so exit 4 means the CLI could not watch the run, not that the run failed: the
+run keeps going on the server either way.
+Exit 3 and exit 4 also print one JSON object on stdout,
+`{"error":"…","code":"auth"}` or `{"error":"…","code":"connect"}`, so a caller
+reading the stream sees why it stopped.
+
+### What not to use
 
 `plori attach` is for a human at a terminal: it takes over the keyboard and
 expects someone to answer approvals. A calling agent should stay on
-`run`/`result`/`inputs`/`answer`, which are one-shot and parse as JSON. If you
-only want to watch a session, `plori attach --read-only` is the scriptable
-form, and redirecting either stdin or stdout already selects it.
+`run`/`result`/`watch`/`inbox`/`inputs`/`answer`, which either parse as JSON or
+stream JSON lines. If you only want to follow one session's output,
+`plori attach --read-only` is the scriptable form, and redirecting either stdin
+or stdout already selects it.
 
 Wire-level acceptance cases live in the godog UAT suite at [`uat/`](../uat/) (`make uat`).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@plori/cli",
   "description": "plori (plori.ai): a cloud AI agent with its own persistent environment - durable disk, real CLI tools, and memory. The official plori CLI.",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "license": "MIT",
   "homepage": "https://plori.ai",
   "repository": {
@@ -26,10 +26,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@plori/cli-darwin-arm64": "0.3.2",
-    "@plori/cli-darwin-x64": "0.3.2",
-    "@plori/cli-linux-x64": "0.3.2",
-    "@plori/cli-linux-arm64": "0.3.2",
-    "@plori/cli-win32-x64": "0.3.2"
+    "@plori/cli-darwin-arm64": "0.4.0",
+    "@plori/cli-darwin-x64": "0.4.0",
+    "@plori/cli-linux-x64": "0.4.0",
+    "@plori/cli-linux-arm64": "0.4.0",
+    "@plori/cli-win32-x64": "0.4.0"
   }
 }