@coder/ai-sdk-agent 0.2.1 → 0.4.0

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/agent/coder-agent.ts
 import {
-  stepCountIs,
+  isStepCount,
   ToolLoopAgent
 } from "ai";
 
@@ -42,6 +42,32 @@ var CoderChatError = class extends CoderAgentError {
   }
 };
 
+// src/ai-version.ts
+var SUPPORTED_AI_MAJOR = 7;
+function unsupportedAiVersionMessage(version) {
+  const major = Number(/^v?(\d+)(?:[.+-]|$)/.exec(version.trim())?.[1]);
+  if (!Number.isSafeInteger(major) || major === SUPPORTED_AI_MAJOR) return void 0;
+  return `@coder/ai-sdk-agent supports the \`ai\` package v${SUPPORTED_AI_MAJOR} only (peer dependency \`ai@^${SUPPORTED_AI_MAJOR}\`), but ai@${version} is installed. Other majors fail at runtime in confusing ways (brand-check TypeErrors, silently empty streams). Install a compatible version, e.g. \`pnpm add ai@^${SUPPORTED_AI_MAJOR}\`.`;
+}
+function resolveInstalledAiVersion() {
+  try {
+    const nodeModule = typeof process !== "undefined" && typeof process.getBuiltinModule === "function" ? process.getBuiltinModule("node:module") : void 0;
+    const requireFromHere = nodeModule?.createRequire(import.meta.url);
+    const pkg = requireFromHere?.("ai/package.json");
+    return typeof pkg?.version === "string" ? pkg.version : void 0;
+  } catch {
+    return void 0;
+  }
+}
+var cachedMessage;
+function assertSupportedAiVersion(resolveVersion = resolveInstalledAiVersion) {
+  if (cachedMessage === void 0) {
+    const version = resolveVersion();
+    cachedMessage = version === void 0 ? null : unsupportedAiVersionMessage(version) ?? null;
+  }
+  if (cachedMessage !== null) throw new CoderAgentError(cachedMessage);
+}
+
 // src/files.ts
 function isBlob(v) {
   return typeof Blob !== "undefined" && v instanceof Blob;
@@ -86,11 +112,16 @@ function base64ToBytes(b64) {
   return bytes;
 }
 function dataContentToFileContent(data) {
-  if (data instanceof Uint8Array) return data;
-  if (typeof data === "string") return base64ToBytes(data);
-  throw new CoderAgentError(
-    "File parts referencing a URL are not supported; provide the file bytes instead."
-  );
+  switch (data.type) {
+    case "data":
+      return data.data instanceof Uint8Array ? data.data : base64ToBytes(data.data);
+    case "text":
+      return new TextEncoder().encode(data.text);
+    default:
+      throw new CoderAgentError(
+        `File parts referencing a ${data.type === "url" ? "URL" : "provider reference"} are not supported; provide the file bytes instead.`
+      );
+  }
 }
 
 // src/coder/types.ts
@@ -211,6 +242,176 @@ async function* streamChatEvents(options) {
     }
   }
 }
