@coder/ai-sdk-agent 0.8.0 → 0.9.1

package/README.md

@@ -223,9 +223,11 @@ conversation with server‑side history). `agent.chatId` is the current chat id.
 - `agent.interrupt({ signal? })` — interrupt an in‑flight generation.
 - `agent.archive({ signal? })` — archive the underlying chat (cleanup; see [Cleanup](#cleanup)).
 - `agent.listModels()` — list the deployment's model configs, so you don't have to guess the `model` hint.
-- Resume a prior chat: `new CoderAgent({ …, chatId: "…" })` — see
-  [Durable workflows](#durable-workflows-persist-resume-recover) for the full
-  resumption how‑to.
+- Resume a prior chat: `new CoderAgent({ …, chatId: "…" })` — optionally with
+  `lastSeenMessageId` (the persisted resume cursor, read from
+  `agent.lastSeenMessageId`) to skip the resumed turn's pre‑prompt history
+  probe. See [Durable workflows](#durable-workflows-persist-resume-recover)
+  for the full resumption how‑to.
 
 Interrupting is asynchronous on the server: `interrupt()` resolves as soon as the
 interrupt is acknowledged, and the run keeps winding down for a few seconds
@@ -321,7 +323,9 @@ await agent.generate({ prompt: "…" });
 // e.g. attribute where the turn spent its time:
 for (const ev of events) {
   if (ev.type === "http:response")
-    console.log(`${ev.method} ${ev.path} → ${ev.status} in ${ev.durationMs.toFixed(0)}ms`);
+    console.log(
+      `${ev.op}: ${ev.method} ${ev.path} → ${ev.status} in ${ev.durationMs.toFixed(0)}ms`,
+    );
   if (ev.type === "ws:event" && ev.event.type === "action_required")
     console.log(`tool calls arrived at +${ev.timestamp - events[0]!.timestamp}ms`);
   if (ev.type === "segment:settle")
@@ -335,12 +339,12 @@ such as a message's `created_at`, for delivery‑lag measurements):
 
 | event            | when                                                | payload (besides `timestamp`)                                                                                                                                                                                                                                                     |
 | ---------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `http:request`   | a REST request is sent                              | `id` (correlates the pair), `method`, `path`                                                                                                                                                                                                                                      |
-| `http:response`  | response headers arrive (incl. non‑2xx, `ok:false`) | `id`, `method`, `path`, `status`, `ok`, `durationMs`                                                                                                                                                                                                                              |
-| `http:error`     | the fetch itself rejects (network failure, abort)   | `id`, `method`, `path`, `message`, `durationMs`                                                                                                                                                                                                                                   |
+| `http:request`   | a REST request is sent                              | `id` (correlates the pair), `op` (the client operation, e.g. `"createChatMessage"`), `method`, `path`                                                                                                                                                                             |
+| `http:response`  | response headers arrive (incl. non‑2xx, `ok:false`) | `id`, `op`, `method`, `path`, `status`, `ok`, `durationMs`                                                                                                                                                                                                                        |
+| `http:error`     | the fetch itself rejects (network failure, abort)   | `id`, `op`, `method`, `path`, `message`, `durationMs`                                                                                                                                                                                                                             |
 | `ws:dial`        | a stream connection attempt starts                  | `chatId`, `reader` (identifies the `streamChatEvents` call), `attempt` (1‑based per reader, increments per redial), `url`                                                                                                                                                         |
 | `ws:open`        | the WebSocket handshake completes                   | `chatId`, `reader`, `attempt`                                                                                                                                                                                                                                                     |
-| `ws:event`       | a decoded stream event arrives                      | `chatId`, `reader`, `attempt`, `event` (the decoded `ChatStreamEvent`, by reference — don't mutate)                                                                                                                                                                               |
+| `ws:event`       | a decoded stream event arrives                      | `chatId`, `reader`, `attempt`, `event` (the decoded `ChatStreamEvent`, by reference — don't mutate), `forwarded` (the reader's replay verdict)                                                                                                                                    |
 | `ws:close`       | the connection ends (exactly one per dial)          | `chatId`, `reader`, `attempt`, `code`/`reason` when the server/network closed it; absent when the reader closed it (settle, teardown, redial)                                                                                                                                     |
 | `ws:error`       | a socket error or unparseable frame                 | `chatId`, `reader`, `attempt`, `message`                                                                                                                                                                                                                                          |
 | `ws:redial`      | a dropped connection is about to be redialed        | `chatId`, `reader`, `attempt` (the ended connection), `consecutiveFailures`, `maxConsecutiveFailures`, `backoffMs`                                                                                                                                                                |
@@ -356,9 +360,24 @@ Semantics worth knowing:
 - **No secrets** — events carry no headers and no tokens (auth travels in the
   `Coder-Session-Token` header, which is deliberately excluded); `path`/`url`
   never contain credentials.
-- `ws:event` fires at arrival, **before** replay dedup: after a redial, chatd's
-  replay of the in‑progress episode is visible here (correlate with `reader`/`attempt`)
-  even though the reader suppresses the duplicates it forwards to the turn.
+- `http:*` events name their operation: `op` is the public `CoderChatClient`
+  method performing the exchange (`"createChat"`, `"createChatMessage"`,
+  `"getMessages"`, `"submitToolResults"`, … — the `CoderClientOperation`
+  union), so per‑operation classification never has to reverse‑engineer
+  `path`. `method`/`path` stay for generic consumers; `archiveChat` stamps its
+  own `op` even though it issues the same `PATCH` as `updateChat`.
+- `ws:event` fires at arrival: after a redial, chatd's replay of the
+  in‑progress episode is visible here (correlate with `reader`/`attempt`),
+  stamped with the reader's own replay verdict — `forwarded: false` exactly on
+  the duplicate deltas the reader suppresses from the turn, so subscribers
+  never re‑derive the episode filter.
+- `forwarded` does **not** reflect snapshot dedup: repeated or revised
+  `message` snapshots are always `forwarded: true`, because reconciling them
+  is deliberately the consumer's job past the transport layer —
+  `TurnTranslator`'s per‑message ledger decides what a revision re‑emits, and
+  that disposition is not stamped on transport frames. Use `ws:event` for
+  span pairing and replay accounting; subscribers needing content fidelity
+  must consume model output (or `TurnTranslator`), not transport frames.
 - Every `ws:*` event carries `reader` — a monotonic id for the
   `streamChatEvents` call (reader) behind the connection, allocated from one
   process‑wide counter so it stays unique across model and client instances.
@@ -436,6 +455,25 @@ for a few seconds, during which archiving 409s — `archive()` retries those 409
 `settleRetryDelayMs`) and rethrows the last one if the chat never settles. Any
 other failure, including your own abort, rethrows immediately.
 
+`archive()` and `interrupt()` target the session's chat — or, after the session
+was dropped (`resetSession()`, or the automatic discard after a fresh‑chat
+stream failure — see [Handling errors](#handling-errors)), the **last‑known
+chat id** (`agent.lastKnownChatId`), so a stranded chat is still cleaned up
+instead of leaking. Generation never uses the last‑known id: a turn after a
+drop creates a fresh chat as always. Every chat stranded by an _automatic_
+discard is also recorded on a ledger (`agent.strandedChatIds`, oldest first) —
+with `maxRetries` several failed attempts can strand one chat each while only
+the final attempt's error surfaces — and one `archive()` retires them all,
+oldest first, alongside its primary target. Both methods report what they
+acted on instead of silently no‑oping: `archive()` resolves
+`{ archived: true, chatId, archivedChatIds }` (each archived id is cleared as
+a cleanup target) or `{ archived: false }` when no chat exists at all;
+`interrupt()` resolves `{ interrupted: true, chatId }` /
+`{ interrupted: false }` the same way. Deliberate abandonment is different:
+`resetSession()` does **not** add to the ledger (you may want that chat kept),
+so after a manual reset the old chat is targetable only until a new chat
+supersedes `lastKnownChatId`.
+
 To make cleanup ride scope exit instead of a `finally` you have to remember, the
 agent is an **async disposable**:
 
@@ -469,7 +507,11 @@ carry structured detail you can branch on:
   repeat (workspace/MCP tooling, fresh attachment uploads); otherwise it is
   `false` — a retry would resubmit the prompt as a new user turn and could
   duplicate those effects. A failure mid‑`stream()` surfaces on the stream,
-  outside the retry wrapper. The last transport failure is in `cause`.
+  outside the retry wrapper. The last transport failure is in `cause`, and
+  `chatId` names the chat the failed turn had created or attached to (absent
+  when it failed before a chat existed) — after the fresh‑chat discard the
+  chat still exists server‑side, and `archive()` keeps targeting it via
+  `agent.lastKnownChatId` ([Cleanup](#cleanup)).
 
 ```ts
 import { CoderApiError, CoderChatError } from "@coder/ai-sdk-agent";
@@ -843,24 +885,25 @@ sequence pinpoints _where_ a turn died:
 
 `CoderAgentSettings`:
 
-| field                             | description                                                                                      |
-| --------------------------------- | ------------------------------------------------------------------------------------------------ |
-| `client` \| (`baseUrl` + `token`) | connection (one or the other; `baseUrl`/`token` default from `CODER_URL`/`CODER_SESSION_TOKEN`)  |
-| `organizationId`                  | org UUID that owns the chat (required)                                                           |
-| `model`                           | model hint: UUID, `provider:model`, model id, or display‑name substring                          |
-| `instructions`                    | system prompt                                                                                    |
-| `tools`                           | AI SDK `ToolSet` (client‑executed)                                                               |
-| `workspaceId`                     | bind the chat to a Coder workspace (enables workspace‑scoped tools)                              |
-| `workspaceFiles`                  | adapter enabling `uploadToWorkspace()` (write files to the workspace FS)                         |
-| `mcpServerIds`                    | server‑side MCP servers to enable                                                                |
-| `planMode`                        | enable plan mode (`"plan"`)                                                                      |
-| `stopWhen`                        | AI SDK stop condition(s); default `stepCountIs(64)`                                              |
-| `maxRetries`                      | default `0` — SDK retries can duplicate server‑side turns; override with care                    |
-| `requestTimeoutMs`                | per‑turn time budget (ms); interrupts the run and rejects (`kind: "timeout"`) instead of hanging |
-| `onTransportEvent`                | observability hook for typed transport events (see [Observability](#observability))              |
-| `settleDeadlineMs`                | overall deadline for bounded cleanup (`archive()` 409 retries, disposal); default 15 000         |
-| `settleRetryDelayMs`              | pause between `archive()` retries while the chat settles; default 1000                           |
-| `chatId`                          | resume an existing chat                                                                          |
+| field                             | description                                                                                                        |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `client` \| (`baseUrl` + `token`) | connection (one or the other; `baseUrl`/`token` default from `CODER_URL`/`CODER_SESSION_TOKEN`)                    |
+| `organizationId`                  | org UUID that owns the chat (required)                                                                             |
+| `model`                           | model hint: UUID, `provider:model`, model id, or display‑name substring                                            |
+| `instructions`                    | system prompt                                                                                                      |
+| `tools`                           | AI SDK `ToolSet` (client‑executed)                                                                                 |
+| `workspaceId`                     | bind the chat to a Coder workspace (enables workspace‑scoped tools)                                                |
+| `workspaceFiles`                  | adapter enabling `uploadToWorkspace()` (write files to the workspace FS)                                           |
+| `mcpServerIds`                    | server‑side MCP servers to enable                                                                                  |
+| `planMode`                        | enable plan mode (`"plan"`)                                                                                        |
+| `stopWhen`                        | AI SDK stop condition(s); default `stepCountIs(64)`                                                                |
+| `maxRetries`                      | default `0` — SDK retries can duplicate server‑side turns; override with care                                      |
+| `requestTimeoutMs`                | per‑turn time budget (ms); interrupts the run and rejects (`kind: "timeout"`) instead of hanging                   |
+| `onTransportEvent`                | observability hook for typed transport events (see [Observability](#observability))                                |
+| `settleDeadlineMs`                | overall deadline for bounded cleanup (`archive()` 409 retries, disposal); default 15 000                           |
+| `settleRetryDelayMs`              | pause between `archive()` retries while the chat settles; default 1000                                             |
+| `chatId`                          | resume an existing chat                                                                                            |
+| `lastSeenMessageId`               | resume cursor for `chatId` (persist `agent.lastSeenMessageId`) — skips the resumed turn's pre‑prompt history probe |
 
 The `model` hint resolves against the deployment's model configs in order: a
 config UUID is used as‑is, then an exact `provider:model` match, an exact model
@@ -903,7 +946,9 @@ Two facts make the pattern work:
 
 - **All chat state lives on the Coder server.** Messages, tool activity, the
   run itself — none of it is in your process. The only durable thing a
-  workflow has to carry between steps is **`agent.chatId`: a string.**
+  workflow has to carry between steps is **`agent.chatId`: a string** — plus,
+  optionally, **`agent.lastSeenMessageId`: the resume cursor**, which saves the
+  resumed turn one serial round‑trip (below).
 - **`CoderAgent` can't ride a `fetch`‑shim durability layer** (it talks REST +
   WebSocket through its own client), so each turn runs **inside** a durable
   step — and the checkpointed chat id is the thread between steps.
@@ -916,18 +961,29 @@ on another machine, hours apart, retried after failures.
 ```ts
 import { CoderAgent, type CoderTransportEvent } from "@coder/ai-sdk-agent";
 
+interface WorkflowCheckpoint {
+  chatId: string;
+  /** The resume cursor — pairs with chatId, never persisted without it. */
+  lastSeenMessageId?: number;
+}
+
 // Any durable KV your engine gives you: step state, a job row, a DB table.
 declare const checkpoints: {
-  get(workflowId: string): Promise<string | undefined>;
-  set(workflowId: string, chatId: string): Promise<void>;
+  get(workflowId: string): Promise<WorkflowCheckpoint | undefined>;
+  set(workflowId: string, checkpoint: WorkflowCheckpoint): Promise<void>;
 };
 
 export async function runTurn(workflowId: string, prompt: string): Promise<string> {
+  const checkpoint = await checkpoints.get(workflowId); // undefined on the first step → the turn creates the chat
   const agent = new CoderAgent({
     baseUrl: process.env.CODER_URL!,
     token: process.env.CODER_SESSION_TOKEN!, // read per step — never checkpoint or log it
     organizationId: process.env.CODER_ORG_ID!,
-    chatId: await checkpoints.get(workflowId), // undefined on the first step → the turn creates the chat
+    chatId: checkpoint?.chatId,
+    // The previous step's cursor lets this step skip its pre-prompt history
+    // probe; absent (first resume, older checkpoints), the turn seeds it from
+    // the chat's newest message instead — one extra GET, same result.
+    lastSeenMessageId: checkpoint?.lastSeenMessageId,
     requestTimeoutMs: 300_000, // always bound workflow steps — see below
     onTransportEvent: observe, // per-step telemetry — see below
   });
@@ -946,9 +1002,19 @@ export async function runTurn(workflowId: string, prompt: string): Promise<strin
     // still persist the id, or the retried step orphans a live chat and its
     // partial effects. Exception: after an exhausted stream failure on a
     // chat this very call created, the SDK has already discarded the dead
-    // session (agent.chatId is undefined) and nothing is written — see the
+    // session (agent.chatId is undefined) and nothing is written — the thrown
+    // CoderStreamError's chatId still names the stranded chat, and
+    // agent.archive() retires it via agent.lastKnownChatId — see the
     // CoderStreamError notes below for what retrying means then.
-    if (agent.chatId) await checkpoints.set(workflowId, agent.chatId);
+    if (agent.chatId) {
+      const next: WorkflowCheckpoint = { chatId: agent.chatId };
+      // The cursor is optional sugar: persist it when a turn established one
+      // (a turn that failed before streaming may not have), skip it otherwise.
+      if (agent.lastSeenMessageId !== undefined) {
+        next.lastSeenMessageId = agent.lastSeenMessageId;
+      }
+      await checkpoints.set(workflowId, next);
+    }
   }
 }
 ```
@@ -981,12 +1047,16 @@ await archiveWorkflowChat("wf-1042");
 
 What resuming does (and doesn't do):
 
-- **Construction is free.** `new CoderAgent({ …, chatId })` performs no I/O
-  and no validation — a bad or archived id fails the _turn_, not the
-  constructor.
+- **Construction is free.** `new CoderAgent({ …, chatId })` performs no I/O —
+  a bad or archived id fails the _turn_, not the constructor. (The one
+  exception is local validation of `lastSeenMessageId`: a cursor that isn't a
+  positive integer, or arrives without its `chatId`, throws immediately.)
 - **The first resumed turn seeds its cursor** from the chat's newest message
   (one single‑message history probe), so it streams only its own events —
-  it never re‑absorbs earlier turns' content or usage.
+  it never re‑absorbs earlier turns' content or usage. Supplying the
+  checkpointed `lastSeenMessageId` skips that probe: the previous step already
+  knew the cursor, so the resumed prompt goes out without any pre‑prompt
+  round‑trip.
 - **Re‑supply process‑local configuration.** Client `tools` live in your
   process, not on the server, so each step that expects tool calls must pass
   them again. The workspace binding is the opposite: fixed at creation,
@@ -994,7 +1064,10 @@ What resuming does (and doesn't do):
 - **Sessions stay single‑flight across the whole system**, not just within one
   process: run steps strictly sequentially per chat. A second job posting to
   the same chat queues behind the live run and burns its own
-  `requestTimeoutMs` waiting.
+  `requestTimeoutMs` waiting — it attributes nothing of the live run's output
+  to itself (its window opens only when its own queued prompt materializes),
+  and if it times out first, it withdraws its queued prompt rather than
+  leaving it to run unattended.
 
 ### Let the SDK absorb drops — and handle what it re‑throws
 
@@ -1063,12 +1136,15 @@ try {
   the dead session so a retry — `maxRetries` or a re‑run step — starts clean
   on a fresh chat. The discard happens for _every_ chat the failed turn
   itself created — **including the effectful, `isRetryable: false` case**:
-  the id is gone, the `finally` checkpoint writes nothing, and the
-  interrupted chat — whose workspace/MCP tools may already have acted —
-  becomes an unacknowledged orphan for the reconciliation sweep (below). A
-  retried step then starts a fresh chat that has _not_ seen the orphan's
-  effects: gate that retry on the same idempotency judgment as any
-  re‑submission. **On a resumed chat it is always `isRetryable: false`:**
+  `agent.chatId` is `undefined` and the `finally` checkpoint writes nothing —
+  but the stranded chat is not nameless: the error's **`chatId`** field names
+  it, and `interrupt()`/`archive()` keep targeting it via
+  `agent.lastKnownChatId` ([Cleanup](#cleanup)), so the step's error path can
+  retire the orphan directly — or checkpoint `err.chatId` for the
+  reconciliation sweep (below) when its workspace/MCP effects need
+  reconciling first. A retried step then starts a fresh chat that has _not_
+  seen the orphan's effects: gate that retry on the same idempotency judgment
+  as any re‑submission. **On a resumed chat it is always `isRetryable: false`:**
   re‑running the step resubmits the same prompt as a _new user turn_, with the
   failed attempt's partial output still in history (usually fine — the model
   sees its own aborted attempt), and any workspace/MCP tool effects that ran
@@ -1117,9 +1193,11 @@ checkpoint:
   turns into resuming the dead chat.)
 - **Crashed after the checkpoint** — the chat is resumable, but don't just
   resubmit. The crashed attempt's run may still be live server‑side, and a
-  resumed turn seeds its message cursor _before_ submitting — whatever the
-  old run commits after that point would be absorbed into the resumed turn's
-  output and usage. A crash _inside one of your client tools_ is worse: the
+  resubmission then queues behind it: nothing the old run commits is
+  attributed to the resumed turn (its window opens only at its own queued
+  prompt's materialization), but the step burns its `requestTimeoutMs`
+  waiting for the old run to finish first — and a timeout withdraws the
+  queued prompt again. A crash _inside one of your client tools_ is worse: the
   chat is paused in `requires_action`, where new messages wait forever — and
   if the tool's external effect committed before the crash, that pause is the
   only pending record of it, so reconcile the tool ledger **before** any