From 5284ed4806c30cb4661b7242905075a372b7b4e0 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Mon, 15 Jun 2026 23:55:40 +0800
Subject: [PATCH] docs(agent): sync inject wording + resume error wording with
 code (review #34)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- agent/README: the inject() line said "without triggering a turn",
  regressing the #32 turn-enclosure model. Restored the running-vs-idle
  wording (idle inject wraps a one-shot injection turn; ADR 0017) to match
  the interface JSDoc.
- agent-loop resume() JSDoc said "throws a typed error" but the code
  throws a plain Error (consistent with the sibling assertAgentIdFree
  throw). Softened to "rejects with a clear error" — no behavior change;
  plain Error is intentional (no consumer needs a structured code here).
---
 packages/agent-loop/src/index.ts | 2 +-
 packages/agent/README.md         | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/agent-loop/src/index.ts b/packages/agent-loop/src/index.ts
index 355c610989..a1efc78d56 100644
--- a/packages/agent-loop/src/index.ts
+++ b/packages/agent-loop/src/index.ts
@@ -114,7 +114,7 @@ export class AgentLoop extends Service implements AgentFactory {
    * continue), and starts a fresh agent on it. The live session id is the
    * resumed id, NOT `${agentId}-session`.
    *
-   * Requires `ctx.sessionPersistence`; throws a typed error if it is not
+   * Requires `ctx.sessionPersistence`; rejects with a clear error if it is not
    * configured. NOT hard-injected (that would make non-persistent demos pend
    * forever) — callers that need resume (ACP) inject `sessionPersistence`, so
    * by the time this runs the service exists.
diff --git a/packages/agent/README.md b/packages/agent/README.md
index 5bffc4681b..73914ea05b 100644
--- a/packages/agent/README.md
+++ b/packages/agent/README.md
@@ -53,7 +53,7 @@ The handle every plugin programs against:
 
 - `agent.send(content, options?)` — queue a message; starts a turn when idle
 - `agent.steer(content, options?)` — steer a running turn (inject between steps); behaves like `send` when idle
-- `agent.inject(content, options?)` — inject in-session context without triggering a turn (context/message event); next request sees it
+- `agent.inject(content, options?)` — inject in-session context (context/message event); the next request sees it. Does not run the model. While a turn is open it joins that turn; while idle it is wrapped in a one-shot `injection` turn so every event stays turn-enclosed (ADR 0017)
 - `agent.abort(reason?)` — abort the in-flight step
 - `agent.session`, `agent.status`, `agent.options`, `agent.id`