@gitterm/sdk 0.1.3 → 0.2.1

package/dist/direct/runs.d.ts

@@ -0,0 +1,19 @@
+import { GittermError } from "../errors.js";
+import type { AgentRunReply, RunWatchOptions } from "../types.js";
+import type { DirectRun, DirectRunMessage, DirectWorkspace } from "./types.js";
+export declare function directError(error: unknown): GittermError;
+export declare function directRunOperations(assertWorkspace: (workspace: DirectWorkspace) => void, fetchImpl?: typeof fetch): {
+    messages(run: DirectRun): Promise<DirectRunMessage[]>;
+    cancel(run: DirectRun): Promise<{
+        cancelled: boolean;
+    }>;
+    events: (ref: DirectRun, options?: RunWatchOptions) => AsyncIterable<import("../types.js").AgentRunEvent<DirectRun>>;
+    wait: (ref: DirectRun, options?: import("../types.js").RunWaitOptions) => Promise<DirectRun>;
+    result: (ref: DirectRun, options?: import("../types.js").RunResultOptions) => Promise<import("../types.js").AgentRunResult<DirectRun>>;
+    get: (run: DirectRun) => Promise<DirectRun>;
+    watch: (run: DirectRun, options?: RunWatchOptions) => AsyncGenerator<DirectRun>;
+    respond: (run: DirectRun, input: {
+        requestId: string;
+        reply: AgentRunReply;
+    }) => Promise<DirectRun>;
+};

package/dist/direct/types.d.ts

