From 8410cc6c2ca074f2a86441aeac397ae4a3a84701 Mon Sep 17 00:00:00 2001 From: btipling Date: Thu, 3 Sep 2026 05:35:16 +0000 Subject: [PATCH 1/2] docs(agents): add backend-agents durable-turn architecture row Add a backend-agents architecture statement to AGENTS.md capturing the durable-turn ownership model in timeless terms: - The Workflow run (POST /api/turns) owns the turn, independent of any attached viewport; it survives tab close / refresh / logout. A viewport attaches to a live run (hydrate from Blob + GET /api/turns/:runId/stream); unmount/switch/New/Clear/logout is detach only, never a cancel. Cancel is the explicit POST /api/turns/:runId/cancel. - Tools are steps: one 'use step' = one model round OR one tool execution OR one persist; never a mega-step, never wrap runAgentStream in a single step. - /api/agent is the legacy tests/JSON path; production turns use /api/turns (post-D17 current truth). Implements #819 (backend-agents H25). Refs #794. Docs-only; no test gate. --- AGENTS.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index f87437f1..f2d1a356 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -265,6 +265,16 @@ ops inventory). ### Vercel Workflows (backend-agents) +- **Architecture — the Workflow run owns the turn.** A durable turn is owned by + the Workflow run started at `POST /api/turns`, independent of any attached + viewport: it survives tab close / refresh / logout. A viewport **attaches** to + a live run (hydrate from Blob + `GET /api/turns/:runId/stream`); + unmount/switch/New/Clear/logout is **detach only**, never a cancel — cancel is + the explicit `POST /api/turns/:runId/cancel`. **Tools are steps:** one + `'use step'` = one model round **or** one tool execution **or** one persist — + never a mega-step, never wrap `runAgentStream` in a single step. Inference is + server-side: production turns use `/api/turns`; `/api/agent` is the legacy + tests/JSON path. - **Wiring ships by Git deploy:** `workflow` dependency + `withWorkflow(nextConfig)` in `next.config.js`; `"use workflow"` fixtures/xhr live server-side (`lib/workflows/*`, `app/api/workflows/smoke`). From 9f00b3e99fb82cd88e17d7e36b187625a674fd35 Mon Sep 17 00:00:00 2001 From: btipling Date: Thu, 3 Sep 2026 05:47:52 +0000 Subject: [PATCH 2/2] docs(agents): align Workflows step grain with toolExecuteStep batch MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace “one tool execution” with the feature-divide grain: one 'use step' is one model round or one toolExecuteStep (one model round's toolCalls / waves) or one persist. Punch-list fix for PR #930 review. Refs #819. Co-authored-by: Bjorn --- AGENTS.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f2d1a356..579e7041 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -271,8 +271,9 @@ ops inventory). a live run (hydrate from Blob + `GET /api/turns/:runId/stream`); unmount/switch/New/Clear/logout is **detach only**, never a cancel — cancel is the explicit `POST /api/turns/:runId/cancel`. **Tools are steps:** one - `'use step'` = one model round **or** one tool execution **or** one persist — - never a mega-step, never wrap `runAgentStream` in a single step. Inference is + `'use step'` = one model round **or** one **`toolExecuteStep` (one model + round's `toolCalls` / waves)** **or** one persist — never a mega-step, never + wrap `runAgentStream` in a single step. Inference is server-side: production turns use `/api/turns`; `/api/agent` is the legacy tests/JSON path. - **Wiring ships by Git deploy:** `workflow` dependency + `withWorkflow(nextConfig)`