From 627451cd943ab7df525258ac29947ca9d02c6ee5 Mon Sep 17 00:00:00 2001 From: Ramnique Singh <30795890+ramnique@users.noreply.github.com> Date: Thu, 2 Jul 2026 14:19:24 +0530 Subject: [PATCH] =?UTF-8?q?docs(x):=20stage=207=20resolved=20=E2=80=94=20d?= =?UTF-8?q?ocument=20the=20code-mode=20runs=20carve-out?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Decision: defer code-mode unification; no deletions. The legacy runs runtime (runs/, AgentRuntime/streamAgent, runs:* IPC, App.tsx legacy tab state) remains solely for code-mode sessions. AGENTS.md gets the authoritative carve-out section: what stays and why, the no-new-callers rule (headless work uses agents/headless.ts), the temporary fallbacks that die with unification, and the scoped future project (rowboat-mode code prompts as composition turns; direct-mode ACP streams as a delegated turn kind). Turn-runtime design doc status updated to implemented-and-live. Co-Authored-By: Claude Fable 5 --- AGENTS.md | 27 +++++++++++++++++++ .../packages/core/docs/turn-runtime-design.md | 6 ++--- 2 files changed, 30 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9a9b0a73..0b40683a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -58,6 +58,33 @@ session ids are auto-detected. This is the intended way to see "what did the model actually receive" — the raw JSONL deliberately stores structural facts and references, never the derived wire form. +## The legacy runs runtime is code-mode-only + +The old runs runtime (`packages/core/src/runs/`, `AgentRuntime`/`streamAgent` +in `packages/core/src/agents/runtime.ts`, the `runs:*` IPC channels, and the +renderer's legacy chat-tab state machine in `App.tsx`) remains in the tree +**solely for code-mode sessions** — a deliberate, documented carve-out: + +- A code session IS a run (`sessionId === runId`). Direct-mode prompts drive + an external ACP agent and hand-assemble `code-run-event`s into the run log + (`code-mode/sessions/service.ts`); rowboat-mode code tabs go through + `runs:createMessage` → the old `AgentRuntime` loop. +- Everything else — main chat, background tasks, live notes, knowledge + pipelines, scheduled agents — runs on turns/sessions. Do NOT add new + callers of `createRun`/`createMessage`/`streamAgent`; headless work uses + `packages/core/src/agents/headless.ts` (`startHeadlessAgent`/ + `runHeadlessAgent`). +- Temporary bridges that die when code-mode is unified: the renderer + transcript loader's `runs:fetch` fallback (`lib/agent-transcript.ts`), the + `runs:downloadLog` fallback in the chat sidebar, and the `notify-user` + gate's `fetchRun` fallback (`application/lib/builtin-tools.ts`). +- The remaining migration (designed but deferred): port code sessions onto + sessions/turns — rowboat-mode prompts become normal turns with + `codeMode`/`codeCwd` composition (already supported by the agent + resolver's composition overrides), direct-mode prompts become a delegated + turn kind carrying opaque code events. That project deletes `runs/` + entirely. + ## Invariants to respect - Turn/session files are **append-only**; reducers reject impossible diff --git a/apps/x/packages/core/docs/turn-runtime-design.md b/apps/x/packages/core/docs/turn-runtime-design.md index 091168f2..d199fabe 100644 --- a/apps/x/packages/core/docs/turn-runtime-design.md +++ b/apps/x/packages/core/docs/turn-runtime-design.md @@ -1,8 +1,8 @@ # Turn Runtime Technical Specification -Status: design complete for the turn layer, amended after review for session -integration: context references, revised crash-recovery semantics, and a -distinguishable model-call-limit outcome. No implementation exists yet. The +Status: implemented and live. All chat, background, and knowledge callers +run on this runtime; the legacy runs runtime remains only for code-mode +sessions (see the carve-out section in the repo-root `AGENTS.md`). The companion session layer is specified in `session-design.md`. This document specifies a new turn-oriented agent loop for `@x/core`. It is