@@ -1,3 +1,4 @@
+import type { AgentRun, AgentRunMessage, OpencodeApi, RunWaitOptions } from "../types.js";
 export type DirectWorkspaceLifecycle = "ephemeral" | "persistent";
 export type DirectWorkspaceStatus = "pending" | "running" | "paused" | "failed" | "terminated" | "unknown";
 export type DirectProviderCapabilities = {
@@ -10,13 +11,13 @@ export type DirectProviderCapabilities = {
 };
 export type DirectApiModelCredential = {
     providerName: string;
-    type?: "api";
+    source: "apiKey";
     apiKey: string;
     metadata?: Record<string, string>;
 };
 export type DirectOAuthModelCredential = {
     providerName: string;
-    type: "oauth";
+    source: "oauth";
     refreshToken: string;
     /** May be omitted when OpenCode should refresh immediately. */
     accessToken?: string;
@@ -131,7 +132,11 @@ export type DirectWorkspaceCreateInput = {
     };
     lifecycle?: DirectWorkspaceLifecycle;
     environmentVariables?: Record<string, string>;
-    modelCredentials?: DirectModelCredential[];
+    models?: {
+        default?: string;
+        inherit?: "none";
+        providers?: Record<string, Omit<DirectApiModelCredential, "providerName"> | Omit<DirectOAuthModelCredential, "providerName">>;
+    };
     setup?: DirectWorkspaceSetup;
     secretFiles?: DirectSecretFile[];
     /** Provider-specific attachment settings. */
@@ -141,6 +146,8 @@ export type DirectWorkspaceCreateInput = {
     /** Trusted integration context appended to the generated global AGENTS.md. */
     additionalAgentInstructions?: string;
     opencode?: {
+        /** Defaults to v1. v2 requires a compatible provider image/template. */
+        api?: OpencodeApi;
         config?: Record<string, unknown>;
         plugins?: string[];
         skills?: Array<{
@@ -162,6 +169,7 @@ export type DirectWorkspace = {
     status: DirectWorkspaceStatus;
     lifecycle: DirectWorkspaceLifecycle;
     runtime: DirectWorkspaceRuntime;
+    opencodeApi: OpencodeApi;
     setup: "not_requested" | "before_agent_complete" | "after_agent";
     createdAt: string;
 };
@@ -293,27 +301,21 @@ export type DirectRunCreateInput = {
     title?: string;
     agent?: string;
     model?: string;
-    /** Reuse this native OpenCode session for conversational context. */
-    sessionId?: string;
+    context?: {
+        type: "isolated";
+    } | {
+        type: "continue";
+        run: DirectRun;
+    };
+    waitForSetup?: boolean;
+    setupTimeoutMs?: number;
+    signal?: AbortSignal;
 };
-export type DirectRun = {
-    id: string;
-    workspaceId: string;
+/** Contains runtime credentials. Encrypt when persisting; do not send to an untrusted UI. */
+export type DirectRun = AgentRun & {
+    workspace: DirectWorkspace;
     sessionId: string;
     messageId: string;
-    title: string;
-    status: "running" | "retrying" | "completed" | "failed" | "cancelled";
-    error: string | null;
-    finalText: string | null;
-    submittedAt: string;
-};
-export type DirectRunMessage = {
-    id: string;
-    role: "user" | "assistant";
-    text: string;
-    error: string | null;
-};
-export type DirectRunWaitOptions = {
-    timeoutMs?: number;
-    pollIntervalMs?: number;
 };
+export type DirectRunMessage = AgentRunMessage;
+export type DirectRunWaitOptions = RunWaitOptions;

package/dist/errors.d.ts

@@ -1,4 +1,5 @@
-export type GittermErrorCode = "NOT_LOGGED_IN" | "UNAUTHORIZED" | "NOT_FOUND" | "FORBIDDEN" | "BAD_REQUEST" | "CONFLICT" | "SERVER_ERROR" | "NETWORK" | "ABORTED" | CredentialErrorCode | WorkspaceLifecycleErrorCode;
+import type { AgentRun } from "./types.js";
+export type GittermErrorCode = "NOT_LOGGED_IN" | "UNAUTHORIZED" | "NOT_FOUND" | "FORBIDDEN" | "BAD_REQUEST" | "CONFLICT" | "SERVER_ERROR" | "NETWORK" | "ABORTED" | "TIMEOUT" | "INPUT_NOT_PENDING" | "INPUT_REQUIRED" | "RUN_FAILED" | "RUN_CANCELLED" | CredentialErrorCode | WorkspaceLifecycleErrorCode;
 export type CredentialErrorCode = "MODEL_CREDENTIAL_UNAVAILABLE" | "MODEL_CREDENTIAL_DUPLICATE_PROVIDER" | "MODEL_CREDENTIAL_INVALID" | "MODEL_CREDENTIAL_REQUIRED";
 export type WorkspaceLifecycleErrorCode = "WORKSPACE_NOT_RUNNING" | "WORKSPACE_TERMINATED" | "WORKSPACE_NON_RECOVERABLE" | "WORKSPACE_START_TIMEOUT" | "WORKSPACE_RESTART_FAILED";
 export declare const WORKSPACE_LIFECYCLE_ERROR_CODES: readonly WorkspaceLifecycleErrorCode[];
@@ -15,3 +16,8 @@ export declare class WorkspaceLifecycleError extends GittermError {
         cause?: unknown;
     });
 }
+/** result() could not produce a successful result. The run remains inspectable. */
+export declare class AgentRunError<T extends AgentRun = AgentRun> extends GittermError {
+    readonly run: T;
+    constructor(run: T, code: "INPUT_REQUIRED" | "RUN_FAILED" | "RUN_CANCELLED");
+}

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { DEFAULT_GITTERM_SERVER_URL, getConfigPath, loadConfig, loadConfigSync,
 export type { CliConfig } from "./config.js";
 export { loginWithDeviceCode } from "./device-login.js";
 export type { DeviceCodeInfo, LoginWithDeviceCodeOptions } from "./device-login.js";
-export { GittermError, WorkspaceLifecycleError } from "./errors.js";
+export { AgentRunError, GittermError, WorkspaceLifecycleError } from "./errors.js";
 export { createGittermWorkspaceClient, getWorkspaceEnvironment, type GittermWorkspaceClient, type WorkspaceClientOptions, type WorkspaceEnvironment, type WorkspacePort, type WorkspaceSelf, } from "./workspace-client.js";
 export type { CredentialErrorCode, GittermErrorCode, WorkspaceLifecycleErrorCode, } from "./errors.js";
-export type { AgentRun, AgentRunCreateInput, AgentRunInputRequest, AgentRunMessage, AgentRunMessagePart, AgentRunReply, AgentRunStatus, RunWaitOptions, OpencodeApi, AgentType, AgentKey, AuthStatus, BuiltInAgentKey, CloudProvider, ProviderKey, Workspace, WorkspaceCreateInput, WorkspaceCreateResult, WorkspaceCatalog, WorkspaceEnsureRunningResult, WorkspaceHostingType, WorkspaceListOptions, WorkspaceListResult, WorkspaceRestartResult, WorkspaceRuntimeAccess, WorkspaceStatus, WorkspaceSetupStatus, ModelCredential, ModelProviderInfo, WorkspaceModelCredentialInput, WorkspacePauseResult, WorkspaceTerminateResult, WorkspaceProviderSelection, } from "./types.js";
+export type { AgentPermissionRequest, AgentQuestion, AgentQuestionOption, AgentQuestionRequest, AgentRun, AgentRunCreateInput, AgentRunInputRequest, AgentRunMessage, AgentRunMessagePart, AgentRunReply, AgentRunStatus, AgentRunEvent, AgentRunResult, AgentRunReplyPermission, AgentRunReplyQuestion, RunResultOptions, RunRef, RunWaitOptions, RunWatchOptions, OpencodeApi, AgentType, AgentKey, AuthStatus, BuiltInAgentKey, CloudProvider, ProviderKey, Workspace, WorkspaceCreateInput, WorkspaceCreateResult, WorkspaceCatalog, WorkspaceEnsureRunningResult, WorkspaceHostingType, WorkspaceListOptions, WorkspaceListResult, WorkspaceRestartResult, WorkspaceRuntimeAccess, WorkspaceStatus, WorkspaceSetupStatus, ModelCredential, ModelProviderInfo, ModelInfo, ModelCredentialSource, WorkspaceModelsInput, WorkspaceModelAccess, WorkspacePauseResult, WorkspaceTerminateResult, WorkspaceProviderSelection, } from "./types.js";

package/dist/index.js

@@ -84,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) {
@@ -114,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;
@@ -147,16 +302,8 @@ function normalizeBaseCommit(value) {
 function workspaceIdOf(ref) {
   return typeof ref === "string" ? ref : ref.id;
 }
-function runTargetOf(refOrWorkspaceId, runId) {
-  if (typeof refOrWorkspaceId === "string") {
-    if (!runId)
-      throw new GittermError("BAD_REQUEST", "runId is required");
-    return { workspaceId: refOrWorkspaceId, runId };
-  }
-  return {
-    workspaceId: refOrWorkspaceId.workspaceId,
-    runId: "runId" in refOrWorkspaceId ? refOrWorkspaceId.runId : refOrWorkspaceId.id
-  };
+function runTargetOf(ref) {
+  return { workspaceId: ref.workspaceId, runId: ref.id };
 }
 function throwIfAborted(signal, what) {
   if (signal?.aborted)
@@ -243,6 +390,8 @@ function mapTrpcCode(code) {
       return "BAD_REQUEST";
     case "CONFLICT":
       return "CONFLICT";
+    case "TIMEOUT":
+      return "TIMEOUT";
     default:
       return "SERVER_ERROR";
   }
@@ -251,71 +400,86 @@ 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 });
-      const lifecycleCode = WORKSPACE_LIFECYCLE_ERROR_CODES.find((candidate) => error.message.includes(candidate));
-      if (lifecycleCode) {
-        throw new WorkspaceLifecycleError(lifecycleCode, 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 new GittermError("NETWORK", error instanceof Error ? error.message : "Network request failed", { cause: error });
+    throw toGittermError(serverUrl, error);
   }
 }
-function settlesWait(status, until) {
-  if (status === "completed" || status === "failed" || status === "cancelled")
-    return true;
-  return status === "awaiting_input" && until !== "terminal";
-}
-function waitForRun(trpc, target, options) {
-  const timeoutMs = options?.timeoutMs ?? 30 * 60000;
-  const what = `waiting for run ${target.runId}`;
-  return new Promise((resolve, reject) => {
-    throwIfAborted(options?.signal, what);
-    let last;
-    let subscription;
-    const finish = (settle) => {
-      clearTimeout(timer);
-      options?.signal?.removeEventListener("abort", onAbort);
-      settle();
-      subscription?.unsubscribe();
-    };
-    const onAbort = () => finish(() => reject(new GittermError("ABORTED", `Aborted while ${what}`)));
-    const timer = setTimeout(() => finish(() => reject(new GittermError("NETWORK", `Timed out ${what}`))), timeoutMs);
-    options?.signal?.addEventListener("abort", onAbort, { once: true });
-    subscription = trpc.run.lifecycle.subscribe(target, {
-      onData: (event) => {
-        last = event.run;
-        if (settlesWait(last.status, options?.until)) {
-          const run = last;
-          finish(() => resolve(run));
-        }
-      },
-      onError: (error) => finish(() => reject(error)),
-      onComplete: () => finish(() => {
-        if (last && settlesWait(last.status, options?.until))
-          resolve(last);
-        else {
-          reject(new GittermError("NETWORK", `Run ${target.runId} event stream ended unexpectedly`));
-        }
-      })
-    });
+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;
+    }
+  } finally {
+    options?.signal?.removeEventListener("abort", onAbort);
+    subscription.unsubscribe();
+  }
 }
 function createGittermClient(options = {}) {
   const credentials = resolveCredentials(options);
@@ -341,6 +505,8 @@ function createGittermClient(options = {}) {
     ]
   });
   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)
@@ -368,7 +534,7 @@ function createGittermClient(options = {}) {
     const timeoutMs = waitOptions?.timeoutMs ?? 10 * 60000;
     const pollIntervalMs = waitOptions?.pollIntervalMs ?? 2000;
     const signal = waitOptions?.signal;
-    const deadline = Date.now() + timeoutMs;
+    const deadline2 = Date.now() + timeoutMs;
     while (true) {
       throwIfAborted(signal, "waiting for workspace setup");
       const result = await trpc.workspace.getSetupStatus.query({ workspaceId }, { signal });
@@ -379,9 +545,9 @@ 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 sleep(pollIntervalMs, signal, "waiting for workspace setup");
@@ -462,12 +628,18 @@ ${log}` : ""}`);
         };
       }),
       create: createWorkspace,
+      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 () => {
-        const { signal, ...request } = input;
+        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,
@@ -481,22 +653,15 @@ ${log}` : ""}`);
         workspaceId: workspaceIdOf(ref),
         ...listOptions
       })),