+var WATCH_PATH = "/api/experimental/chats/watch";
+var WATCH_BACKOFF_INITIAL_MS = 1e3;
+var WATCH_BACKOFF_CAP_MS = 3e4;
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    if (signal?.aborted) {
+      resolve();
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function upgradeStatus(message) {
+  const match = /unexpected server response: (\d{3})$/i.exec(message.trim());
+  return match ? Number(match[1]) : void 0;
+}
+function watchChatEvents(options) {
+  const controller = new AbortController();
+  const external = options.signal;
+  const chain = () => controller.abort(external?.reason);
+  if (external) {
+    if (external.aborted) chain();
+    else external.addEventListener("abort", chain, { once: true });
+  }
+  const inner = watchChatEventsLoop({ ...options, signal: controller.signal });
+  const detach = () => external?.removeEventListener("abort", chain);
+  const finish = async () => {
+    controller.abort();
+    detach();
+    try {
+      await inner.return();
+    } catch {
+    }
+  };
+  return {
+    // Detach the signal chain once the loop settles for good (done, or the
+    // terminal 4xx rejection) — the iteration protocol never calls return()
+    // on a failed iterator, and the {once} listener would otherwise pile up
+    // on a long-lived signal across re-created watchers.
+    async next() {
+      try {
+        const result = await inner.next();
+        if (result.done) detach();
+        return result;
+      } catch (err) {
+        detach();
+        throw err;
+      }
+    },
+    async return() {
+      await finish();
+      return { done: true, value: void 0 };
+    },
+    async throw(err) {
+      await finish();
+      throw err;
+    },
+    [Symbol.asyncIterator]() {
+      return this;
+    },
+    // Native async generators are async-disposable; the wrapper must be too,
+    // so `await using events = client.watchChats(…)` keeps tearing down.
+    async [Symbol.asyncDispose]() {
+      await finish();
+    }
+  };
+}
+async function* watchChatEventsLoop(options) {
+  const { baseUrl, token, signal } = options;
+  const factory = options.webSocketFactory ?? defaultFactory;
+  const url = `${httpToWs(baseUrl)}${WATCH_PATH}`;
+  let backoffMs = WATCH_BACKOFF_INITIAL_MS;
+  while (!signal?.aborted) {
+    const queue = [];
+    let resolveNext;
+    let finished = false;
+    let failure;
+    const wake = () => {
+      resolveNext?.();
+      resolveNext = void 0;
+    };
+    const ws = factory(url, { headers: { "Coder-Session-Token": token } });
+    const onAbort = () => {
+      finished = true;
+      try {
+        ws.close(1e3);
+      } catch {
+      }
+      wake();
+    };
+    let abortListenerAdded = false;
+    if (signal) {
+      if (signal.aborted) onAbort();
+      else {
+        signal.addEventListener("abort", onAbort, { once: true });
+        abortListenerAdded = true;
+      }
+    }
+    const onMessage = (ev) => {
+      if (finished) return;
+      let payload;
+      try {
+        const data = typeof ev.data === "string" ? ev.data : String(ev.data);
+        payload = JSON.parse(data);
+      } catch (err) {
+        failure = new CoderAgentError("failed to parse chat watch frame", { cause: err });
+        finished = true;
+        wake();
+        return;
+      }
+      if (Array.isArray(payload)) {
+        for (const e of payload) queue.push(e);
+      } else if (payload && typeof payload === "object") {
+        queue.push(payload);
+      }
+      wake();
+    };
+    const onError = (ev) => {
+      if (finished) return;
+      const message = ev && typeof ev === "object" && "message" in ev ? String(ev.message) : "chat watch socket error";
+      const status = upgradeStatus(message);
+      failure = status !== void 0 && status >= 400 && status < 500 ? new CoderApiError({ status, method: "GET", path: WATCH_PATH, message }) : new CoderAgentError(message);
+      finished = true;
+      wake();
+    };
+    const onClose = () => {
+      finished = true;
+      wake();
+    };
+    ws.addEventListener("message", onMessage);
+    ws.addEventListener("error", onError);
+    ws.addEventListener("close", onClose);
+    try {
+      while (true) {
+        while (queue.length > 0) {
+          const next = queue.shift();
+          backoffMs = WATCH_BACKOFF_INITIAL_MS;
+          yield next;
+        }
+        if (finished) break;
+        await new Promise((resolve) => {
+          resolveNext = resolve;
+        });
+      }
+    } finally {
+      finished = true;
+      if (signal && abortListenerAdded) signal.removeEventListener("abort", onAbort);
+      ws.removeEventListener("message", onMessage);
+      ws.removeEventListener("error", onError);
+      ws.removeEventListener("close", onClose);
+      try {
+        ws.close(1e3);
+      } catch {
+      }
+    }
+    if (signal?.aborted) return;
+    if (failure instanceof CoderApiError) throw failure;
+    await sleep(backoffMs, signal);
+    if (signal?.aborted) return;
+    backoffMs = Math.min(backoffMs * 2, WATCH_BACKOFF_CAP_MS);
+  }
+}
 
 // src/coder/client.ts
 var API_PREFIX = "/api/experimental/chats";
@@ -309,8 +510,28 @@ var CoderChatClient = class {
   submitToolResults(chatId, req, signal) {
     return this.#request("POST", `${API_PREFIX}/${chatId}/tool-results`, req, signal);
   }
-  interruptChat(chatId, signal) {
-    return this.#request("POST", `${API_PREFIX}/${chatId}/interrupt`, void 0, signal);
+  /**
+   * Interrupt the chat's in-flight run (`POST /interrupt`). The server flips
+   * an active run to `interrupting` and responds immediately with the updated
+   * chat — it does not wait for the run to actually stop.
+   *
+   * Pass `{ wait: true }` to send `?wait=true`, asking the server to hold the
+   * response until the run has stopped. Coder servers without that param
+   * ignore the unknown query harmlessly and still return immediately, so
+   * callers should be prepared to confirm completion via the event stream.
+   *
+   * The second parameter also accepts a bare `AbortSignal` (the historical
+   * signature).
+   */
+  interruptChat(chatId, optsOrSignal) {
+    const opts = optsOrSignal instanceof AbortSignal ? { signal: optsOrSignal } : optsOrSignal;
+    const query = opts?.wait ? "?wait=true" : "";
+    return this.#request(
+      "POST",
+      `${API_PREFIX}/${chatId}/interrupt${query}`,
+      void 0,
+      opts?.signal
+    );
   }
   updateChat(chatId, req, signal) {
     return this.#request("PATCH", `${API_PREFIX}/${chatId}`, req, signal);
@@ -390,6 +611,22 @@ var CoderChatClient = class {
       webSocketFactory: this.#webSocketFactory
     });
   }
+  /**
+   * Watch lifecycle events (status/title changes, creation, deletion, …) for
+   * every chat visible to the authenticated user via the `/chats/watch`
+   * WebSocket. Dropped connections are redialed with exponential backoff; the
+   * iteration ends only when `opts.signal` aborts, or with a terminal
+   * {@link CoderApiError} when the server rejects the upgrade with a 4xx
+   * (bad/expired token, or an older Coder server without the endpoint → 404).
+   */
+  watchChats(opts) {
+    return watchChatEvents({
+      baseUrl: this.baseUrl,
+      token: this.#token,
+      signal: opts?.signal,
+      webSocketFactory: this.#webSocketFactory
+    });
+  }
   // --- Helpers --------------------------------------------------------------
   /**
    * Resolves a user-friendly model hint to a model-config UUID.
@@ -398,30 +635,159 @@ var CoderChatClient = class {
    * (e.g. `anthropic:claude-haiku-4-5-20251001`), a bare model id, or a
    * display-name substring (case-insensitive). Returns `undefined` if no
    * match is found, in which case the caller should let chatd pick the default.
+   *
+   * Tolerates partial payloads from older/newer servers: a malformed listing
+   * (empty body, non-array JSON, null entries) resolves as no match, and
+   * entries missing `provider`, `model`, or `display_name` are matched on the
+   * fields they do carry — an entry without `provider` still matches by its
+   * model id, one without `model` only by display name.
    */
   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 configs = await this.listModelConfigs(signal);
+    const raw = await this.listModelConfigs(signal);
+    const configs = (Array.isArray(raw) ? raw : []).filter(
+      (c) => typeof c === "object" && c !== null
+    );
     const lower = hint.toLowerCase();
     const colon = hint.indexOf(":");
     const provider = colon >= 0 ? hint.slice(0, colon).toLowerCase() : void 0;
     const model = colon >= 0 ? hint.slice(colon + 1).toLowerCase() : lower;
     const candidates = configs.filter((c) => c.enabled !== false);
     const pool = candidates.length > 0 ? candidates : configs;
+    const modelOf = (c) => typeof c.model === "string" ? c.model.toLowerCase() : void 0;
+    const providerOf = (c) => typeof c.provider === "string" ? c.provider.toLowerCase() : void 0;
+    const displayNameOf = (c) => typeof c.display_name === "string" ? c.display_name.toLowerCase() : void 0;
     const exact = pool.find(
-      (c) => c.model.toLowerCase() === model && (provider === void 0 || c.provider.toLowerCase() === provider)
+      (c) => modelOf(c) === model && (provider === void 0 || providerOf(c) === provider)
     );
     if (exact) return exact.id;
-    const byModel = pool.find((c) => c.model.toLowerCase() === model);
+    const byModel = pool.find((c) => modelOf(c) === model);
     if (byModel) return byModel.id;
-    const byDisplay = pool.find((c) => c.display_name.toLowerCase().includes(lower));
+    const byDisplay = pool.find((c) => displayNameOf(c)?.includes(lower));
     if (byDisplay) return byDisplay.id;
-    const byModelSubstring = pool.find((c) => c.model.toLowerCase().includes(model));
+    const byModelSubstring = pool.find((c) => modelOf(c)?.includes(model));
     return byModelSubstring?.id;
   }
 };
 
