@gitterm/sdk 0.1.2 → 0.2.0

package/dist/index.js

@@ -1,5 +1,12 @@
 // src/client.ts
-import { createTRPCClient, httpBatchLink, TRPCClientError } from "@trpc/client";
+import {
+  createTRPCClient,
+  httpBatchLink,
+  httpSubscriptionLink,
+  splitLink,
+  TRPCClientError
+} from "@trpc/client";
+import { EventSource } from "eventsource";
 
 // src/config.ts
 import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
@@ -51,6 +58,14 @@ async function deleteConfig(configPath) {
 }
 
 // src/errors.ts
+var WORKSPACE_LIFECYCLE_ERROR_CODES = [
+  "WORKSPACE_NOT_RUNNING",
+  "WORKSPACE_TERMINATED",
+  "WORKSPACE_NON_RECOVERABLE",
+  "WORKSPACE_START_TIMEOUT",
+  "WORKSPACE_RESTART_FAILED"
+];
+
 class GittermError extends Error {
   code;
   cause;
@@ -69,6 +84,15 @@ class WorkspaceLifecycleError extends GittermError {
   }
 }
 
+class AgentRunError extends GittermError {
+  run;
+  constructor(run, code) {
+    super(code, run.error ?? (code === "INPUT_REQUIRED" ? "The agent needs input; supply a handler or use runs.respond()" : `Agent run ${run.status}`));
+    this.run = run;
+    this.name = "AgentRunError";
+  }
+}
+
 // src/transport.ts
 var LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
 function normalizeServerUrl(value) {
@@ -99,6 +123,152 @@ function createNoRedirectFetch(fetchImpl = fetch) {
   };
 }
 
