@coder/ai-sdk-agent 0.7.2 → 0.9.0

package/dist/index.js

@@ -30,6 +30,15 @@ var CoderApiError = class extends CoderAgentError {
 };
 var CoderStreamError = class extends APICallError {
   name = "CoderStreamError";
+  /**
+   * 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.
+   */
+  chatId;
   constructor(args) {
     super({
       message: args.message,
@@ -42,6 +51,7 @@ var CoderStreamError = class extends APICallError {
       isRetryable: args.isRetryable ?? true,
       cause: args.cause
     });
+    this.chatId = args.chatId;
   }
 };
 var CoderChatError = class extends CoderAgentError {
@@ -303,6 +313,52 @@ async function* streamChatEventsLoop(options) {
         abortListenerAdded = true;
       }
     }
+    const ingest = (next) => {
+      let progress = false;
+      let forwarded = true;
+      if (next.type === "message_part") {
+        const mp = next.message_part;
+        const hv = mp?.history_version;
+        const ga = mp?.generation_attempt;
+        const seq = mp?.seq;
+        if (hv !== void 0 && ga !== void 0 && seq !== void 0) {
+          if (hv === lastHistoryVersion && ga === lastGenerationAttempt && lastSeq !== void 0 && seq <= lastSeq) {
+            forwarded = false;
+          } else {
+            lastHistoryVersion = hv;
+            lastGenerationAttempt = ga;
+            lastSeq = seq;
+            progress = true;
+          }
+        } else {
+          sawUntrackableDelta = true;
+        }
+      } else if (next.type === "message" && next.message) {
+        const serialized = JSON.stringify(next.message);
+        if (lastMessageJson.get(next.message.id) !== serialized) {
+          lastMessageJson.set(next.message.id, serialized);
+          progress = true;
+        }
+        if (maxCommittedId === void 0 || next.message.id > maxCommittedId) {
+          maxCommittedId = next.message.id;
+          sawUntrackableDelta = false;
+        }
+      }
+      if (progress) {
+        failures = 0;
+        backoffMs = STREAM_BACKOFF_INITIAL_MS;
+      }
+      emit?.({
+        type: "ws:event",
+        chatId,
+        reader,
+        attempt,
+        event: next,
+        forwarded,
+        timestamp: Date.now()
+      });
+      if (forwarded) queue.push(next);
+    };
     const onMessage = (ev) => {
       if (finished) return;
       let batch;
@@ -325,27 +381,9 @@ async function* streamChatEventsLoop(options) {
         return;
       }
       if (Array.isArray(batch)) {
-        for (const e of batch) {
-          queue.push(e);
-          emit?.({
-            type: "ws:event",
-            chatId,
-            reader,
-            attempt,
-            event: e,
-            timestamp: Date.now()
-          });
-        }
+        for (const e of batch) ingest(e);
       } else if (batch && typeof batch === "object") {
-        queue.push(batch);
-        emit?.({
-          type: "ws:event",
-          chatId,
-          reader,
-          attempt,
-          event: batch,
-          timestamp: Date.now()
-        });
+        ingest(batch);
       }
       wake();
     };
@@ -383,40 +421,7 @@ async function* streamChatEventsLoop(options) {
     try {
       while (true) {
         while (queue.length > 0) {
-          const next = queue.shift();
-          let progress = false;
-          if (next.type === "message_part") {
-            const mp = next.message_part;
-            const hv = mp?.history_version;
-            const ga = mp?.generation_attempt;
-            const seq = mp?.seq;
-            if (hv !== void 0 && ga !== void 0 && seq !== void 0) {
-              if (hv === lastHistoryVersion && ga === lastGenerationAttempt && lastSeq !== void 0 && seq <= lastSeq) {
-                continue;
-              }
-              lastHistoryVersion = hv;
-              lastGenerationAttempt = ga;
-              lastSeq = seq;
-              progress = true;
-            } else {
-              sawUntrackableDelta = true;
-            }
-          } else if (next.type === "message" && next.message) {
-            const serialized = JSON.stringify(next.message);
-            if (lastMessageJson.get(next.message.id) !== serialized) {
-              lastMessageJson.set(next.message.id, serialized);
-              progress = true;
-            }
-            if (maxCommittedId === void 0 || next.message.id > maxCommittedId) {
-              maxCommittedId = next.message.id;
-              sawUntrackableDelta = false;
-            }
-          }
-          if (progress) {
-            failures = 0;
-            backoffMs = STREAM_BACKOFF_INITIAL_MS;
-          }
-          yield next;
+          yield queue.shift();
         }
         if (finished) break;
         await new Promise((resolve) => {
@@ -446,7 +451,8 @@ async function* streamChatEventsLoop(options) {
       throw new CoderStreamError({
         message: "chat stream dropped mid-turn and cannot be resumed: this server does not stamp deltas with history_version/generation_attempt/seq, so a redial would replay them",
         url,
-        cause: failure
+        cause: failure,
+        chatId
       });
     }
     if (failure) lastFailure = failure;
@@ -455,7 +461,8 @@ async function* streamChatEventsLoop(options) {
       throw new CoderStreamError({
         message: `Coder chat stream ${path} could not be (re-)established after ${failures} consecutive connection failures without progress`,
         url,
-        cause: lastFailure
+        cause: lastFailure,
+        chatId
       });
     }
     emit?.({
@@ -667,9 +674,11 @@ var CoderChatClient = class {
   /**
    * Issue a request and return the raw `Response` on success (body unread). On a
    * non-2xx status the body is consumed to build a {@link CoderApiError}. Shared
-   * by JSON requests and the raw upload/download endpoints.
+   * by JSON requests and the raw upload/download endpoints. `op` names the
+   * public client method on the exchange's `http:*` events (issue #112) — the
+   * emit site is shared, so each call site threads its own literal.
    */
-  async #send(method, path, opts) {
+  async #send(op, method, path, opts) {
     const headers = {
       "Coder-Session-Token": this.#token,
       ...opts?.headers
@@ -684,7 +693,7 @@ var CoderChatClient = class {
     if (emit) {
       requestId = ++this.#httpSeq;
       startedAt = performance.now();
-      emit({ type: "http:request", id: requestId, method, path, timestamp: Date.now() });
+      emit({ type: "http:request", id: requestId, op, method, path, timestamp: Date.now() });
     }
     let res;
     try {
@@ -693,6 +702,7 @@ var CoderChatClient = class {
       emit?.({
         type: "http:error",
         id: requestId,
+        op,
         method,
         path,
         message: err instanceof Error ? err.message : String(err),
@@ -704,6 +714,7 @@ var CoderChatClient = class {
     emit?.({
       type: "http:response",
       id: requestId,
+      op,
       method,
       path,
       status: res.status,
@@ -733,8 +744,8 @@ var CoderChatClient = class {
       return void 0;
     }
   }
-  async #request(method, path, body, signal) {
-    const res = await this.#send(method, path, {
+  async #request(op, method, path, body, signal) {
+    const res = await this.#send(op, method, path, {
       body: body === void 0 ? void 0 : JSON.stringify(body),
       headers: body === void 0 ? void 0 : { "Content-Type": "application/json" },
       signal
@@ -744,6 +755,7 @@ var CoderChatClient = class {
   // --- REST -----------------------------------------------------------------
   listModelConfigs(signal) {
     return this.#request(
+      "listModelConfigs",
       "GET",
       `${API_PREFIX}/model-configs`,
       void 0,
@@ -751,13 +763,14 @@ var CoderChatClient = class {
     );
   }
   createChat(req, signal) {
-    return this.#request("POST", API_PREFIX, req, signal);
+    return this.#request("createChat", "POST", API_PREFIX, req, signal);
   }
   getChat(chatId, signal) {
-    return this.#request("GET", `${API_PREFIX}/${chatId}`, void 0, signal);
+    return this.#request("getChat", "GET", `${API_PREFIX}/${chatId}`, void 0, signal);
   }
   createChatMessage(chatId, req, signal) {
     return this.#request(
+      "createChatMessage",
       "POST",
       `${API_PREFIX}/${chatId}/messages`,
       req,
@@ -771,6 +784,7 @@ var CoderChatClient = class {
     if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
     const q = params.toString();
     return this.#request(
+      "getMessages",
       "GET",
       `${API_PREFIX}/${chatId}/messages${q ? `?${q}` : ""}`,
       void 0,
@@ -778,7 +792,13 @@ var CoderChatClient = class {
     );
   }
   submitToolResults(chatId, req, signal) {
-    return this.#request("POST", `${API_PREFIX}/${chatId}/tool-results`, req, signal);
+    return this.#request(
+      "submitToolResults",
+      "POST",
+      `${API_PREFIX}/${chatId}/tool-results`,
+      req,
+      signal
+    );
   }
   /**
    * Interrupt the chat's in-flight run (`POST /interrupt`). The server flips
@@ -797,6 +817,7 @@ var CoderChatClient = class {
     const opts = optsOrSignal instanceof AbortSignal ? { signal: optsOrSignal } : optsOrSignal;
     const query = opts?.wait ? "?wait=true" : "";
     return this.#request(
+      "interruptChat",
       "POST",
       `${API_PREFIX}/${chatId}/interrupt${query}`,
       void 0,
@@ -804,11 +825,17 @@ var CoderChatClient = class {
     );
   }
   updateChat(chatId, req, signal) {
-    return this.#request("PATCH", `${API_PREFIX}/${chatId}`, req, signal);
+    return this.#request("updateChat", "PATCH", `${API_PREFIX}/${chatId}`, req, signal);
   }
   /** Convenience: archive a chat (soft-hide; safe for cleanup). */
   archiveChat(chatId, signal) {
-    return this.updateChat(chatId, { archived: true }, signal);
+    return this.#request(
+      "archiveChat",
+      "PATCH",
+      `${API_PREFIX}/${chatId}`,
+      { archived: true },
+      signal
+    );
   }
   // --- Files ----------------------------------------------------------------
   /**
@@ -846,6 +873,7 @@ var CoderChatClient = class {
       headers["Content-Disposition"] = `attachment; filename="${ascii}"; filename*=UTF-8''${utf8}`;
     }
     const res = await this.#send(
+      "uploadChatFile",
       "POST",
       `${API_PREFIX}/files?organization=${encodeURIComponent(organizationId)}`,
       { body: resolved.body, headers, signal }
@@ -863,7 +891,9 @@ var CoderChatClient = class {
   }
   /** Download a chat file's bytes and media type by id. */
   async getChatFile(fileId, signal) {
-    const res = await this.#send("GET", `${API_PREFIX}/files/${fileId}`, { signal });
+    const res = await this.#send("getChatFile", "GET", `${API_PREFIX}/files/${fileId}`, {
+      signal
+    });
     const buf = await res.arrayBuffer();
     return {
       bytes: new Uint8Array(buf),
@@ -917,7 +947,13 @@ var CoderChatClient = class {
   async resolveModelConfigId(hint, signal) {
     const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
     if (UUID_RE.test(hint)) return hint;
-    const raw = await this.listModelConfigs(signal);
+    const raw = await this.#request(
+      "resolveModelConfigId",
+      "GET",
+      `${API_PREFIX}/model-configs`,
+      void 0,
+      signal
+    );
     const configs = (Array.isArray(raw) ? raw : []).filter(
       (c) => typeof c === "object" && c !== null
     );
@@ -1752,6 +1788,25 @@ var CoderLanguageModel = class {
   supportedUrls = {};
   #config;
   #chatId;
+  /**
+   * The last chat id this model created or attached to, retained as a CLEANUP
+   * target — see {@link lastKnownChatId}. Unlike `#chatId` it survives
+   * {@link resetSession}, and is only replaced when a later turn's chat
+   * supersedes it or cleared by {@link noteChatCleanedUp} once cleanup
+   * actually succeeded against it.
+   */
+  #lastKnownChatId;
+  /**
+   * Every chat id stranded by an AUTOMATIC session discard (a stream failure
+   * on a chat the failed turn itself created) and not yet cleaned up. A
+   * single `#lastKnownChatId` slot is not enough here: each AI-SDK
+   * `maxRetries` attempt strands its own fresh chat and only the final
+   * attempt's error reaches the caller, so without this ledger every attempt
+   * before the last would leak unnamed. Drained by {@link noteChatCleanedUp}.
+   * Deliberate abandonment ({@link resetSession}) does NOT record here — the
+   * caller chose to walk away and may want the chat kept.
+   */
+  #strandedChatIds = /* @__PURE__ */ new Set();
   #lastSeenMessageId = 0;
   #resolvedModelConfigId;
   #modelResolved = false;
@@ -1767,15 +1822,55 @@ var CoderLanguageModel = class {
     this.#config = config;
     this.modelId = config.model ?? "chatd";
     this.#chatId = config.chatId;
+    this.#lastKnownChatId = config.chatId;
     this.#emitTransportEvent = safeTransportEmitter(config.onTransportEvent);
   }
   get chatId() {
     return this.#chatId;
   }
+  /**
+   * 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() {
+    return this.#lastKnownChatId;
+  }
+  /**
+   * 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() {
+    return [...this.#strandedChatIds];
+  }
+  /**
+   * 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) {
+    this.#strandedChatIds.delete(chatId);
+    if (this.#lastKnownChatId === chatId) this.#lastKnownChatId = void 0;
+  }
   /**
    * 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() {
     this.#chatId = void 0;
@@ -2145,6 +2240,7 @@ var CoderLanguageModel = class {
       }
       const chatId = this.#chatId;
       turnChatId = chatId;
+      this.#lastKnownChatId = chatId;
       if (segmentChat) segmentChat.chatId = chatId;
       const dynamicNames = dynamicToolNames(options.tools);
       translator = new TurnTranslator({
@@ -2243,7 +2339,11 @@ var CoderLanguageModel = class {
       } catch (err) {
         throwIfAborted();
         if (err instanceof CoderStreamError) {
+          if (err.chatId === void 0 && turnChatId !== void 0) {
+            err.chatId = turnChatId;
+          }
           if (turnCreatedChat) {
+            if (turnChatId) this.#strandedChatIds.add(turnChatId);
             discardSession = true;
           }
           const effectful = chatHasWorkspace || chatHasMcpServers || uploadedAttachment;
@@ -2252,7 +2352,8 @@ var CoderLanguageModel = class {
             message: `${err.message}; automatic retry is disabled because ${turnCreatedChat ? "the turn has server-side effects a replay would repeat (workspace/MCP tools that may have executed, or freshly uploaded attachments)" : "the chat has prior state (a retry would resubmit this turn's prompt as a new user turn)"}`,
             url: err.url,
             cause: err,
-            isRetryable: false
+            isRetryable: false,
+            chatId: err.chatId
           });
         }
         if (err instanceof CoderAgentError && !(err instanceof CoderApiError) && !(err instanceof CoderChatError)) {
@@ -2466,25 +2567,28 @@ var CoderAgent = class {
   #settleRetryDelayMs;
   constructor(settings) {
     assertSupportedAiVersion();
+    const env = globalThis.process?.env;
+    const baseUrl = settings.baseUrl ?? env?.CODER_URL;
+    const token = settings.token ?? env?.CODER_SESSION_TOKEN;
     if (settings.client) {
       this.#client = settings.client;
-    } else if (settings.baseUrl && settings.token) {
+    } else if (baseUrl && token) {
       this.#client = new CoderChatClient({
-        baseUrl: settings.baseUrl,
-        token: settings.token,
+        baseUrl,
+        token,
         fetch: settings.fetch,
         webSocketFactory: settings.webSocketFactory,
         onTransportEvent: settings.onTransportEvent
       });
     } else {
       throw new CoderAgentError(
-        "CoderAgent requires either `client` or both `baseUrl` and `token`."
+        "CoderAgent requires either `client` or both `baseUrl` and `token` (or the CODER_URL and CODER_SESSION_TOKEN environment variables)."
       );
     }
     this.#organizationId = settings.organizationId;
     this.#workspaceFiles = settings.workspaceFiles;
     this.#workspaceId = settings.workspaceId;
-    this.#workspaceApi = settings.baseUrl && settings.token ? { baseUrl: settings.baseUrl, token: settings.token, fetch: settings.fetch } : void 0;
+    this.#workspaceApi = baseUrl && token ? { baseUrl, token, fetch: settings.fetch } : void 0;
     this.#settleDeadlineMs = sanitizeDelayMs(settings.settleDeadlineMs, SETTLE_DEADLINE_MS);
     this.#settleRetryDelayMs = sanitizeDelayMs(settings.settleRetryDelayMs, SETTLE_RETRY_DELAY_MS);
     if (settings.workspaceFiles && settings.workspaceId && settings.workspaceFiles.workspaceId !== settings.workspaceId) {
@@ -2528,6 +2632,29 @@ var CoderAgent = class {
   get chatId() {
     return this.#model.chatId;
   }
+  /**
+   * 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() {
+    return this.#model.lastKnownChatId;
+  }
+  /**
+   * 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() {
+    return this.#model.strandedChatIds;
+  }
   generate(options) {
     return this.#inner.generate(options);
   }
@@ -2543,7 +2670,12 @@ var CoderAgent = class {
   listModels(signal) {
     return this.#client.listModelConfigs(signal);
   }
-  /** 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() {
     this.#model.resetSession();
   }
@@ -2551,37 +2683,67 @@ var CoderAgent = class {
    * 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).
    */
   async interrupt(opts) {
-    const id = this.#model.chatId;
-    if (!id) return;
+    const id = this.#model.chatId ?? this.#model.lastKnownChatId;
+    if (!id) return { interrupted: false };
     await this.#model.closePausedStream();
     await this.#client.interruptChat(id, opts?.signal);
+    return { interrupted: true, chatId: id };
   }
   /**
    * 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.
    */
   async archive(opts) {
-    const id = this.#model.chatId;
-    if (!id) return;
+    const primary = this.#model.chatId ?? this.#model.lastKnownChatId;
+    if (!primary) return { archived: false };
     await this.#model.closePausedStream();
-    await archiveWhenSettled(this.#client, id, {
-      deadlineMs: this.#settleDeadlineMs,
-      retryDelayMs: this.#settleRetryDelayMs,
-      signal: opts?.signal
-    });
+    const targets = [.../* @__PURE__ */ new Set([...this.#model.strandedChatIds, primary])];
+    const deadline = Date.now() + this.#settleDeadlineMs;
+    for (const id of targets) {
+      await archiveWhenSettled(this.#client, id, {
+        deadlineMs: Math.max(deadline - Date.now(), 1),
+        retryDelayMs: this.#settleRetryDelayMs,
+        signal: opts?.signal
+      });
+      this.#model.noteChatCleanedUp(id);
+    }
+    return { archived: true, chatId: primary, archivedChatIds: targets };
   }
   /**
    * 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.
@@ -2658,7 +2820,7 @@ var CoderAgent = class {
     }
     if (!this.#workspaceApi) {
       throw new CoderAgentError(
-        `${method}() needs the deployment's REST credentials \u2014 construct the CoderAgent with \`baseUrl\` and \`token\` (they can accompany \`client\`).`
+        `${method}() needs the deployment's REST credentials \u2014 construct the CoderAgent with \`baseUrl\` and \`token\` (they can accompany \`client\`), or set the CODER_URL and CODER_SESSION_TOKEN environment variables.`
       );
     }
     return { conn: this.#workspaceApi, workspaceId: this.#workspaceId };