+// src/coder/workspaces.ts
+async function request(conn, method, path, body, signal) {
+  const fetchFn = conn.fetch ?? globalThis.fetch.bind(globalThis);
+  const headers = { "Coder-Session-Token": conn.token };
+  if (body !== void 0) headers["Content-Type"] = "application/json";
+  const res = await fetchFn(`${conn.baseUrl.replace(/\/$/, "")}${path}`, {
+    method,
+    headers,
+    body: body === void 0 ? void 0 : JSON.stringify(body),
+    signal
+  });
+  const text = await res.text().catch(() => "");
+  let parsed;
+  try {
+    parsed = text.length > 0 ? JSON.parse(text) : void 0;
+  } catch {
+    parsed = void 0;
+  }
+  if (!res.ok) {
+    const errObj = parsed ?? {};
+    throw new CoderApiError({
+      status: res.status,
+      method,
+      path,
+      message: errObj.message ?? res.statusText ?? "request failed",
+      detail: errObj.detail
+    });
+  }
+  return parsed;
+}
+function getWorkspace(conn, workspaceId, signal) {
+  return request(
+    conn,
+    "GET",
+    `/api/v2/workspaces/${workspaceId}`,
+    void 0,
+    signal
+  );
+}
+function getAppsHost(conn, signal) {
+  return request(conn, "GET", "/api/v2/applications/host", void 0, signal);
+}
+async function upsertPortShare(conn, workspaceId, req, signal) {
+  const path = `/api/v2/workspaces/${workspaceId}/port-share`;
+  try {
+    return await request(conn, "POST", path, req, signal);
+  } catch (err) {
+    if (err instanceof CoderApiError && err.status === 404) {
+      throw new CoderApiError({
+        status: 404,
+        method: "POST",
+        path,
+        message: "port sharing is unavailable",
+        detail: "the workspace was not found, or this Coder server predates port sharing (added in Coder v2.9)"
+      });
+    }
+    throw err;
+  }
+}
+function defaultAgentName(workspace) {
+  const agents = (workspace.latest_build?.resources ?? []).flatMap((r) => r.agents ?? []);
+  const first = agents[0];
+  if (agents.length === 1 && first) return first.name;
+  if (agents.length === 0) {
+    throw new CoderAgentError(
+      `Workspace "${workspace.name}" has no agents in its latest build (is it running?); pass agentName explicitly.`
+    );
+  }
+  throw new CoderAgentError(
+    `Workspace "${workspace.name}" has ${agents.length} agents (${agents.map((a) => a.name).join(", ")}); pass agentName to pick one.`
+  );
+}
+function assertValidPort(port) {
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new CoderAgentError(`Invalid port ${port}: expected an integer between 1 and 65535.`);
+  }
+  if (port < 1e3) {
+    throw new CoderAgentError(
+      `Port ${port} cannot be previewed: Coder subdomain app URLs only encode 4-5 digit ports (1000-65535). Serve the preview on a higher port instead.`
+    );
+  }
+}
+async function resolveWorkspacePreview(conn, opts, signal) {
+  assertValidPort(opts.port);
+  const [workspace, appHost] = await Promise.all([
+    getWorkspace(conn, opts.workspaceId, signal),
+    getAppsHost(conn, signal)
+  ]);
+  if (!appHost.host) {
+    throw new CoderAgentError(
+      "This Coder deployment has no wildcard app host configured (--wildcard-access-url), so subdomain preview URLs are unavailable."
+    );
+  }
+  const agentName = opts.agentName ?? defaultAgentName(workspace);
+  const suffix = opts.protocol === "https" ? "s" : "";
+  const label = `${opts.port}${suffix}--${agentName}--${workspace.name}--${workspace.owner_name}`;
+  const scheme = new URL(conn.baseUrl).protocol;
+  return { url: `${scheme}//${appHost.host.replace(/\*/g, label)}`, agentName };
+}
+async function shareWorkspacePreview(conn, opts, signal) {
+  const requested = opts.shareLevel ?? "authenticated";
+  const { url, agentName } = await resolveWorkspacePreview(conn, opts, signal);
+  const share = await upsertPortShare(
+    conn,
+    opts.workspaceId,
+    {
+      agent_name: agentName,
+      port: opts.port,
+      share_level: requested,
+      protocol: opts.protocol ?? "http"
+    },
+    signal
+  );
+  const level = share?.share_level && share.share_level !== "owner" ? share.share_level : requested;
+  return { url, shareLevel: level };
+}
+
 // src/model/prompt.ts
 var CODER_PROVIDER_OPTIONS = "coder";
 function extractSystemPrompt(prompt) {
@@ -529,7 +895,10 @@ function mapUsage(u) {
       total: u?.output_tokens,
       text: void 0,
       reasoning: u?.reasoning_tokens
-    }
+    },
+    // Preserve the verbatim wire usage (snake_case) so callers can reach fields
+    // the normalized shape has no slot for (context_limit, cost, runtime, …).
+    ...u ? { raw: u } : {}
   };
 }
 function jsonResult(value) {
@@ -541,10 +910,15 @@ var TurnTranslator = class {
   #text = { id: void 0, len: 0, sawDelta: false };
   #reasoning = { id: void 0, len: 0, sawDelta: false };
   #currentAssistantId;
+  // Whether text/reasoning deltas arrived since the last assistant `message`
+  // snapshot — i.e. the next assistant snapshot is the trailing snapshot of the
+  // message those deltas streamed (deltas carry no message id of their own).
+  #deltasSinceSnapshot = false;
   #serverToolCalls = /* @__PURE__ */ new Set();
   #serverToolResults = /* @__PURE__ */ new Set();
   #clientToolCalls = /* @__PURE__ */ new Set();
   #clientToolCallSeen = false;
+  #sources = /* @__PURE__ */ new Set();
   #usage;
   #error;
   #terminalStatus;
@@ -667,6 +1041,26 @@ var TurnTranslator = class {
       dynamic: true
     });
   }
