@coder/ai-sdk-agent 0.7.2 → 0.9.0

package/README.md

@@ -196,6 +196,15 @@ Pass a Coder **API token** or **session token** as `token`; it is sent as the
 `Coder-Session-Token` header (REST) and used to authenticate the streaming WebSocket. Create
 a token with `coder tokens create`, or reuse your CLI session.
 
+When `baseUrl`/`token` are not passed, they default from the `CODER_URL` and
+`CODER_SESSION_TOKEN` environment variables (the same convention as
+`@coder/ai-sdk-sandbox`'s transports); explicit settings win over the
+environment. With the variables set, connection config disappears entirely:
+
+```ts
+const agent = new CoderAgent({ organizationId }); // uses CODER_URL + CODER_SESSION_TOKEN
+```
+
 You can also pass a pre‑built client:
 
 ```ts
@@ -312,7 +321,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")
@@ -326,12 +337,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`                                                                                                                                                                |
@@ -347,9 +358,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.
@@ -427,6 +453,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**:
 
@@ -460,7 +505,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";
@@ -675,7 +724,8 @@ Coder servers — no experimental endpoints.
   named "80" and never resolve; serve the preview on a higher port.
 
 The preview helpers call non‑chat endpoints, so they need `baseUrl` + `token`
-credentials — pass them alongside `client` if you construct one yourself.
+credentials — pass them alongside `client` if you construct one yourself (or
+let them default from `CODER_URL`/`CODER_SESSION_TOKEN`).
 
 ## Workspaces & quota
 
@@ -835,7 +885,7 @@ sequence pinpoints _where_ a turn died:
 
 | field                             | description                                                                                      |
 | --------------------------------- | ------------------------------------------------------------------------------------------------ |
-| `client` \| (`baseUrl` + `token`) | connection (one or the other)                                                                    |
+| `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                                                                                    |
@@ -936,7 +986,9 @@ 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);
   }
@@ -1053,12 +1105,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

package/dist/index.d.ts

@@ -344,12 +344,27 @@ interface TransportEventBase {
     /** Wall-clock observation time in ms since epoch (`Date.now()`). */
     timestamp: number;
 }
+/**
+ * Names the `CoderChatClient` operation performing an HTTP exchange (issue
+ * #112). The public client method names are the stable vocabulary, so
+ * subscribers can classify per-operation timings without reverse-engineering
+ * `path` (whose API prefix is private and may change). New client methods
+ * extend this union; treat unrecognized values as "some other operation"
+ * rather than matching exhaustively.
+ */
+type CoderClientOperation = "listModelConfigs" | "resolveModelConfigId" | "createChat" | "getChat" | "createChatMessage" | "getMessages" | "submitToolResults" | "interruptChat" | "updateChat" | "archiveChat" | "uploadChatFile" | "getChatFile";
 interface HttpTransportEventBase extends TransportEventBase {
     /**
      * Correlates a request with its response/error. Monotonically increasing
      * per client instance.
      */
     id: number;
+    /**
+     * The client operation performing this exchange — the public
+     * `CoderChatClient` method name. `archiveChat` stamps its own operation
+     * even though it issues the same `PATCH` as `updateChat`.
+     */
+    op: CoderClientOperation;
     /** HTTP method, e.g. `POST`. */
     method: string;
     /**
@@ -415,14 +430,31 @@ interface StreamOpenTransportEvent extends StreamTransportEventBase {
 }
 /**
  * A decoded stream event arrived on the wire. Emitted at arrival time for
- * every event in a frame batch, BEFORE replay dedup — after a redial, chatd's
- * replay of the in-progress episode is visible here even though the reader
- * suppresses the duplicates it forwards. `event` is the decoded object by
- * reference (no copy): do not mutate it.
+ * every event in a frame batch — after a redial, chatd's replay of the
+ * in-progress episode is still visible here, stamped with the reader's own
+ * replay verdict (`forwarded`). `event` is the decoded object by reference
+ * (no copy): do not mutate it.
  */
 interface StreamEventTransportEvent extends StreamTransportEventBase {
     type: "ws:event";
     event: ChatStreamEvent;
+    /**
+     * The reader's replay disposition for this frame (issue #111): `false`
+     * exactly when the episode filter suppresses it from the consumption path —
+     * a redial's replay of an in-progress delta at or below the last yielded
+     * `seq` of the same episode — and `true` when the reader forwards it to its
+     * consumer. It is a dedup verdict, not a delivery receipt: a consumer
+     * tearing down mid-queue can still discard a forwarded frame.
+     *
+     * Snapshot dedup is deliberately NOT reflected here: repeated or revised
+     * `message` snapshots are always `forwarded: true`, because reconciling
+     * them is the consumer's job past the transport layer — TurnTranslator's
+     * per-message emitted-content ledger decides what a revision re-emits.
+     * That disposition is not stamped on transport frames; subscribers needing
+     * content fidelity must consume model output (or TurnTranslator), not
+     * `ws:event`.
+     */
+    forwarded: boolean;
 }
 /**
  * The connection ended. Exactly one per dial: carries `code`/`reason` when
@@ -586,7 +618,10 @@ interface StreamChatEventsOptions {
  * in-progress generation attempt's `message_part` deltas from `seq` 1, so
  * parts of an episode
  * (`history_version`, `generation_attempt`) at or below the last yielded `seq`
- * are suppressed here rather than double-yielded. The iteration ends in five
+ * are suppressed here rather than double-yielded. That episode filter runs at
+ * frame arrival (not at consumption), so each frame's `ws:event` can carry
+ * the reader's own verdict as `forwarded` (issue #111) while `timestamp`
+ * keeps meaning arrival time. The iteration ends in five
  * ways: `signal` aborting (clean return), a non-transient 4xx upgrade
  * rejection (terminal {@link CoderApiError} — bad/expired token or a deleted
  * chat cannot succeed on retry, while 408/425/429 consume the redial budget),
@@ -815,18 +850,49 @@ interface ChatAttachment extends UploadedChatFile {
      */
     toFilePart(): FilePart;
 }
+/**
+ * Result of {@link CoderAgent.interrupt}: `interrupted: false` means there was
+ * no chat to interrupt (neither a live session nor a
+ * {@link CoderAgent.lastKnownChatId}) and no server call was made.
+ */
+type CoderInterruptResult = {
+    interrupted: true;
+    chatId: string;
+} | {
+    interrupted: false;
+    chatId?: undefined;
+};
+/**
+ * Result of {@link CoderAgent.archive}: `archived: false` means there was no
+ * chat to archive (neither a live session nor a
+ * {@link CoderAgent.lastKnownChatId}) and no server call was made. Failures
+ * still throw — see {@link CoderAgent.archive}. `chatId` is the primary
+ * target (the session's or last-known chat); `archivedChatIds` additionally
+ * lists every chat archived by the call, oldest first — more than one when
+ * earlier stranded chats ({@link CoderAgent.strandedChatIds}) were retired
+ * alongside it.
+ */
+type CoderArchiveResult = {
+    archived: true;
+    chatId: string;
+    archivedChatIds: string[];
+} | {
+    archived: false;
+    chatId?: undefined;
+    archivedChatIds?: undefined;
+};
 interface CoderAgentSettings<TOOLS extends ToolSet = {}> {
     /**
      * A pre-built {@link CoderChatClient}, used instead of constructing one from
      * `baseUrl`/`token`. The preview helpers ({@link CoderAgent.getPreview},
      * {@link CoderAgent.sharePreview}) call non-chat endpoints and therefore
-     * still need credentials — pass `baseUrl` + `token` alongside `client` to
-     * enable them.
+     * still need credentials — pass `baseUrl` + `token` alongside `client` (or
+     * set `CODER_URL` + `CODER_SESSION_TOKEN`) to enable them.
      */
     client?: CoderChatClient;
-    /** Coder deployment base URL, e.g. `https://dev.coder.com`. */
+    /** Coder deployment base URL, e.g. `https://dev.coder.com`. Defaults to `CODER_URL`. */
     baseUrl?: string;
-    /** Coder API/session token (sent as `Coder-Session-Token`). */
+    /** Coder API/session token (sent as `Coder-Session-Token`). Defaults to `CODER_SESSION_TOKEN`. */
     token?: string;
     fetch?: CoderChatClientOptions["fetch"];
     webSocketFactory?: CoderChatClientOptions["webSocketFactory"];
@@ -964,6 +1030,25 @@ declare class CoderAgent<TOOLS extends ToolSet = {}> implements Agent<never, TOO
     get client(): CoderChatClient;
     /** The current chatd chat id, once a turn has started. */
     get chatId(): string | undefined;
+    /**
+     * The last chat id this agent created or attached to, retained for CLEANUP
+     * even after the session was dropped — a fresh-chat stream failure discards
+     * the session ({@link CoderAgent.chatId} becomes `undefined`, so a retry
+     * starts fresh), but the failed chat still exists server-side.
+     * {@link CoderAgent.archive} and {@link CoderAgent.interrupt} fall back to
+     * this id; generation never does. Superseded when a later turn creates or
+     * attaches to another chat; cleared once {@link CoderAgent.archive}
+     * succeeds against it.
+     */
+    get lastKnownChatId(): string | undefined;
+    /**
+     * Chat ids stranded by automatic session discards and not yet cleaned up,
+     * oldest first. Each retryable fresh-chat stream failure strands one chat,
+     * so with `maxRetries` > 0 several can accumulate while only the final
+     * attempt's error (and {@link CoderAgent.lastKnownChatId}) names the
+     * newest. {@link CoderAgent.archive} retires all of them.
+     */
+    get strandedChatIds(): string[];
     generate(options: Parameters<InnerAgent<TOOLS>["generate"]>[0]): ReturnType<InnerAgent<TOOLS>["generate"]>;
     stream(options: Parameters<InnerAgent<TOOLS>["stream"]>[0]): ReturnType<InnerAgent<TOOLS>["stream"]>;
     /**
@@ -972,33 +1057,61 @@ declare class CoderAgent<TOOLS extends ToolSet = {}> implements Agent<never, TOO
      * `id`, `provider`/`model`, or `display_name`.
      */
     listModels(signal?: AbortSignal): Promise<ChatModelConfig[]>;
-    /** Start a fresh chatd chat on the next turn. */
+    /**
+     * Start a fresh chatd chat on the next turn. The dropped chat still exists
+     * server-side: {@link CoderAgent.archive} / {@link CoderAgent.interrupt}
+     * keep targeting it (via {@link CoderAgent.lastKnownChatId}) until a new
+     * chat supersedes it or an archive succeeds against it.
+     */
     resetSession(): void;
     /**
      * Interrupt the in-flight generation, if any. Resolves as soon as the server
      * acknowledges the interrupt — the run keeps winding down asynchronously for
      * a few seconds afterwards (see {@link CoderAgent.archive}).
+     *
+     * Targets the session's chat, or — after the session was dropped (a
+     * fresh-chat stream failure, or {@link CoderAgent.resetSession}) — the
+     * {@link CoderAgent.lastKnownChatId}, whose run may still be winding down
+     * server-side. With neither, there is nothing to interrupt and it resolves
+     * `{ interrupted: false }` without a server call (inspect the result rather
+     * than relying on a silent no-op).
      */
     interrupt(opts?: {
         signal?: AbortSignal;
-    }): Promise<void>;
+    }): Promise<CoderInterruptResult>;
     /**
      * Archive the underlying chat (safe cleanup; hides it from listings).
      *
+     * Targets the session's chat, or — after the session was dropped (a
+     * fresh-chat stream failure, or {@link CoderAgent.resetSession}) — the
+     * {@link CoderAgent.lastKnownChatId}, so the stranded chat is still cleaned
+     * up; chats stranded by EARLIER automatic discards
+     * ({@link CoderAgent.strandedChatIds} — `maxRetries` can accumulate several)
+     * are retired in the same call. On success each archived id is cleared as a
+     * cleanup target; with no id at all, there is nothing to archive and it
+     * resolves `{ archived: false }` without a server call (inspect the result
+     * rather than relying on a silent no-op).
+     *
      * A freshly interrupted/settled chat can keep winding down server-side for a
      * few seconds, during which the server rejects archiving with a 409. Those
-     * 409s are retried (~1s apart, ~15s overall — see `settleDeadlineMs` /
-     * `settleRetryDelayMs`) and the last one is rethrown if the chat never
-     * settles; any other failure, including a caller abort, rethrows immediately.
+     * 409s are retried (~1s apart — see `settleRetryDelayMs`) inside ONE
+     * `settleDeadlineMs` window (~15s) shared by the whole call — however many
+     * chats it archives — and the last 409 is rethrown if the window closes
+     * first; any other failure, including a caller abort, rethrows immediately.
+     * Chats are archived oldest first, each id cleared as its archive succeeds —
+     * a mid-list failure rethrows and leaves the remaining ids targetable by a
+     * later retry.
      */
     archive(opts?: {
         signal?: AbortSignal;
-    }): Promise<void>;
+    }): Promise<CoderArchiveResult>;
     /**
      * Clean up the chat when the agent leaves an `await using` scope, so cleanup
      * rides scope exit instead of a separate call you have to remember in a
      * `finally`. Interrupts any in-flight server run, then archives the chat
-     * (retrying while the interrupted run settles). Best-effort and bounded
+     * (retrying while the interrupted run settles) — including a chat stranded
+     * by a session discard (see {@link CoderAgent.lastKnownChatId}), which a
+     * failed `generate()` would otherwise leak. Best-effort and bounded
      * (~15s overall): disposal errors are swallowed after the bounded attempts
      * so they can't mask the scope's own error — call {@link CoderAgent.archive}
      * directly when you need guaranteed cleanup.
@@ -1128,10 +1241,42 @@ declare class CoderLanguageModel implements LanguageModelV4 {
     readonly supportedUrls: Record<string, RegExp[]>;
     constructor(config: CoderLanguageModelConfig);
     get chatId(): string | undefined;
+    /**
+     * The last chat id this model created or attached to, for CLEANUP targeting
+     * only — generation always targets {@link chatId}. It survives
+     * {@link resetSession} (including the automatic session discard after a
+     * fresh-chat stream failure, which clears {@link chatId} so a retry starts
+     * fresh while the failed chat still exists server-side), is superseded when
+     * a later turn creates or attaches to another chat, and is cleared via
+     * {@link noteChatCleanedUp} once cleanup actually succeeded against it.
+     */
+    get lastKnownChatId(): string | undefined;
+    /**
+     * Chat ids stranded by automatic session discards and not yet cleaned up,
+     * oldest first. Each retryable fresh-chat stream failure strands one chat;
+     * under AI-SDK `maxRetries` several can accumulate while only the final
+     * attempt's error (and {@link lastKnownChatId}) names the newest —
+     * `CoderAgent.archive()` retires all of them. Ids leave the list only via
+     * {@link noteChatCleanedUp}.
+     */
+    get strandedChatIds(): string[];
+    /**
+     * Forgets `chatId` as a cleanup target — call it only after cleanup
+     * actually succeeded against that chat (e.g. `CoderAgent.archive()`
+     * archived it), so later cleanup calls don't re-target an already-archived
+     * chat: removes it from {@link strandedChatIds} and, when it is the
+     * last-known id, clears {@link lastKnownChatId} (match-guarded: a stale
+     * completion must not erase a newer chat's id). The session field
+     * ({@link chatId}) is deliberately untouched — archiving does not reset the
+     * session.
+     */
+    noteChatCleanedUp(chatId: string): void;
     /**
      * Drops the current session so the next turn creates a fresh chat. Also
      * closes the retained event stream, if any (fire-and-forget — a sync reset
      * must not wait on socket teardown, and `close()` never rejects).
+     * {@link lastKnownChatId} deliberately survives the reset: the dropped chat
+     * still exists server-side and cleanup must still be able to target it.
      */
     resetSession(): void;
     /**
@@ -1340,11 +1485,21 @@ declare class CoderApiError extends CoderAgentError {
  */
 declare class CoderStreamError extends APICallError {
     name: string;
+    /**
+     * The chatd chat id the failed turn had created or attached to, when known.
+     * A fresh-chat stream failure discards the session so a retry starts on a
+     * fresh chat (`CoderAgent.chatId` becomes `undefined`), but the failed chat
+     * still exists server-side — this field names it so callers can clean it up
+     * (`CoderAgent.archive()` also retains it as the last-known cleanup target).
+     * `undefined` when the failure happened before any chat existed.
+     */
+    readonly chatId: string | undefined;
     constructor(args: {
         message: string;
         url: string;
         cause?: unknown;
         isRetryable?: boolean;
+        chatId?: string;
     });
 }
 /** A chat generation ended in an error status. */
