From 6508e75a626740181a6c3989d59cd57452db7dd4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=9B=B7=E7=94=B5=E8=8A=BD=E8=A1=A3?= Date: Sun, 19 Apr 2026 01:25:19 -0400 Subject: [PATCH] docs: align README and prompt docs with the real runtime semantics MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README described target-state features that the previous migration left half-implemented. Now that the runtime actually matches the promise, the docs can stop overselling: agent messaging is described as the real live-steer + inbox flow, approvals as the beforeToolCall gate that actually blocks destructive tools, sessions as the transformContext-driven compaction plus rotation. The architecture bullet list grows to name the seams that landed across this migration — the pi contract wiring, the approval gate, the workspace lock model, and the stripped startup mutations — so the README reads like documentation rather than roadmap. The filesystem prompt doc (`files.en.md`) adds the missing preamble: every bash/write/edit succeeds into work_products automatically, and the API endpoints below are only needed for non-filesystem deliverables. Agents were routinely posting duplicate work products because nothing told them the projection already ran. --- README.md | 11 +++++++---- src/main/prompt-builder/api-docs/files.en.md | 5 +++++ 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 958bed64..05e816be 100644 --- a/README.md +++ b/README.md @@ -64,7 +64,7 @@ CEO builds the org chart from one goal.

### Agent messaging -Threads and DMs between agents. Messages land in each recipient's transcript as pi `AgentMessage` turns. +Threads and DMs between agents. Direct / department / project / company / incident channels resolve to wake targets; each message lands in the recipient's transcript as a pi `AgentMessage` turn. If the recipient is already running, the message is delivered live via pi's steer queue; if not, it waits in the inbox until the next prepareRun.

Agent messaging @@ -78,7 +78,7 @@ Goals break into tasks. Agents pick them up, report progress, escalate blockers.

### Approvals -Hiring, deliverables, plan/scope/strategy reviews, budget overrides, production deploys pause for the board. +Hiring, deliverables, plan/scope/strategy reviews, budget overrides, production deploys pause for the board. The same approval policy gates the agent's destructive tools (`bash` / `write` / `edit`) via pi's `beforeToolCall` hook, so a pending approval stops file and shell mutations instead of just flagging them after the fact.

Approvals @@ -164,9 +164,12 @@ src/ - SQLite local; no external services. - `contextIsolation: true`, `nodeIntegration: false`, Zod-validated IPC. -- Worker constructs `new Agent({...})` from `@mariozechner/pi-agent-core` directly. -- Sessions persist as `session_entries`; auto-compact via `shouldCompact` / `compact`. +- Worker constructs `new Agent({...})` from `@mariozechner/pi-agent-core` with the full contract: `sessionId`, `thinkingLevel`, and the `beforeToolCall` / `afterToolCall` / `transformContext` hooks proxied back to `RuntimeBridge` on main. +- Sessions persist as `session_entries`; long transcripts auto-compact at LLM-call time via a pure `transformContext` reducer, and rotate at the long-cycle boundary. +- `beforeToolCall` enforces the approval gate plus thread wait-state guard at the tool-execution layer; mid-run messages reach live agents through pi's steering queue. +- Workspace locks are single-writer-per-repo — every resolved workspace is held exclusively for the duration of the run; contenders queue on the wakeup table. - Thread runtime (`conversation_threads` / `conversation_events` / `thread_wait_states`) sits above pi's `AgentMessage` stream. +- Startup only runs schema migrations plus `interruptStaleRuns`; all other data-repair lives at the transition point or in explicit maintenance paths. --- diff --git a/src/main/prompt-builder/api-docs/files.en.md b/src/main/prompt-builder/api-docs/files.en.md index 27625baa..d609880f 100644 --- a/src/main/prompt-builder/api-docs/files.en.md +++ b/src/main/prompt-builder/api-docs/files.en.md @@ -1,3 +1,8 @@ +### Filesystem artifacts (auto-registered) +Every successful `write`, `edit`, or `bash` tool call is projected into the task's work_products automatically — you do NOT need to POST /api/work-products for files you create in the workspace. The projector reads workspace paths for `write` / `edit` directly and scans `git status` after `bash`; the desktop UI shows new/modified files without any extra API call. + +Use the document / work-product endpoints below only for non-filesystem deliverables (URLs, PRs, external services) or to enrich an auto-registered file (status, reviewState, summary). + ### Create a Document POST /api/companies/{{companyId}}/documents Body: {