+  /**
+   * Emits a chatd `source` part as a standalone V4 url source (no text-block
+   * bracketing needed). Deduped by the emitted id so a part streamed as a
+   * `message_part` isn't re-emitted by its trailing `message` snapshot, while
+   * snapshot-only turns still emit theirs.
+   */
+  #emitSource(out, part) {
+    const url = part.url;
+    if (!url) return;
+    const id = part.source_id || url;
+    if (this.#sources.has(id)) return;
+    this.#sources.add(id);
+    out.push({
+      type: "source",
+      sourceType: "url",
+      id,
+      url,
+      ...part.title !== void 0 ? { title: part.title } : {}
+    });
+  }
   // --- ingest ---------------------------------------------------------------
   ingest(ev) {
     const out = [];
@@ -717,6 +1111,7 @@ var TurnTranslator = class {
     switch (part.type) {
       case "text":
         this.#text.sawDelta = true;
+        this.#deltasSinceSnapshot = true;
         this.#openText(out);
         if (part.text) {
           out.push({ type: "text-delta", id: this.#text.id, delta: part.text });
@@ -725,6 +1120,7 @@ var TurnTranslator = class {
         break;
       case "reasoning":
         this.#reasoning.sawDelta = true;
+        this.#deltasSinceSnapshot = true;
         this.#openReasoning(out);
         if (part.text) {
           out.push({ type: "reasoning-delta", id: this.#reasoning.id, delta: part.text });
@@ -739,6 +1135,9 @@ var TurnTranslator = class {
       case "tool-result":
         if (!this.#isClientTool(part.tool_name)) this.#emitServerToolResult(out, part);
         break;
+      case "source":
+        this.#emitSource(out, part);
+        break;
       default:
         break;
     }
@@ -750,7 +1149,7 @@ var TurnTranslator = class {
     }
     const content = message.content ?? [];
     if (message.role === "assistant") {
-      if (this.#currentAssistantId !== void 0 && this.#currentAssistantId !== message.id) {
+      if (this.#currentAssistantId !== void 0 && this.#currentAssistantId !== message.id && !this.#deltasSinceSnapshot) {
         this.#closeText(out);
         this.#closeReasoning(out);
         this.#text.sawDelta = false;
@@ -770,11 +1169,14 @@ var TurnTranslator = class {
           this.#emitServerToolCall(out, part);
         else if (part.type === "tool-result" && !this.#isClientTool(part.tool_name))
           this.#emitServerToolResult(out, part);
+        else if (part.type === "source") this.#emitSource(out, part);
       }
+      this.#deltasSinceSnapshot = false;
     } else if (message.role === "tool") {
       for (const part of content) {
         if (part.type === "tool-result" && !this.#isClientTool(part.tool_name))
           this.#emitServerToolResult(out, part);
+        else if (part.type === "source") this.#emitSource(out, part);
       }
     }
   }
@@ -788,10 +1190,16 @@ var TurnTranslator = class {
     else if (this.#clientToolCallSeen || this.#terminalStatus === "requires_action")
       unified = "tool-calls";
     else unified = "stop";
+    const coder = {};
+    if (this.#usage?.total_cost_micros !== void 0)
+      coder.total_cost_micros = this.#usage.total_cost_micros;
+    if (this.#usage?.total_runtime_ms !== void 0)
+      coder.total_runtime_ms = this.#usage.total_runtime_ms;
     out.push({
       type: "finish",
       usage: mapUsage(this.#usage),
-      finishReason: { unified, raw: this.#terminalStatus }
+      finishReason: { unified, raw: this.#terminalStatus },
+      ...Object.keys(coder).length > 0 ? { providerMetadata: { coder } } : {}
     });
     return out;
   }
@@ -808,7 +1216,7 @@ var EMPTY_USAGE = {
   outputTokens: { total: void 0, text: void 0, reasoning: void 0 }
 };
 var CoderLanguageModel = class {
-  specificationVersion = "v3";
+  specificationVersion = "v4";
   provider = "coder.chatd";
   modelId;
   supportedUrls = {};
@@ -820,6 +1228,7 @@ var CoderLanguageModel = class {
   #submittedToolCallIds = /* @__PURE__ */ new Set();
   #inFlight = false;
   constructor(config) {
+    assertSupportedAiVersion();
     this.#config = config;
     this.modelId = config.model ?? "chatd";
     this.#chatId = config.chatId;
@@ -1035,6 +1444,7 @@ var CoderLanguageModel = class {
       unified: "stop",
       raw: void 0
     };
+    let providerMetadata;
     const warnings = [];
     for await (const part of this.#runTurn(options)) {
       switch (part.type) {
@@ -1074,6 +1484,7 @@ var CoderLanguageModel = class {
         case "finish":
           usage = part.usage;
           finishReason = part.finishReason;
+          providerMetadata = part.providerMetadata;
           break;
         case "error":
           throw part.error instanceof Error ? part.error : new CoderChatError({ message: String(part.error) });
@@ -1081,7 +1492,13 @@ var CoderLanguageModel = class {
           break;
       }
     }
-    return { content, finishReason, usage, warnings };
+    return {
+      content,
+      finishReason,
+      usage,
+      warnings,
+      ...providerMetadata ? { providerMetadata } : {}
+    };
   }
 };
 
@@ -1099,7 +1516,48 @@ function makeChatAttachment(file) {
     })
   };
 }
-var DEFAULT_STOP = stepCountIs(64);
+var DEFAULT_STOP = isStepCount(64);
+var SETTLE_DEADLINE_MS = 15e3;
+var SETTLE_RETRY_DELAY_MS = 1e3;
+function sanitizeDelayMs(value, fallback) {
+  const MAX_TIMER_MS = 2 ** 31 - 1;
+  if (value === void 0 || Number.isNaN(value)) return fallback;
+  if (value === Number.POSITIVE_INFINITY) return MAX_TIMER_MS;
+  if (!Number.isFinite(value) || value < 0) return fallback;
+  return Math.min(Math.floor(value), MAX_TIMER_MS);
+}
+function sleep2(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal?.reason);
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+async function archiveWhenSettled(client, chatId, opts) {
+  const timeout = AbortSignal.timeout(opts.deadlineMs);
+  const signal = opts.signal ? AbortSignal.any([opts.signal, timeout]) : timeout;
+  const deadline = Date.now() + opts.deadlineMs;
+  for (; ; ) {
+    try {
+      await client.archiveChat(chatId, signal);
+      return;
+    } catch (err) {
+      if (!(err instanceof CoderApiError) || err.status !== 409) throw err;
+      if (Date.now() + opts.retryDelayMs > deadline) throw err;
+      await sleep2(opts.retryDelayMs, opts.signal);
+    }
+  }
+}
 var CoderAgent = class {
   version = "agent-v1";
   #client;
@@ -1107,7 +1565,12 @@ var CoderAgent = class {
   #inner;
   #organizationId;
   #workspaceFiles;
+  #workspaceId;
+  #workspaceApi;
+  #settleDeadlineMs;
+  #settleRetryDelayMs;
   constructor(settings) {
+    assertSupportedAiVersion();
     if (settings.client) {
       this.#client = settings.client;
     } else if (settings.baseUrl && settings.token) {
@@ -1124,6 +1587,10 @@ var CoderAgent = class {
     }
     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.#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) {
       throw new CoderAgentError(
         `workspaceFiles.workspaceId (${settings.workspaceFiles.workspaceId}) does not match the agent's workspaceId (${settings.workspaceId}); the chat's tools would not see uploaded files.`
@@ -1144,6 +1611,7 @@ var CoderAgent = class {
       id: settings.id,
       instructions: settings.instructions,
       tools: settings.tools,
+      toolsContext: settings.toolsContext,
       toolChoice: settings.toolChoice,
       stopWhen: settings.stopWhen ?? DEFAULT_STOP,
       maxRetries: settings.maxRetries ?? 0
@@ -1182,22 +1650,41 @@ var CoderAgent = class {
   resetSession() {
     this.#model.resetSession();
   }
-  /** Interrupt the in-flight generation, if any. */
-  async interrupt() {
+  /**
+   * 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}).
+   */
+  async interrupt(opts) {
     const id = this.#model.chatId;
-    if (id) await this.#client.interruptChat(id);
+    if (id) await this.#client.interruptChat(id, opts?.signal);
   }
-  /** Archive the underlying chat (safe cleanup; hides it from listings). */
-  async archive() {
+  /**
+   * Archive the underlying chat (safe cleanup; hides it from listings).
+   *
+   * 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.
+   */
+  async archive(opts) {
     const id = this.#model.chatId;
-    if (id) await this.#client.archiveChat(id);
+    if (!id) return;
+    await archiveWhenSettled(this.#client, id, {
+      deadlineMs: this.#settleDeadlineMs,
+      retryDelayMs: this.#settleRetryDelayMs,
+      signal: opts?.signal
+    });
   }
   /**
    * 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.
-   * Best-effort: disposal errors are swallowed so they can't mask the scope's
-   * own error.
+   * `finally`. Interrupts any in-flight server run, then archives the chat
+   * (retrying while the interrupted run settles). 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.
    *
    * @example
    * ```ts
@@ -1207,12 +1694,13 @@ var CoderAgent = class {
    * ```
    */
   async [Symbol.asyncDispose]() {
+    const deadline = AbortSignal.timeout(this.#settleDeadlineMs);
     try {
-      await this.interrupt();
+      await this.interrupt({ signal: deadline });
     } catch {
     }
     try {
-      await this.archive();
+      await this.archive({ signal: deadline });
     } catch {
     }
   }
@@ -1256,7 +1744,158 @@ var CoderAgent = class {
     });
     return { workspaceId: this.#workspaceFiles.workspaceId, path };
   }
+  // --- previews ---------------------------------------------------------------
+  /** The v2 connection + workspace id the preview helpers need, or a clear error. */
+  #previewContext(method) {
+    if (!this.#workspaceId) {
+      throw new CoderAgentError(
+        `${method}() requires the agent to be bound to a workspace \u2014 construct the CoderAgent with the \`workspaceId\` setting.`
+      );
+    }
+    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\`).`
+      );
+    }
+    return { conn: this.#workspaceApi, workspaceId: this.#workspaceId };
+  }
+  /**
+   * Resolve the browser URL where a port on the bound workspace can be
+   * previewed, e.g. `https://3000--main--dev--alice.apps.example.com`.
+   * Composed from stable v2 endpoints (workspace lookup + wildcard app host),
+   * so it works against old Coder servers. Requires the `workspaceId` setting,
+   * `baseUrl`/`token` credentials, and a deployment with a wildcard access URL
+   * configured.
+   *
+   * The URL honors the port's current share level — private to the workspace
+   * owner unless shared (see {@link CoderAgent.sharePreview}).
+   */
+  async getPreview(opts) {
+    const { conn, workspaceId } = this.#previewContext("getPreview");
+    const { url } = await resolveWorkspacePreview(
+      conn,
+      { workspaceId, port: opts.port, agentName: opts.agentName, protocol: opts.protocol },
+      opts.signal
+    );
+    return { url };
+  }
+  /**
+   * Share a port on the bound workspace and return its preview URL. Upserts
+   * the port's share level — `authenticated` by default — so teammates (or,
+   * with `public`, anyone) can open what the agent is serving; re-invoking
+   * updates the level in place. On Coder servers that predate port sharing
+   * (< v2.9) this fails with a 404 {@link CoderApiError} saying so.
+   */
+  async sharePreview(opts) {
+    const { conn, workspaceId } = this.#previewContext("sharePreview");
+    return shareWorkspacePreview(
+      conn,
+      {
+        workspaceId,
+        port: opts.port,
+        agentName: opts.agentName,
+        protocol: opts.protocol,
+        shareLevel: opts.shareLevel
+      },
+      opts.signal
+    );
+  }
 };
+
+// src/model/history.ts
+function toolErrorText(result) {
+  if (typeof result === "string") return result;
+  if (result === void 0 || result === null) return "";
+  return JSON.stringify(result) ?? "";
+}
+function toDynamicToolPart(call, result) {
+  const toolCallId = call.tool_call_id;
+  const toolName = call.tool_name;
+  if (!toolCallId || !toolName) return void 0;
+  const providerExecuted = call.provider_executed ?? result?.provider_executed;
+  const base = {
+    type: "dynamic-tool",
+    toolName,
+    toolCallId,
+    ...providerExecuted !== void 0 ? { providerExecuted } : {}
+  };
+  if (!result) return { ...base, state: "input-available", input: call.args };
+  if (result.is_error) {
+    return {
+      ...base,
+      state: "output-error",
+      input: call.args,
+      errorText: toolErrorText(result.result)
+    };
+  }
+  return { ...base, state: "output-available", input: call.args, output: result.result };
+}
+function toUIParts(content, resultsByCallId, opts) {
+  const parts = [];
+  for (const part of content) {
+    switch (part.type) {
+      case "text":
+        parts.push({ type: "text", text: part.text ?? "", state: "done" });
+        break;
+      case "reasoning":
+        parts.push({ type: "reasoning", text: part.text ?? "", state: "done" });
+        break;
+      case "tool-call": {
+        const result = part.tool_call_id ? resultsByCallId.get(part.tool_call_id) : void 0;
+        const ui = toDynamicToolPart(part, result);
+        if (ui) parts.push(ui);
+        break;
+      }
+      case "source":
+        if (part.url) {
+          parts.push({
+            type: "source-url",
+            sourceId: part.source_id || part.url,
+            url: part.url,
+            ...part.title ? { title: part.title } : {}
+          });
+        }
+        break;
+      case "file": {
+        const url = opts?.fileUrl?.(part) ?? part.url;
+        if (url) {
+          parts.push({
+            type: "file",
+            mediaType: part.media_type ?? "application/octet-stream",
+            ...part.name ? { filename: part.name } : {},
+            url
+          });
+        }
+        break;
+      }
+      case "tool-result":
+        break;
+      default:
+        break;
+    }
+  }
+  return parts;
+}
+function chatMessagesToUIMessages(messages, opts) {
+  const ordered = [...messages].sort((a, b) => a.id - b.id);
+  const resultsByCallId = /* @__PURE__ */ new Map();
+  for (const message of ordered) {
+    for (const part of message.content ?? []) {
+      if (part.type !== "tool-result" || !part.tool_call_id) continue;
+      if (!resultsByCallId.has(part.tool_call_id)) resultsByCallId.set(part.tool_call_id, part);
+    }
+  }
+  const out = [];
+  for (const message of ordered) {
+    if (message.role === "tool") continue;
+    out.push({
+      id: String(message.id),
+      role: message.role,
+      parts: toUIParts(message.content ?? [], resultsByCallId, opts)
+    });
+  }
+  return out;
+}
 export {
   CHAT_ATTACHMENT_MEDIA_TYPES,
   CODER_PROVIDER_OPTIONS,
@@ -1268,6 +1907,7 @@ export {
   CoderLanguageModel,
   MAX_CHAT_FILE_SIZE_BYTES,
   TurnTranslator,
+  chatMessagesToUIMessages,
   classifyTurnAction,
   dataContentToFileContent,
   dynamicToolNames,
@@ -1275,6 +1915,7 @@ export {
   resolveFileContent,
   streamChatEvents,
   toolsToDynamicTools,
-  userContentToInputParts
+  userContentToInputParts,
+  watchChatEvents
 };
 //# sourceMappingURL=index.js.map