@@ -1357,4 +1512,4 @@ declare class CoderChatError extends CoderAgentError {
     constructor(payload: ChatErrorPayload);
 }
 
-export { CHAT_ATTACHMENT_MEDIA_TYPES, CODER_PROVIDER_OPTIONS, type Chat, type ChatAttachment, type ChatAttachmentMediaType, type ChatBusyBehavior, type ChatClientType, type ChatErrorPayload, type ChatFileInput, type ChatInputPart, type ChatInputPartType, type ChatMessage, type ChatMessagePart, type ChatMessagePartType, type ChatMessageRole, type ChatMessageUsage, type ChatMessagesResponse, type ChatMessagesToUIMessagesOptions, type ChatModelConfig, type ChatPlanMode, type ChatQueuedMessage, type ChatStatus, type ChatStreamActionRequired, type ChatStreamEvent, type ChatStreamEventType, type ChatStreamMessagePart, type ChatStreamRetry, type ChatStreamStatus, type ChatStreamToolCall, type ChatWatchEvent, type ChatWatchEventKind, CoderAgent, CoderAgentError, type CoderAgentSettings, CoderApiError, CoderChatClient, type CoderChatClientOptions, CoderChatError, type CoderFileProviderOptions, CoderLanguageModel, type CoderLanguageModelConfig, CoderStreamError, type CoderTransportEvent, type CreateChatMessageRequest, type CreateChatMessageResponse, type CreateChatRequest, type DynamicTool, type FileContent, type FilePartUploader, type HttpErrorTransportEvent, type HttpRequestTransportEvent, type HttpResponseTransportEvent, MAX_CHAT_FILE_SIZE_BYTES, type PreviewShareLevel, type ResolvedFile, type SegmentSettleTransportEvent, type SegmentStartTransportEvent, type SharePreviewOptions, type SharedWorkspacePreview, type StreamCloseTransportEvent, type StreamDialTransportEvent, type StreamErrorTransportEvent, type StreamEventTransportEvent, type StreamOpenTransportEvent, type StreamRedialTransportEvent, type SubmitToolResultsRequest, TERMINAL_STATUSES, type ToolResult, type TransportEventHandler, type TurnAction, TurnTranslator, type UpdateChatRequest, type UploadChatFileResponse, type UploadedChatFile, type UserContent, type WatchChatEventsOptions, type WebSocketFactory, type WebSocketLike, type WorkspaceFileStore, type WorkspacePlacement, type WorkspacePreview, type WorkspacePreviewOptions, chatMessagesToUIMessages, classifyTurnAction, dataContentToFileContent, dynamicToolNames, extractSystemPrompt, resolveFileContent, streamChatEvents, toolsToDynamicTools, userContentToInputParts, watchChatEvents };
+export { CHAT_ATTACHMENT_MEDIA_TYPES, CODER_PROVIDER_OPTIONS, type Chat, type ChatAttachment, type ChatAttachmentMediaType, type ChatBusyBehavior, type ChatClientType, type ChatErrorPayload, type ChatFileInput, type ChatInputPart, type ChatInputPartType, type ChatMessage, type ChatMessagePart, type ChatMessagePartType, type ChatMessageRole, type ChatMessageUsage, type ChatMessagesResponse, type ChatMessagesToUIMessagesOptions, type ChatModelConfig, type ChatPlanMode, type ChatQueuedMessage, type ChatStatus, type ChatStreamActionRequired, type ChatStreamEvent, type ChatStreamEventType, type ChatStreamMessagePart, type ChatStreamRetry, type ChatStreamStatus, type ChatStreamToolCall, type ChatWatchEvent, type ChatWatchEventKind, CoderAgent, CoderAgentError, type CoderAgentSettings, CoderApiError, type CoderArchiveResult, CoderChatClient, type CoderChatClientOptions, CoderChatError, type CoderClientOperation, type CoderFileProviderOptions, type CoderInterruptResult, CoderLanguageModel, type CoderLanguageModelConfig, CoderStreamError, type CoderTransportEvent, type CreateChatMessageRequest, type CreateChatMessageResponse, type CreateChatRequest, type DynamicTool, type FileContent, type FilePartUploader, type HttpErrorTransportEvent, type HttpRequestTransportEvent, type HttpResponseTransportEvent, MAX_CHAT_FILE_SIZE_BYTES, type PreviewShareLevel, type ResolvedFile, type SegmentSettleTransportEvent, type SegmentStartTransportEvent, type SharePreviewOptions, type SharedWorkspacePreview, type StreamCloseTransportEvent, type StreamDialTransportEvent, type StreamErrorTransportEvent, type StreamEventTransportEvent, type StreamOpenTransportEvent, type StreamRedialTransportEvent, type SubmitToolResultsRequest, TERMINAL_STATUSES, type ToolResult, type TransportEventHandler, type TurnAction, TurnTranslator, type UpdateChatRequest, type UploadChatFileResponse, type UploadedChatFile, type UserContent, type WatchChatEventsOptions, type WebSocketFactory, type WebSocketLike, type WorkspaceFileStore, type WorkspacePlacement, type WorkspacePreview, type WorkspacePreviewOptions, chatMessagesToUIMessages, classifyTurnAction, dataContentToFileContent, dynamicToolNames, extractSystemPrompt, resolveFileContent, streamChatEvents, toolsToDynamicTools, userContentToInputParts, watchChatEvents };