+// src/runs.ts
+function terminal(status) {
+  return status === "completed" || status === "failed" || status === "cancelled";
+}
+function aborted(signal) {
+  if (signal?.aborted)
+    throw new GittermError("ABORTED", "Run observation was aborted; the agent was not cancelled");
+}
+async function abortable(operation, signal) {
+  if (signal.aborted)
+    operation.catch(() => {});
+  aborted(signal);
+  let onAbort;
+  try {
+    return await Promise.race([
+      operation,
+      new Promise((_, reject) => {
+        onAbort = () => reject(new GittermError("ABORTED", "Run observation was aborted; the agent was not cancelled"));
+        signal.addEventListener("abort", onAbort, { once: true });
+      })
+    ]);
+  } finally {
+    if (onAbort)
+      signal.removeEventListener("abort", onAbort);
+  }
+}
+function delay(ms, signal) {
+  aborted(signal);
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new GittermError("ABORTED", "Operation aborted"));
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+async function deadline(options, operation) {
+  aborted(options?.signal);
+  const timeoutMs = options?.timeoutMs ?? 30 * 60000;
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 0)
+    throw new GittermError("BAD_REQUEST", "timeoutMs must be finite and non-negative");
+  const controller = new AbortController;
+  const onAbort = () => controller.abort();
+  options?.signal?.addEventListener("abort", onAbort, { once: true });
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, timeoutMs);
+  try {
+    return await operation(controller.signal);
+  } catch (error) {
+    if (timedOut)
+      throw new GittermError("TIMEOUT", "Run observation timed out; the agent was not cancelled", {
+        cause: error
+      });
+    aborted(options?.signal);
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    options?.signal?.removeEventListener("abort", onAbort);
+    controller.abort();
+  }
+}
+async function* runEvents(states) {
+  const seen = new Set;
+  let pending = new Set;
+  let status;
+  for await (const run of states) {
+    if (run.status !== status) {
+      status = run.status;
+      yield { type: "run.status", run };
+    }
+    const current = new Set(run.pendingInputs.map((request) => request.id));
+    for (const requestId of pending) {
+      if (!current.has(requestId))
+        yield { type: "input.resolved", run, requestId };
+    }
+    pending = current;
+    for (const request of run.pendingInputs) {
+      if (seen.has(request.id))
+        continue;
+      seen.add(request.id);
+      yield { type: "input.required", run, request };
+    }
+    if (run.status === "completed" || run.status === "failed" || run.status === "cancelled") {
+      yield { type: `run.${run.status}`, run };
+      return;
+    }
+  }
+}
+function runHelpers(operations) {
+  return {
+    events: (ref, options) => runEvents(operations.watch(ref, options)),
+    wait: (ref, options) => deadline(options, async (signal) => {
+      for await (const run of operations.watch(ref, { signal })) {
+        if (terminal(run.status) || run.status === "awaiting_input" && options?.until !== "terminal")
+          return run;
+      }
+      throw new GittermError("NETWORK", "Run stream ended before a terminal state");
+    }),
+    result: (ref, options) => deadline(options, async (signal) => {
+      for await (const event of runEvents(operations.watch(ref, { signal }))) {
+        aborted(signal);
+        if (event.type === "run.completed")
+          return event.run;
+        if (event.type === "run.failed")
+          throw new AgentRunError(event.run, "RUN_FAILED");
+        if (event.type === "run.cancelled")
+          throw new AgentRunError(event.run, "RUN_CANCELLED");
+        if (event.type !== "input.required")
+          continue;
+        const { request } = event;
+        let reply;
+        if (request.kind === "permission") {
+          if (!options?.onPermission)
+            throw new AgentRunError(event.run, "INPUT_REQUIRED");
+          reply = {
+            type: "permission",
+            response: await abortable(Promise.resolve(options.onPermission(request, { signal })), signal)
+          };
+        } else {
+          if (!options?.onQuestion)
+            throw new AgentRunError(event.run, "INPUT_REQUIRED");
+          reply = {
+            type: "question",
+            ...await abortable(Promise.resolve(options.onQuestion(request, { signal })), signal)
+          };
+        }
+        aborted(signal);
+        try {
+          await abortable(operations.respond(ref, { requestId: request.id, reply }), signal);
+        } catch (error) {
+          if (!(error instanceof GittermError) || error.code !== "INPUT_NOT_PENDING")
+            throw error;
+        }
+      }
+      throw new GittermError("NETWORK", "Run stream ended before a terminal state");
+    })
+  };
+}
+
 // src/client.ts
 function envValue(name) {
   const value = typeof process !== "undefined" ? process.env[name] : undefined;
@@ -129,6 +299,29 @@ function normalizeBaseCommit(value) {
     return null;
   return /^[0-9a-f]{40}([0-9a-f]{24})?$/i.test(trimmed) ? trimmed.toLowerCase() : trimmed;
 }
+function workspaceIdOf(ref) {
+  return typeof ref === "string" ? ref : ref.id;
+}
+function runTargetOf(ref) {
+  return { workspaceId: ref.workspaceId, runId: ref.id };
+}
+function throwIfAborted(signal, what) {
+  if (signal?.aborted)
+    throw new GittermError("ABORTED", `Aborted while ${what}`);
+}
+function sleep(ms, signal, what) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new GittermError("ABORTED", `Aborted while ${what}`));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
 function normalizeWorkspace(workspace) {
   if (!workspace)
     return null;
@@ -157,6 +350,10 @@ function normalizeWorkspace(workspace) {
       name: workspace.image.name,
       imageId: workspace.image.imageId
     } : null,
+    metadata: workspace.metadata ?? {},
+    opencodeApi: workspace.opencodeApi ?? "v1",
+    autoTerminateAt: toIso(workspace.autoTerminateAt),
+    customImage: workspace.customImage ?? null,
     startedAt: toIso(workspace.startedAt),
     pausedAt: toIso(workspace.pausedAt),
     terminatedAt: toIso(workspace.terminatedAt),
@@ -193,6 +390,8 @@ function mapTrpcCode(code) {
       return "BAD_REQUEST";
     case "CONFLICT":
       return "CONFLICT";
+    case "TIMEOUT":
+      return "TIMEOUT";
     default:
       return "SERVER_ERROR";
   }
@@ -201,58 +400,113 @@ function credentialErrorCode(message) {
   const match = /^(MODEL_CREDENTIAL_(?:UNAVAILABLE|DUPLICATE_PROVIDER|INVALID|REQUIRED)):\s*/.exec(message);
   return match?.[1];
 }
+function toGittermError(serverUrl, error) {
+  if (error instanceof GittermError)
+    return error;
+  if (error instanceof TRPCClientError) {
+    const data = error.data;
+    const trpcCode = data?.code;
+    if (!error.data) {
+      return new GittermError("NETWORK", `Could not reach the GitTerm server at ${serverUrl}`, {
+        cause: error
+      });
+    }
+    const code = mapTrpcCode(trpcCode);
+    const structuredLifecycleCode = WORKSPACE_LIFECYCLE_ERROR_CODES.find((candidate) => candidate === data?.workspaceLifecycleCode);
+    if (structuredLifecycleCode) {
+      return new WorkspaceLifecycleError(structuredLifecycleCode, error.message, { cause: error });
+    }
+    if (error.message.startsWith("INPUT_NOT_PENDING:"))
+      return new GittermError("INPUT_NOT_PENDING", error.message, { cause: error });
+    const credentialCode = credentialErrorCode(error.message);
+    if (credentialCode)
+      return new GittermError(credentialCode, error.message, { cause: error });
+    const lifecycleCode = WORKSPACE_LIFECYCLE_ERROR_CODES.find((candidate) => error.message.startsWith(`${candidate}:`));
+    if (lifecycleCode) {
+      return new WorkspaceLifecycleError(lifecycleCode, error.message, { cause: error });
+    }
+    return new GittermError(code, code === "UNAUTHORIZED" ? `Authentication failed: ${error.message}. Check that the API token is valid and has not expired.` : error.message, { cause: error });
+  }
+  return new GittermError("NETWORK", error instanceof Error ? error.message : "Network request failed", { cause: error });
+}
 async function runWithServer(serverUrl, operation) {
   try {
     return await operation();
   } catch (error) {
-    if (error instanceof GittermError)
-      throw error;
-    if (error instanceof TRPCClientError) {
-      const trpcCode = error.data?.code;
-      if (!error.data) {
-        throw new GittermError("NETWORK", `Could not reach the GitTerm server at ${serverUrl}`, {
-          cause: error
-        });
-      }
-      const code = mapTrpcCode(trpcCode);
-      const credentialCode = credentialErrorCode(error.message);
-      if (credentialCode)
-        throw new GittermError(credentialCode, error.message, { cause: error });
-      if (/WORKSPACE_TERMINATED/.test(error.message)) {
-        throw new WorkspaceLifecycleError("WORKSPACE_TERMINATED", error.message, { cause: error });
-      }
-      if (/WORKSPACE_NON_RECOVERABLE/.test(error.message)) {
-        throw new WorkspaceLifecycleError("WORKSPACE_NON_RECOVERABLE", error.message, {
-          cause: error
-        });
-      }
-      if (/WORKSPACE_START_TIMEOUT/.test(error.message)) {
-        throw new WorkspaceLifecycleError("WORKSPACE_START_TIMEOUT", error.message, {
-          cause: error
-        });
-      }
-      if (/WORKSPACE_RESTART_FAILED/.test(error.message)) {
-        throw new WorkspaceLifecycleError("WORKSPACE_RESTART_FAILED", error.message, {
-          cause: error
-        });
-      }
-      throw new GittermError(code, code === "UNAUTHORIZED" ? `Authentication failed: ${error.message}. Check that the API token is valid and has not expired.` : error.message, { cause: error });
+    throw toGittermError(serverUrl, error);
+  }
+}
+function isTerminalRun(status) {
+  return status === "completed" || status === "failed" || status === "cancelled";
+}
+async function* watchRun(trpc, serverUrl, target, options) {
+  const what = `watching run ${target.runId}`;
+  throwIfAborted(options?.signal, what);
+  const queue = [];
+  let wake;
+  const push = (item) => {
+    queue.push(item);
+    wake?.();
+    wake = undefined;
+  };
+  const onAbort = () => push({ error: new GittermError("ABORTED", `Aborted while ${what}`) });
+  options?.signal?.addEventListener("abort", onAbort, { once: true });
+  let last;
+  const subscription = trpc.run.lifecycle.subscribe(target, {
+    onData: (event) => {
+      last = event.run;
+      push({ run: last });
+    },
+    onError: (error) => push({ error }),
+    onComplete: () => push(last && isTerminalRun(last.status) ? { done: true } : {
+      error: new GittermError("NETWORK", `Run ${target.runId} event stream ended unexpectedly`)
+    })
+  });
+  try {
+    while (true) {
+      throwIfAborted(options?.signal, what);
+      if (queue.length === 0)
+        await new Promise((resolve) => wake = resolve);
+      const item = queue.shift();
+      if ("done" in item)
+        return;
+      if ("error" in item)
+        throw toGittermError(serverUrl, item.error);
+      yield item.run;
+      if (isTerminalRun(item.run.status))
+        return;
     }
-    throw new GittermError("NETWORK", error instanceof Error ? error.message : "Network request failed", { cause: error });
+  } finally {
+    options?.signal?.removeEventListener("abort", onAbort);
+    subscription.unsubscribe();
   }
 }
 function createGittermClient(options = {}) {
   const credentials = resolveCredentials(options);
+  const fetchImpl = createNoRedirectFetch(options.fetch);
+  const authorization = `Bearer ${credentials.token}`;
   const trpc = createTRPCClient({
     links: [
-      httpBatchLink({
-        url: toTrpcUrl(credentials.serverUrl),
-        fetch: createNoRedirectFetch(options.fetch),
-        headers: () => ({ authorization: `Bearer ${credentials.token}` })
+      splitLink({
+        condition: (operation) => operation.type === "subscription",
+        true: httpSubscriptionLink({
+          url: toTrpcUrl(credentials.serverUrl),
+          EventSource,
+          eventSourceOptions: {
+            fetch: (url, init) => fetchImpl(url, { ...init, headers: { ...init.headers, authorization } })
+          }
+        }),
+        false: httpBatchLink({
+          url: toTrpcUrl(credentials.serverUrl),
+          fetch: fetchImpl,
+          headers: () => ({ authorization })
+        })
       })
     ]
   });
   const run = (operation) => runWithServer(credentials.serverUrl, operation);
+  const watch = (ref, watchOptions) => watchRun(trpc, credentials.serverUrl, runTargetOf(ref), watchOptions);
+  const respond = (ref, input) => run(async () => trpc.run.respond.mutate({ ...runTargetOf(ref), ...input }));
   const normalizeCreateResult = (result) => {
     const workspace = normalizeWorkspace(result.workspace);
     if (!workspace)
@@ -279,9 +533,11 @@ function createGittermClient(options = {}) {
   const waitForWorkspaceSetup = async (workspaceId, waitOptions) => {
     const timeoutMs = waitOptions?.timeoutMs ?? 10 * 60000;
     const pollIntervalMs = waitOptions?.pollIntervalMs ?? 2000;
-    const deadline = Date.now() + timeoutMs;
+    const signal = waitOptions?.signal;
+    const deadline2 = Date.now() + timeoutMs;
     while (true) {
-      const result = await trpc.workspace.getSetupStatus.query({ workspaceId });
+      throwIfAborted(signal, "waiting for workspace setup");
+      const result = await trpc.workspace.getSetupStatus.query({ workspaceId }, { signal });
       if (result.status === "not_requested" || result.status === "succeeded")
         return result;
       if (result.status === "failed") {
@@ -289,12 +545,12 @@ function createGittermClient(options = {}) {
         throw new GittermError("BAD_REQUEST", `Workspace setup failed${result.exitCode === null ? "" : ` with exit code ${result.exitCode}`}${log ? `
 ${log}` : ""}`);
       }
-      if (Date.now() >= deadline) {
+      if (Date.now() >= deadline2) {
         const log = result.log?.trim();
-        throw new GittermError("NETWORK", `Timed out waiting for workspace ${workspaceId} setup (last status: ${result.status})${log ? `
+        throw new GittermError("TIMEOUT", `Timed out waiting for workspace ${workspaceId} setup (last status: ${result.status})${log ? `
 ${log}` : ""}`);
       }
-      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+      await sleep(pollIntervalMs, signal, "waiting for workspace setup");
     }
   };
   return {
@@ -316,27 +572,32 @@ ${log}` : ""}`);
       list: (input) => run(async () => {
         const result = await trpc.workspace.listWorkspaces.query(input);
         return {
-          workspaces: result.workspaces.map((workspace) => normalizeWorkspace(workspace)),
+          workspaces: result.workspaces.map(normalizeWorkspace).filter((workspace) => workspace !== null),
           pagination: result.pagination
         };
       }),
-      get: (workspaceId) => run(async () => {
-        const result = await trpc.workspace.getWorkspace.query({ workspaceId });
+      get: (ref) => run(async () => {
+        const result = await trpc.workspace.getWorkspace.query({
+          workspaceId: workspaceIdOf(ref)
+        });
         const workspace = normalizeWorkspace(result.workspace);
         if (!workspace)
           throw new GittermError("NOT_FOUND", "Workspace not found");
         return workspace;
       }),
-      getRuntimeAccess: (workspaceId) => run(async () => {
-        const result = await trpc.workspace.getRuntimeAccess.query({ workspaceId });
+      getRuntimeAccess: (ref) => run(async () => {
+        const result = await trpc.workspace.getRuntimeAccess.query({
+          workspaceId: workspaceIdOf(ref)
+        });
         return normalizeRuntime(result);
       }),
-      ensureRunning: (workspaceId, options2) => run(async () => {
+      ensureRunning: (ref, waitOptions) => run(async () => {
+        throwIfAborted(waitOptions?.signal, "ensuring the workspace is running");
         const result = await trpc.workspace.ensureRunning.mutate({
-          workspaceId,
-          timeoutMs: options2?.timeoutMs,
-          pollIntervalMs: options2?.pollIntervalMs
-        });
+          workspaceId: workspaceIdOf(ref),
+          timeoutMs: waitOptions?.timeoutMs,
+          pollIntervalMs: waitOptions?.pollIntervalMs
+        }, { signal: waitOptions?.signal });
         const workspace = normalizeWorkspace(result.workspace);
         if (!workspace)
           throw new GittermError("SERVER_ERROR", "ensureRunning failed");
@@ -345,44 +606,62 @@ ${log}` : ""}`);
           runtime: normalizeRuntime(result.runtime)
         };
       }),
-      pause: (workspaceId) => run(async () => {
-        const result = await trpc.workspace.pauseWorkspace.mutate({ workspaceId });
+      pause: (ref) => run(async () => {
+        const result = await trpc.workspace.pauseWorkspace.mutate({
+          workspaceId: workspaceIdOf(ref)
+        });
         return { durationMinutes: result.durationMinutes };
       }),
-      restart: (workspaceId) => run(async () => {
-        const result = await trpc.workspace.restartWorkspace.mutate({ workspaceId });
+      restart: (ref) => run(async () => {
+        const result = await trpc.workspace.restartWorkspace.mutate({
+          workspaceId: workspaceIdOf(ref)
+        });
         return { status: result.status };
       }),
-      terminate: (workspaceId) => run(async () => {
-        const result = await trpc.workspace.deleteWorkspace.mutate({ workspaceId });
+      terminate: (ref) => run(async () => {
+        const result = await trpc.workspace.deleteWorkspace.mutate({
+          workspaceId: workspaceIdOf(ref)
+        });
         return {
           workspace: normalizeWorkspace(result.workspace),
           cleanupInBackground: result.cleanupInBackground
         };
       }),
       create: createWorkspace,
-      setupStatus: (workspaceId) => run(async () => trpc.workspace.getSetupStatus.query({ workspaceId })),
-      waitForSetup: (workspaceId, waitOptions) => run(() => waitForWorkspaceSetup(workspaceId, waitOptions))
+      models: (ref) => run(() => trpc.workspace.getModelAccess.query({ workspaceId: workspaceIdOf(ref) })),
+      setupStatus: (ref) => run(async () => trpc.workspace.getSetupStatus.query({ workspaceId: workspaceIdOf(ref) })),
+      waitForSetup: (ref, waitOptions) => run(() => waitForWorkspaceSetup(workspaceIdOf(ref), waitOptions))
     },
     runs: {
-      create: (input) => run(async () => trpc.run.create.mutate(input)),
-      get: (workspaceId, runId) => run(async () => trpc.run.get.query({ workspaceId, runId })),
-      messages: (workspaceId, runId) => run(async () => trpc.run.messages.query({ workspaceId, runId })),
-      cancel: (workspaceId, runId) => run(async () => trpc.run.cancel.mutate({ workspaceId, runId })),
-      wait: (workspaceId, runId, waitOptions) => run(async () => {
-        const timeoutMs = waitOptions?.timeoutMs ?? 30 * 60000;
-        const pollIntervalMs = waitOptions?.pollIntervalMs ?? 2000;
-        const deadline = Date.now() + timeoutMs;
-        while (true) {
-          const result = await trpc.run.get.query({ workspaceId, runId });
-          if (result.status !== "pending" && result.status !== "running" && result.status !== "retrying")
-            return result;
-          if (Date.now() >= deadline) {
-            throw new GittermError("NETWORK", `Timed out waiting for run ${runId}`);
-          }
-          await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+      create: (input) => run(async () => {
+        const { signal, workspace, ...rest } = input;
+        const request = {
+          ...rest,
+          workspaceId: workspaceIdOf(workspace),
+          context: rest.context?.type === "continue" ? { type: "continue", runId: rest.context.run.id } : rest.context
+        };
+        if (request.waitForSetup) {
+          await waitForWorkspaceSetup(request.workspaceId, {
+            timeoutMs: request.setupTimeoutMs,
+            signal
+          });
         }
-      })
+        throwIfAborted(signal, "creating the run");
+        return trpc.run.create.mutate({ ...request, idempotencyKey: request.idempotencyKey ?? crypto.randomUUID() }, { signal });
+      }),
+      list: (ref, listOptions) => run(async () => trpc.run.list.query({
+        workspaceId: workspaceIdOf(ref),
+        ...listOptions
+      })),
+      get: (ref) => run(async () => trpc.run.get.query(runTargetOf(ref))),
+      messages: (ref) => run(async () => {
+        const messages = await trpc.run.messages.query(runTargetOf(ref));
+        return messages.map((message) => ({ ...message, parts: message.parts ?? [] }));
+      }),
+      cancel: (ref) => run(async () => trpc.run.cancel.mutate(runTargetOf(ref))),
+      respond,
+      watch,
+      ...runHelpers({ watch, respond })
     },
     catalog: {
       agentTypes: (input) => run(async () => {
@@ -395,6 +674,18 @@ ${log}` : ""}`);
       }),
       workspaceOptions: () => run(async () => trpc.workspace.getWorkspaceCatalog.query())
     },
+    models: {
+      list: (listOptions) => run(async () => {
+        const result = await trpc.modelCredentials.listModels.query();
+        return result.models.map((model) => ({
+          id: model.modelId,
+          name: model.displayName,
+          provider: model.modelId.slice(0, model.modelId.indexOf("/")),
+          isFree: model.isFree,
+          isRecommended: model.isRecommended
+        })).filter((model) => !listOptions?.provider || model.provider === listOptions.provider);
+      })
+    },
     credentials: {
       list: () => run(async () => {
         const result = await trpc.modelCredentials.listMyCredentials.query();
@@ -411,6 +702,7 @@ ${log}` : ""}`);
         return result.providers.map((provider) => ({
           id: provider.id,
           name: provider.name,
+          logicalProviderKey: provider.logicalProviderKey,
           displayName: provider.displayName,
           authType: provider.authType,
           isRecommended: provider.isRecommended
@@ -420,7 +712,7 @@ ${log}` : ""}`);
   };
 }
 // src/device-login.ts
-function sleep(ms) {
+function sleep2(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 async function loginWithDeviceCode(serverUrl, options = {}) {
@@ -440,8 +732,8 @@ async function loginWithDeviceCode(serverUrl, options = {}) {
     intervalSeconds: codeJson.intervalSeconds,
     expiresInSeconds: codeJson.expiresInSeconds
   });
-  const deadline = Date.now() + codeJson.expiresInSeconds * 1000;
-  while (Date.now() < deadline) {
+  const deadline2 = Date.now() + codeJson.expiresInSeconds * 1000;
+  while (Date.now() < deadline2) {
     const tokenRes = await fetchImpl(new URL("/api/device/token", normalizedServerUrl), {
       method: "POST",
       headers: { "content-type": "application/json" },
@@ -455,7 +747,7 @@ async function loginWithDeviceCode(serverUrl, options = {}) {
       const errText = await tokenRes.text().catch(() => "");
       throw new Error(`Login failed: ${tokenRes.status} ${errText}`);
     }
-    await sleep(Math.max(1, codeJson.intervalSeconds) * 1000);
+    await sleep2(Math.max(1, codeJson.intervalSeconds) * 1000);
   }
   throw new Error("Device code expired; try again.");
 }
@@ -525,6 +817,7 @@ function createGittermWorkspaceClient(options = {}) {
   };
 }
 export {
+  AgentRunError,
   DEFAULT_GITTERM_SERVER_URL,
   GittermError,
   WorkspaceLifecycleError,

package/dist/runs.d.ts

@@ -0,0 +1,19 @@
+import type { AgentRun, AgentRunEvent, AgentRunReply, AgentRunResult, RunResultOptions, RunWaitOptions, RunWatchOptions } from "./types.js";
+export declare function terminal(status: AgentRun["status"]): boolean;
+export declare function aborted(signal?: AbortSignal): void;
+export declare function abortable<T>(operation: Promise<T>, signal: AbortSignal): Promise<T>;
+export declare function delay(ms: number, signal: AbortSignal): Promise<void>;
+/** Deduplication is subscriber-local, not an exactly-once delivery guarantee. */
+export declare function runEvents<T extends AgentRun>(states: AsyncIterable<T>): AsyncGenerator<AgentRunEvent<T>>;
+/** Same interaction helpers for hosted and direct runs. */
+export declare function runHelpers<Ref, T extends AgentRun>(operations: {
+    watch(ref: Ref, options?: RunWatchOptions): AsyncIterable<T>;
+    respond(ref: Ref, input: {
+        requestId: string;
+        reply: AgentRunReply;
+    }): Promise<T>;
+}): {
+    events: (ref: Ref, options?: RunWatchOptions) => AsyncIterable<AgentRunEvent<T>>;
+    wait: (ref: Ref, options?: RunWaitOptions) => Promise<T>;
+    result: (ref: Ref, options?: RunResultOptions) => Promise<AgentRunResult<T>>;
+};