-      get: (refOrWorkspaceId, runId) => run(async () => {
-        const target = runTargetOf(refOrWorkspaceId, runId);
-        return trpc.run.get.query(target);
-      }),
-      messages: (refOrWorkspaceId, runId) => run(async () => {
-        const target = runTargetOf(refOrWorkspaceId, runId);
-        const messages = await trpc.run.messages.query(target);
+      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: (refOrWorkspaceId, runId) => run(async () => trpc.run.cancel.mutate(runTargetOf(refOrWorkspaceId, runId))),
-      respond: (ref, input) => run(async () => trpc.run.respond.mutate({ ...runTargetOf(ref), ...input })),
-      wait: (refOrWorkspaceId, runIdOrOptions, maybeOptions) => run(async () => {
-        const target = typeof refOrWorkspaceId === "string" ? runTargetOf(refOrWorkspaceId, runIdOrOptions) : runTargetOf(refOrWorkspaceId);
-        const waitOptions = typeof refOrWorkspaceId === "string" ? maybeOptions : runIdOrOptions;
-        return waitForRun(trpc, target, waitOptions);
-      })
+      cancel: (ref) => run(async () => trpc.run.cancel.mutate(runTargetOf(ref))),
+      respond,
+      watch,
+      ...runHelpers({ watch, respond })
     },
     catalog: {
       agentTypes: (input) => run(async () => {
@@ -509,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();
@@ -525,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
@@ -554,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" },
@@ -639,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>>;
+};