@gitterm/sdk 0.1.2 → 0.1.3

package/README.md

@@ -258,7 +258,7 @@ const { workspace, runtime } = await client.workspaces.create({
 The username defaults to `x-access-token`. Inline repository credentials take precedence over
 `gitIntegrationId` and authenticate repository validation, cloning, and runtime Git operations such
 as pull and push. Without inline credentials, `gitIntegrationId` continues to use the connected
-dashboard integration. Omitting `modelCredentialIds` and `modelCredentials` likewise continues to
+dashboard integration. Omitting `modelCredentials` likewise continues to
 use dashboard-managed model credentials.
 
 GitTerm does not save inline PATs in its application database. Inline PATs must be delivered to the
@@ -294,21 +294,102 @@ const status = await client.auth.status();
 
 ```ts
 client.auth.status();                 // -> { userId, email, name, plan, authMethod }
-client.workspaces.list(options?);     // -> { workspaces, pagination }
-client.workspaces.get(workspaceId);
-client.workspaces.getRuntimeAccess(workspaceId); // read-only; never resumes compute
-client.workspaces.ensureRunning(workspaceId, options?);
-client.workspaces.pause(workspaceId);
-client.workspaces.restart(workspaceId);
-client.workspaces.terminate(workspaceId);
+client.workspaces.list(options?);     // -> { workspaces, pagination }; filter by status or metadata
+client.workspaces.get(workspace);      // workspace = id string or any object with an `id`
+client.workspaces.getRuntimeAccess(workspace); // read-only; never resumes compute
+client.workspaces.ensureRunning(workspace, options?); // resume if paused, wait until running
+client.workspaces.setupStatus(workspace);
+client.workspaces.waitForSetup(workspace, options?);
+client.workspaces.pause(workspace);    // -> { durationMinutes } of the usage session just closed
+client.workspaces.restart(workspace);
+client.workspaces.terminate(workspace); // -> { workspace, cleanupInBackground }
 client.workspaces.create({
   repo: "https://github.com/acme/product",
 });
+client.runs.create(input);
+client.runs.list(workspace, options?); // -> { runs, pagination }
+client.runs.get(run);                  // run = AgentRun, { workspaceId, runId }, or (workspaceId, runId)
+client.runs.messages(run);
+client.runs.cancel(run);
+client.runs.wait(run, options?);        // resolves when terminal or awaiting_input (push-based)
+client.runs.respond(run, { requestId, reply }); // answer a permission prompt or agent question
 client.catalog.agentTypes();
 client.catalog.cloudProviders();
 client.catalog.workspaceOptions();
 ```
 
+Every wait (`ensureRunning`, `waitForSetup`, and `runs.create` with `waitForSetup`) accepts
+`{ timeoutMs, pollIntervalMs, signal }`. `runs.wait` is push-based (server-sent events) and
+accepts `{ timeoutMs, signal, until }`. Pass an `AbortSignal` to stop waiting on shutdown; the
+promise rejects with code `ABORTED`.
+
+`pause()` returns `durationMinutes`, the length of the usage session it just closed, which is
+what billing records. `terminate()` returns `cleanupInBackground: true` when the provider
+finishes tearing down resources after the call returns.
+
+#### Tagging and lifetime
+
+`metadata` attaches caller-owned tags to a workspace so you can find it again without a
+lookup table of your own, and `autoTerminateAfterMs` caps how long it can live:
+
+```ts
+await client.workspaces.create({
+  repo: "https://github.com/acme/product",
+  metadata: { tenant: "acme", channel: "C0123" },
+  autoTerminateAfterMs: 2 * 60 * 60 * 1000, // gone in 2h even if this process crashes
+});
+
+const { workspaces } = await client.workspaces.list({
+  metadata: { tenant: "acme", channel: "C0123" },
+});
+```
+
+Metadata allows up to 20 keys of letters, digits, `_ . : -`, with values up to 500 characters,
+and `list` matches workspaces containing every given pair. `autoTerminateAfterMs` ranges from
+1 minute to 30 days; the reaper terminates the workspace once the time passes regardless of
+activity, and `workspace.autoTerminateAt` shows the deadline. Idle workspaces are still paused
+by the platform's idle policy independently of this.
+
+#### Bring your own image
+
+Pass `image` to run your own build instead of the catalog image. On the managed service the
+image must be pullable without credentials; creation fails immediately with the reason if it
+isn't, rather than leaving a workspace stuck pulling.
+
+```ts
+await client.workspaces.create({
+  repo: "https://github.com/acme/product",
+  provider: { type: "railway" },
+  image: "ghcr.io/acme/agent-runner:1.4.0",
+});
+
+// E2B takes a public template id or alias instead of a registry reference.
+await client.workspaces.create({
+  repo: "https://github.com/acme/product",
+  provider: { type: "e2b" },
+  image: "acme-python-runner",
+});
+```
+
+Supported on Railway, AWS, Daytona, exe.dev, and E2B. Vercel and Cloudflare run fixed
+runtimes and reject `image`. Floating tags such as `latest` are pinned to the digest verified
+at create time, so a restart months later runs the same image; `workspace.customImage` shows
+what was pinned.
+
+The image has to behave like the stock one, because GitTerm's entrypoint does the clone, writes
+agent files, runs setup phases, and starts the agent. Layer on the published base and keep its
+entrypoint:
+
+```dockerfile
+FROM opeoginni/gitterm-opencode-server:latest
+RUN apt-get update && apt-get install -y --no-install-recommends python3 python3-pip poppler-utils \
+  && rm -rf /var/lib/apt/lists/*
+```
+
+Rules: do not override `ENTRYPOINT` or `CMD`; keep global installs outside `/workspace`, which
+is a persisted volume; keep `opencode` and `@gitterm/cli` on `PATH`; keep port 7681. For E2B,
+build your template from the same base and publish it so any account can start it.
+
 The server defaults the agent to `opencode`, selects the user's preferred provider,
 uses that provider's default machine profile, and applies the provider's persistence policy.
 Override only the placement decisions your integration cares about:
@@ -385,12 +466,104 @@ run UI review or browser capture tools in the sandbox, upload the resulting medi
 the changelog in the checked-out repository, then terminate the workspace. Use an
 `idempotencyKey` based on the release SHA when the workflow may be retried.
 
+### Workspace lifecycle and readiness
+
+A workspace has one of four statuses:
+
+| Status       | Meaning                                                                                   |
+| ------------ | ----------------------------------------------------------------------------------------- |
+| `pending`    | Compute is being provisioned or resumed. `runtime.url` is `null`.                         |
+| `running`    | The provider reports the sandbox or container up. The agent process may still be booting. |
+| `paused`     | Stopped but resumable.                                                                    |
+| `terminated` | Gone for good.                                                                            |
+
+Whether `create()` returns `running` or `pending` depends on the provider. Sandbox providers
+(E2B, Daytona, Vercel, Ascii, exe.dev, Cloudflare) settle immediately and return `running`.
+Railway settles by webhook and returns `pending` until its deployment reports success, usually
+within a minute. Code that only ever ran against a sandbox provider will see `pending` for the
+first time when it moves to Railway.
+
+Three things have to be true before a prompt can be delivered, and the SDK handles each:
+
+1. **The workspace is `running`.** `runs.create()` waits for a `pending` workspace to
+   transition on its own, up to `startTimeoutMs` (default 120s). It does not resume a `paused`
+   workspace; call `ensureRunning()` for that, which resumes, polls until `running`, and returns
+   the runtime access.
+2. **The agent answers.** `running` is the provider's view. `runs.create()` then probes the
+   workspace URL until the agent server responds before submitting the prompt, so callers never
+   need their own health check.
+3. **Setup finished (optional).** `afterAgent` commands run in the background once the agent is
+   reachable. Pass `waitForSetup: true` to `runs.create()` to block on them, or poll with
+   `setupStatus()` / `waitForSetup()`. Status `waiting` means the agent isn't reachable yet, so
+   setup hasn't started; `running`, `succeeded`, and `failed` describe the phase itself;
+   `not_requested` means there were no `afterAgent` commands. The SDK polls setup from the
+   client so a long `npm ci` never holds one HTTP request open; that polling needs the
+   `workspace:read` scope on the token in addition to `run:write`. `waiting` cannot last
+   forever: while you poll, the server also reads the setup state files inside the workspace
+   (through the agent when the provider has no exec channel), and if nothing has progressed
+   after 15 minutes it marks the setup `failed` with a log explaining what stalled.
+
+The shortest correct sequence is therefore:
+
+```ts
+const { workspace } = await client.workspaces.create({ repo, setup: { afterAgent: ["npm ci"] } });
+const run = await client.runs.create({
+  workspaceId: workspace.id,
+  idempotencyKey: `review-${sha}`,
+  waitForSetup: true,
+  prompt: "Review the open pull request",
+});
+const done = await client.runs.wait(workspace.id, run.id);
+```
+
+For a workspace you didn't just create, start with `ensureRunning()`:
+
+```ts
+const { workspace, runtime } = await client.workspaces.ensureRunning(workspaceId);
+// runtime.url is set; workspace.status is "running"
+```
+
+Failures surface as `WorkspaceLifecycleError` with stable codes: `WORKSPACE_NOT_RUNNING` (the
+workspace is `paused`, or stopped while waiting), `WORKSPACE_TERMINATED`,
+`WORKSPACE_START_TIMEOUT` (still `pending` after the timeout, or no runtime URL),
+`WORKSPACE_NON_RECOVERABLE`, and `WORKSPACE_RESTART_FAILED`.
+
+Direct provider mode behaves differently: `direct.workspaces.create()` waits for the OpenCode
+runtime to answer before returning, so a direct workspace is ready for `runs.create()` as soon
+as `create()` resolves.
+
 ### Agent runs
 
 Runs use durable GitTerm IDs backed by the workspace's native OpenCode session. Reusing an
 idempotency key with the same input returns the original run, and terminal results remain
-available after the workspace is paused. Completion means the native session became idle;
-it does not claim that a pull request, upload, or other product outcome succeeded.
+available after the workspace is paused. `idempotencyKey` defaults to a random UUID; pass your
+own whenever a retry could otherwise submit the same prompt twice. Completion means the native
+session became idle; it does not claim that a pull request, upload, or other product outcome
+succeeded.
+
+Every run carries `createdAt`, `submittedAt` (when the prompt reached the agent), and
+`completedAt`. `runs.list(workspace, { status: "active" })` returns what is still in flight, so a
+process recovering after a restart can pick up where it left off without having persisted run
+ids itself. The server watches every active run's OpenCode session and keeps the run current;
+`get`/`list`/`messages` read that state without touching the workspace.
+
+Statuses: `pending` → `running` (or `retrying` while OpenCode backs off from the model
+provider) → `completed` | `failed` | `cancelled`. A run that stops to ask something is
+`awaiting_input` until you answer it (below).
+
+`runs.messages()` returns each turn's concatenated `text` plus an ordered `parts` array. Tool
+calls appear as `{ type: "tool", tool, status, title, input, output, error }` with output
+truncated to 4000 characters, which is usually enough to see why a run went wrong:
+
+```ts
+for (const message of await client.runs.messages(run)) {
+  for (const part of message.parts) {
+    if (part.type === "tool" && part.status === "error") {
+      console.log(part.tool, part.title, part.error);
+    }
+  }
+}
+```
 
 ```ts
 const { workspace } = await client.workspaces.create({
@@ -409,6 +582,50 @@ const completed = await client.runs.wait(workspace.id, run.id);
 const messages = await client.runs.messages(workspace.id, run.id);
 ```
 
+#### Questions and permission prompts
+
+When the agent calls OpenCode's `question` tool, or a tool needs approval under your
+`permission` config, the run becomes `awaiting_input` and `run.pendingInputs` describes what it
+is waiting for. `runs.wait()` returns at that point by default; answer with `runs.respond()` and
+wait again. This is what makes a chat bot able to relay "should I do A or B?" to a human.
+
+```ts
+let run = await client.runs.wait(workspace.id, created.id);
+while (run.status === "awaiting_input") {
+  for (const request of run.pendingInputs) {
+    if (request.kind === "permission") {
+      // request.title, e.g. "bash: rm -rf dist"; also permission / patterns / always
+      await client.runs.respond(run, {
+        requestId: request.id,
+        reply: { type: "permission", response: "once" }, // "once" | "always" | "reject"
+      });
+    } else {
+      // request.questions[i] has header, question, options[{ label, description }], multiple, custom
+      const answers = request.questions.map((question) => [question.options[0]!.label]);
+      await client.runs.respond(run, {
+        requestId: request.id,
+        reply: { type: "question", answers },
+      });
+      // or: reply: { type: "question", reject: true }
+    }
+  }
+  run = await client.runs.wait(workspace.id, created.id);
+}
+```
+
+Rejecting a permission or dismissing a question ends the turn: OpenCode records a failed tool
+call and the run finishes. Pass `{ until: "terminal" }` to `runs.wait()` to keep waiting through
+`awaiting_input` (for example when a separate process answers). A run left `awaiting_input` does
+not keep its workspace awake; if nobody answers before the workspace's idle timeout pauses it,
+the run is cancelled with `"Workspace paused while waiting for input"`. To avoid prompts entirely
+in headless runs, allow the relevant tools in `opencode.config.permission` when creating the
+workspace.
+
+`runs.wait()` uses a lightweight lifecycle stream internally; it does not mirror OpenCode's
+native message, tool, or token events. `runs.messages()` provides the persisted transcript at
+lifecycle checkpoints and completion. For live execution details, use
+`workspaces.getRuntimeAccess()` with the official OpenCode SDK.
+
 Runs are isolated by default and can execute in parallel. To preserve conversational context,
 continue a terminal run; continued runs sharing context must remain sequential:
 
@@ -423,57 +640,65 @@ const next = await client.runs.create({
 
 ### Model provider credentials
 
-Workspaces can receive model credentials two ways, and they compose:
-
-**Dashboard credentials** — list the account's credential metadata, choose one active credential
-per provider, and pass the IDs when creating a workspace. The SDK never returns credential
-secrets.
+`modelCredentials` takes one entry per provider. Each entry selects where that provider's
+credential comes from, and the three forms compose in one array:
 
 ```ts
-const credentials = await client.credentials.list();
-const selected = credentials.filter(
-  (credential) =>
-    credential.isActive && ["anthropic", "openai"].includes(credential.logicalProviderKey),
-);
-
 const { workspace } = await client.workspaces.create({
   repo: "https://github.com/acme/product",
-  modelCredentialIds: selected.map((credential) => credential.id),
+  modelCredentials: [
+    { providerName: "openai", label: "work" }, // dashboard credential, by label
+    { providerName: "anthropic" }, // that provider's dashboard default
+    { providerName: "google", apiKey: process.env.GOOGLE_API_KEY! }, // inline, this workspace only
+  ],
 });
 ```
 
-**Inline credentials** — pass API keys directly for this workspace only. They are injected into
-the provisioned agent and never stored in the dashboard. Use
-`client.credentials.listProviders()` for valid provider names; OAuth providers (e.g. GitHub
-Copilot) can only be connected through the dashboard.
+**Dashboard credentials** are addressed by `providerName` plus the `label` you gave them in the
+dashboard (labels are unique per provider). Omit `label` to use the provider's default. The SDK
+never returns credential secrets; `client.credentials.list()` returns metadata including labels
+if you need to discover them, and requires an API token with the `workspace:write` scope.
 
-```ts
-const { workspace } = await client.workspaces.create({
-  repo: "https://github.com/acme/product",
-  modelCredentials: [{ providerName: "anthropic", apiKey: process.env.ANTHROPIC_API_KEY! }],
-});
+**Inline credentials** pass an API key directly for this workspace only. They are injected into
+the provisioned agent and never stored in the dashboard. Use `client.credentials.listProviders()`
+for valid provider names; OAuth providers (e.g. GitHub Copilot) can only be connected through
+the dashboard.
 
 const run = await client.runs.create({
-  workspaceId: workspace.workspaceId,
-  model: "anthropic/claude-sonnet-4-20250514",
-  prompt: "Record before/after videos of the changes in PR #42",
+workspaceId: workspace.workspaceId,
+model: "anthropic/claude-sonnet-4-20250514",
+prompt: "Record before/after videos of the changes in PR #42",
 });
-```
+
+````
 
 Rules and errors:
 
-- Omit both fields to inject the dashboard defaults.
+- Omit `modelCredentials` to inject every dashboard default.
+- Naming any dashboard credential (an entry without `apiKey`) switches off the implicit defaults,
+  so list each provider the workspace needs. Inline-only arrays keep the defaults for the other
+  providers.
 - One credential per logical provider. An inline credential always overrides the dashboard
-  credential (default or selected) for the same provider; two credentials for the same provider
-  within one field throw `MODEL_CREDENTIAL_DUPLICATE_PROVIDER`.
-- Unknown providers or inline keys for OAuth-only providers throw `MODEL_CREDENTIAL_INVALID`;
-  missing, inactive, or unowned dashboard selections throw `MODEL_CREDENTIAL_UNAVAILABLE`.
+  credential for the same provider; two entries for the same provider throw
+  `MODEL_CREDENTIAL_DUPLICATE_PROVIDER`.
+- Unknown providers or inline keys for OAuth-only providers throw `MODEL_CREDENTIAL_INVALID`.
+  A label that doesn't exist throws `MODEL_CREDENTIAL_UNAVAILABLE` and the message lists the
+  labels that do.
 - A run that requests a credential-backed `provider/model` not available in its workspace throws
   `MODEL_CREDENTIAL_REQUIRED` before the prompt is submitted.
 
-Use `client.runs.cancel(workspaceId, runId)` to abort the current run. GitTerm keeps the
-underlying OpenCode session private. For native session control, use
-`workspaces.getRuntimeAccess()` and connect with the official OpenCode SDK.
+Use `client.runs.cancel(workspaceId, runId)` to abort the current run; a run that is
+`awaiting_input` has its pending prompt rejected first. GitTerm keeps the underlying OpenCode
+session private. For native session control, use `workspaces.getRuntimeAccess()` and connect
+with the official OpenCode SDK.
+
+### OpenCode API versions
+
+Managed workspaces continue to run `opencode-ai@latest` (`opencodeApi: "v1"`). OpenCode 2
+changes the server API; callers testing it must supply their own compatible image and create the
+workspace with `opencode: { api: "v2" }`. Runs, questions, permissions, and events behave the
+same from the SDK's point of view; the flag only tells GitTerm which protocol to speak to the
+workspace. `v2` is experimental until OpenCode 2 ships.
 
 ### Errors
 
@@ -489,13 +714,13 @@ try {
     // "Not logged in. Run: gitterm login"
   }
 }
-```
+````
 
 Workspace lifecycle failures are also exposed as `WorkspaceLifecycleError`, with stable
-`WORKSPACE_TERMINATED`, `WORKSPACE_NON_RECOVERABLE`, `WORKSPACE_START_TIMEOUT`, and
-`WORKSPACE_RESTART_FAILED` codes. General codes are
+`WORKSPACE_NOT_RUNNING`, `WORKSPACE_TERMINATED`, `WORKSPACE_NON_RECOVERABLE`,
+`WORKSPACE_START_TIMEOUT`, and `WORKSPACE_RESTART_FAILED` codes. General codes are
 `NOT_LOGGED_IN`, `UNAUTHORIZED`, `NOT_FOUND`, `FORBIDDEN`, `BAD_REQUEST`, `CONFLICT`,
-`SERVER_ERROR`, and `NETWORK`.
+`SERVER_ERROR`, `NETWORK`, and `ABORTED` (a wait was cancelled through its `signal`).
 
 The package ships self-contained declarations from `dist`; TypeScript consumers do not
 need GitTerm's API package or tRPC server types.

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { AgentType, AgentRun, AgentRunCreateInput, AgentRunMessage, AuthStatus, CloudProvider, Workspace, WorkspaceCreateInput, WorkspaceCreateResult, WorkspaceEnsureRunningResult, WorkspaceListOptions, WorkspaceListResult, WorkspaceRestartResult, WorkspaceRuntimeAccess, WorkspacePauseResult, WorkspaceTerminateResult, WorkspaceCatalog, WorkspaceSetupStatus, ModelCredential, ModelProviderInfo } from "./types.js";
+import type { AgentType, AgentRun, AgentRunCreateInput, AgentRunListOptions, AgentRunListResult, AgentRunMessage, AgentRunReply, AuthStatus, CloudProvider, RunRef, RunWaitOptions, WaitOptions, Workspace, WorkspaceCreateInput, WorkspaceCreateResult, WorkspaceEnsureRunningResult, WorkspaceListOptions, WorkspaceListResult, WorkspaceRef, WorkspaceRestartResult, WorkspaceRuntimeAccess, WorkspacePauseResult, WorkspaceTerminateResult, WorkspaceCatalog, WorkspaceSetupStatus, ModelCredential, ModelProviderInfo } from "./types.js";
 export type GittermClientOptions = {
     serverUrl?: string;
     token?: string;
@@ -12,33 +12,41 @@ export type GittermClient = {
     };
     workspaces: {
         list(input?: WorkspaceListOptions): Promise<WorkspaceListResult>;
-        get(workspaceId: string): Promise<Workspace>;
-        getRuntimeAccess(workspaceId: string): Promise<WorkspaceRuntimeAccess>;
-        ensureRunning(workspaceId: string, options?: {
-            timeoutMs?: number;
-            pollIntervalMs?: number;
-        }): Promise<WorkspaceEnsureRunningResult>;
-        pause(workspaceId: string): Promise<WorkspacePauseResult>;
-        restart(workspaceId: string): Promise<WorkspaceRestartResult>;
-        terminate(workspaceId: string): Promise<WorkspaceTerminateResult>;
+        get(workspace: WorkspaceRef): Promise<Workspace>;
+        getRuntimeAccess(workspace: WorkspaceRef): Promise<WorkspaceRuntimeAccess>;
+        /** Resume a paused workspace if needed and wait until it is running. */
+        ensureRunning(workspace: WorkspaceRef, options?: WaitOptions): Promise<WorkspaceEnsureRunningResult>;
+        pause(workspace: WorkspaceRef): Promise<WorkspacePauseResult>;
+        restart(workspace: WorkspaceRef): Promise<WorkspaceRestartResult>;
+        terminate(workspace: WorkspaceRef): Promise<WorkspaceTerminateResult>;
         create(input: WorkspaceCreateInput): Promise<WorkspaceCreateResult>;
-        setupStatus(workspaceId: string): Promise<WorkspaceSetupStatus>;
-        waitForSetup(workspaceId: string, options?: {
-            timeoutMs?: number;
-            pollIntervalMs?: number;
-        }): Promise<WorkspaceSetupStatus>;
+        setupStatus(workspace: WorkspaceRef): Promise<WorkspaceSetupStatus>;
+        waitForSetup(workspace: WorkspaceRef, options?: WaitOptions): Promise<WorkspaceSetupStatus>;
     };
     runs: {
         create(input: AgentRunCreateInput): Promise<AgentRun>;
+        list(workspace: WorkspaceRef, options?: AgentRunListOptions): Promise<AgentRunListResult>;
+        get(run: RunRef): Promise<AgentRun>;
         get(workspaceId: string, runId: string): Promise<AgentRun>;
+        messages(run: RunRef): Promise<AgentRunMessage[]>;
         messages(workspaceId: string, runId: string): Promise<AgentRunMessage[]>;
+        cancel(run: RunRef): Promise<{
+            cancelled: boolean;
+        }>;
         cancel(workspaceId: string, runId: string): Promise<{
             cancelled: boolean;
         }>;
-        wait(workspaceId: string, runId: string, options?: {
-            timeoutMs?: number;
-            pollIntervalMs?: number;
+        /** Answer the permission prompt or question a run is `awaiting_input` on. */
+        respond(run: RunRef, input: {
+            requestId: string;
+            reply: AgentRunReply;
         }): Promise<AgentRun>;
+        /**
+         * Resolve once the run needs attention: terminal, or `awaiting_input`
+         * unless `until: "terminal"`. Push-based; no polling.
+         */
+        wait(run: RunRef, options?: RunWaitOptions): Promise<AgentRun>;
+        wait(workspaceId: string, runId: string, options?: RunWaitOptions): Promise<AgentRun>;
     };
     catalog: {
         agentTypes(input?: {

package/dist/errors.d.ts

@@ -1,6 +1,7 @@
-export type GittermErrorCode = "NOT_LOGGED_IN" | "UNAUTHORIZED" | "NOT_FOUND" | "FORBIDDEN" | "BAD_REQUEST" | "CONFLICT" | "SERVER_ERROR" | "NETWORK" | CredentialErrorCode | WorkspaceLifecycleErrorCode;
+export type GittermErrorCode = "NOT_LOGGED_IN" | "UNAUTHORIZED" | "NOT_FOUND" | "FORBIDDEN" | "BAD_REQUEST" | "CONFLICT" | "SERVER_ERROR" | "NETWORK" | "ABORTED" | CredentialErrorCode | WorkspaceLifecycleErrorCode;
 export type CredentialErrorCode = "MODEL_CREDENTIAL_UNAVAILABLE" | "MODEL_CREDENTIAL_DUPLICATE_PROVIDER" | "MODEL_CREDENTIAL_INVALID" | "MODEL_CREDENTIAL_REQUIRED";
-export type WorkspaceLifecycleErrorCode = "WORKSPACE_TERMINATED" | "WORKSPACE_NON_RECOVERABLE" | "WORKSPACE_START_TIMEOUT" | "WORKSPACE_RESTART_FAILED";
+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[];
 export declare class GittermError extends Error {
     readonly code: GittermErrorCode;
     readonly cause?: unknown;

package/dist/index.d.ts

@@ -6,4 +6,4 @@ export type { DeviceCodeInfo, LoginWithDeviceCodeOptions } from "./device-login.
 export { 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, AgentRunMessage, AgentRunStatus, 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 { 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";

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;
@@ -129,6 +144,37 @@ 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(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 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 +203,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),
@@ -218,37 +268,75 @@ async function runWithServer(serverUrl, operation) {
       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
-        });
+      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 });
   }
 }
+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 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 })
+        })
       })
     ]
   });
@@ -279,9 +367,11 @@ function createGittermClient(options = {}) {
   const waitForWorkspaceSetup = async (workspaceId, waitOptions) => {
     const timeoutMs = waitOptions?.timeoutMs ?? 10 * 60000;
     const pollIntervalMs = waitOptions?.pollIntervalMs ?? 2000;
+    const signal = waitOptions?.signal;
     const deadline = 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") {
@@ -294,7 +384,7 @@ ${log}` : ""}`);
         throw new GittermError("NETWORK", `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 +406,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,43 +440,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))
+      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, ...request } = input;
+        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: (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);
+        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);
       })
     },
     catalog: {
@@ -420,7 +534,7 @@ ${log}` : ""}`);
   };
 }
 // src/device-login.ts
-function sleep(ms) {
+function sleep2(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 async function loginWithDeviceCode(serverUrl, options = {}) {
@@ -455,7 +569,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.");
 }

package/dist/types.d.ts

@@ -6,6 +6,13 @@ export type AuthStatus = {
     plan: string;
     authMethod: "session" | "apiToken";
 };
+/**
+ * `pending` — compute is being provisioned or resumed; `runtime.url` is null.
+ * `running` — the provider reports the sandbox/container up. The agent may
+ * still be booting; `runs.create()` waits for it to answer.
+ * `paused` — stopped but resumable with `workspaces.ensureRunning()`.
+ * `terminated` — gone for good.
+ */
 export type WorkspaceStatus = "pending" | "running" | "paused" | "terminated";
 export type WorkspaceHostingType = "cloud" | "local";
 export type Workspace = {
@@ -33,12 +40,40 @@ export type Workspace = {
         name: string;
         imageId: string;
     } | null;
+    /** Caller-owned tags supplied at create time. */
+    metadata: Record<string, string>;
+    /** OpenCode HTTP API generation the workspace's agent server speaks. */
+    opencodeApi: OpencodeApi;
+    /** When set, the workspace is terminated at this time regardless of activity. */
+    autoTerminateAt: string | null;
+    /** The caller-supplied image or E2B template this workspace runs, if any. */
+    customImage: string | null;
     startedAt: string | null;
     pausedAt: string | null;
     terminatedAt: string | null;
     lastActiveAt: string | null;
     updatedAt: string | null;
 };
+/** A workspace id, or any object carrying one (e.g. a `Workspace`). */
+export type WorkspaceRef = string | {
+    id: string;
+};
+/** A run id pair, or any object carrying one (e.g. an `AgentRun`). */
+export type RunRef = {
+    workspaceId: string;
+    id: string;
+} | {
+    workspaceId: string;
+    runId: string;
+};
+/** `v1` = OpenCode 1.x (`/event`, `/session/*`); `v2` = OpenCode 2 (`/api/*`), experimental until 2.0 ships. */
+export type OpencodeApi = "v1" | "v2";
+export type WaitOptions = {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    /** Abort the wait early; the promise rejects with code `ABORTED`. */
+    signal?: AbortSignal;
+};
 export type WorkspaceRuntimeAccess = {
     workspaceId: string;
     status: WorkspaceStatus;
@@ -62,6 +97,8 @@ export type WorkspaceListOptions = {
     limit?: number;
     offset?: number;
     status?: "all" | "active" | "terminated";
+    /** Only workspaces whose metadata contains every given key/value. */
+    metadata?: Record<string, string>;
 };
 export type WorkspaceListResult = {
     workspaces: Workspace[];
@@ -156,6 +193,27 @@ export type AgentKey = BuiltInAgentKey | (string & {});
 export type WorkspaceCreateInput = {
     idempotencyKey?: string;
     name?: string;
+    /**
+     * Caller-owned tags (e.g. tenant or channel ids). Up to 20 keys of letters,
+     * digits, `_ . : -`; values up to 500 chars. Returned on the workspace and
+     * filterable with `workspaces.list({ metadata })`.
+     */
+    metadata?: Record<string, string>;
+    /**
+     * Terminate automatically this long after creation, whatever its activity.
+     * Between 1 minute and 30 days. Use it as a cost guardrail for ephemeral
+     * workspaces in case the caller crashes before `terminate()`.
+     */
+    autoTerminateAfterMs?: number;
+    /**
+     * Run your own image instead of the catalog image. Registry-backed providers
+     * (railway, aws, daytona, exedev) take an OCI reference such as
+     * `ghcr.io/acme/agent-runner:1.4.0`; E2B takes a public template id or
+     * alias. The managed service only runs images that can be pulled without
+     * credentials, and pins floating tags to a digest at create time. Build on
+     * `opeoginni/gitterm-opencode-server` and keep its entrypoint.
+     */
+    image?: string;
     repo: string;
     branch?: string;
     /** Commit SHA to pin the checkout to after cloning `branch`/`checkoutRef`. */
@@ -176,13 +234,10 @@ export type WorkspaceCreateInput = {
     /** Defaults from the selected provider. */
     persistent?: boolean;
     workspaceProfile?: "standard" | "ssh-enabled";
-    /** Credential IDs from client.credentials.list(). Omit to inject dashboard defaults. */
-    modelCredentialIds?: string[];
     /**
-     * Inline API keys for this workspace only — injected at provision time and
-     * never stored in the dashboard. An inline key overrides any dashboard
-     * credential for the same provider. OAuth providers can't be supplied
-     * inline; connect those in the dashboard.
+     * One entry per provider. Omit entirely to inject the dashboard defaults.
+     * Naming any dashboard credential (an entry without `apiKey`) turns off the
+     * implicit defaults, so list every provider the workspace needs.
      */
     modelCredentials?: WorkspaceModelCredentialInput[];
     /** Ephemeral environment variables injected into this workspace only. */
@@ -218,6 +273,11 @@ export type WorkspaceCreateInput = {
          * webfetch: "allow" } } disables tool approval prompts in headless runs.
          */
         config?: Record<string, unknown>;
+        /**
+         * OpenCode API generation served by the image. Defaults to `v1`. Use `v2`
+         * with an image built on OpenCode 2 (`@opencode-ai/cli`); experimental.
+         */
+        api?: OpencodeApi;
     };
 };
 export type WorkspaceRestartResult = {
@@ -234,7 +294,54 @@ export type WorkspaceEnsureRunningResult = {
     workspace: Workspace;
     runtime: WorkspaceRuntimeAccess;
 };
-export type AgentRunStatus = "pending" | "running" | "retrying" | "completed" | "failed" | "cancelled";
+export type AgentRunStatus = "pending" | "running" | "retrying"
+/** Blocked on a permission prompt or agent question; answer with `runs.respond()`. */
+ | "awaiting_input" | "completed" | "failed" | "cancelled";
+/** A prompt the agent is blocked on. `permission` = OpenCode tool approval; `question` = the agent's `question` tool. */
+export type AgentRunInputRequest = {
+    id: string;
+    kind: "permission";
+    createdAt: string;
+    toolCallId: string | null;
+    /** Permission action, e.g. "bash" or "edit". */
+    permission: string;
+    /** What the action applies to, e.g. the shell command or file paths. */
+    patterns: string[];
+    /** Patterns OpenCode remembers when answered with "always". */
+    always: string[];
+    title: string;
+} | {
+    id: string;
+    kind: "question";
+    createdAt: string;
+    toolCallId: string | null;
+    questions: Array<{
+        key: string;
+        header: string;
+        question: string;
+        options: Array<{
+            label: string;
+            description: string;
+            value?: string;
+        }>;
+        /** More than one option may be selected. */
+        multiple: boolean;
+        /** A free-text answer outside `options` is accepted. */
+        custom: boolean;
+    }>;
+};
+export type AgentRunReply = {
+    type: "permission";
+    response: "once" | "always" | "reject";
+}
+/** One entry per question, each the selected option labels (or a custom answer when allowed). */
+ | {
+    type: "question";
+    answers: string[][];
+} | {
+    type: "question";
+    reject: true;
+};
 export type AgentRun = {
     id: string;
     workspaceId: string;
@@ -242,17 +349,43 @@ export type AgentRun = {
     status: AgentRunStatus;
     error: string | null;
     finalText: string | null;
+    /** Non-empty exactly while `status` is `awaiting_input`. */
+    pendingInputs: AgentRunInputRequest[];
     context: {
         type: "isolated";
     } | {
         type: "continued";
         runId: string;
     };
+    createdAt: string;
+    /** When the prompt reached the agent; null while `pending`. */
+    submittedAt: string | null;
+    completedAt: string | null;
+};
+export type AgentRunListOptions = {
+    /** `active` = pending/running/retrying/awaiting_input; `terminal` = completed/failed/cancelled. */
+    status?: "all" | "active" | "terminal";
+    /** 1–50, default 20. */
+    limit?: number;
+    offset?: number;
+};
+export type AgentRunListResult = {
+    runs: AgentRun[];
+    pagination: {
+        total: number;
+        limit: number;
+        offset: number;
+        hasMore: boolean;
+    };
 };
 export type AgentRunCreateInput = {
     workspaceId: string;
-    /** Stable key used to return the same run when a request is retried. */
-    idempotencyKey: string;
+    /**
+     * Stable key used to return the same run when a request is retried.
+     * Defaults to a random UUID, which gives no retry protection; pass your own
+     * for anything a retry could duplicate.
+     */
+    idempotencyKey?: string;
     prompt: string;
     title?: string;
     agent?: string;
@@ -265,20 +398,67 @@ export type AgentRunCreateInput = {
         type: "continue";
         runId: string;
     };
-    /** Wait for workspace setup commands before submitting the prompt. */
+    /**
+     * Wait for the `afterAgent` setup phase to succeed before submitting the
+     * prompt. Fails the call with the setup log if that phase failed.
+     */
     waitForSetup?: boolean;
     /** How long to wait for setup, in ms. Server maximum is 600000 (10 minutes). */
     setupTimeoutMs?: number;
+    /**
+     * How long to wait for a `pending` workspace to become `running`, in ms.
+     * Defaults to 120000; server maximum is 240000. Paused workspaces are not
+     * resumed — call `workspaces.ensureRunning()` first.
+     */
+    startTimeoutMs?: number;
+    /** Abort while waiting for setup or start; rejects with code `ABORTED`. */
+    signal?: AbortSignal;
+};
+export type AgentRunMessagePart = {
+    type: "text";
+    text: string;
+} | {
+    type: "tool";
+    callId: string;
+    tool: string;
+    status: "pending" | "running" | "completed" | "error";
+    title: string | null;
+    input: Record<string, unknown>;
+    /** Tool output when completed, truncated to 4000 characters. */
+    output: string | null;
+    error: string | null;
+    startedAt: string | null;
+    completedAt: string | null;
+};
+export type RunWaitOptions = {
+    /** Default 30 minutes. */
+    timeoutMs?: number;
+    /** Abort the wait early; the promise rejects with code `ABORTED`. */
+    signal?: AbortSignal;
+    /**
+     * `input-or-terminal` (default) also returns when the run is `awaiting_input`
+     * so the caller can answer with `runs.respond()`; `terminal` keeps waiting.
+     */
+    until?: "input-or-terminal" | "terminal";
 };
 export type AgentRunMessage = {
     id: string;
     role: "user" | "assistant";
     createdAt: string;
     completedAt: string | null;
+    /** Concatenated text parts. */
     text: string;
     error: string | null;
+    /** Ordered text and tool-call parts, for seeing what the agent actually did. */
+    parts: AgentRunMessagePart[];
 };
 export type WorkspaceSetupStatus = {
+    /**
+     * `not_requested` — no `afterAgent` commands. `waiting` — the agent isn't
+     * reachable yet, so setup hasn't started. `running`, `succeeded`, `failed`
+     * describe the `afterAgent` phase itself. A setup stuck in `waiting` for
+     * 15 minutes is marked `failed` with the reason in `log`.
+     */
     status: "not_requested" | "waiting" | "running" | "succeeded" | "failed";
     exitCode: number | null;
     startedAt: string | null;
@@ -298,13 +478,26 @@ export type ModelProviderInfo = {
     isRecommended: boolean;
 };
 /**
- * An API key passed directly to workspaces.create(). `providerName` must be an
- * API-key provider from credentials.listProviders(), e.g. "anthropic" or
- * "openai"; unknown or OAuth-only providers throw MODEL_CREDENTIAL_INVALID.
+ * Selects the credential for one provider on workspaces.create().
+ * `providerName` comes from credentials.listProviders(), e.g. "anthropic" or
+ * "openai"; unknown providers throw MODEL_CREDENTIAL_INVALID.
+ *
+ * - `{ providerName, apiKey }` — inline key for this workspace only, never
+ *   stored. Overrides any dashboard credential for the same provider.
+ *   OAuth-only providers throw MODEL_CREDENTIAL_INVALID.
+ * - `{ providerName, label }` — the dashboard credential with that label.
+ *   Unknown labels throw MODEL_CREDENTIAL_UNAVAILABLE listing the labels
+ *   that exist.
+ * - `{ providerName }` — that provider's dashboard default credential.
  */
 export type WorkspaceModelCredentialInput = {
     providerName: string;
     apiKey: string;
+    label?: never;
+} | {
+    providerName: string;
+    label?: string;
+    apiKey?: never;
 };
 /** Safe dashboard credential metadata. Secret material is never returned by the SDK. */
 export type ModelCredential = {
@@ -314,7 +507,8 @@ export type ModelCredential = {
     providerDisplayName: string;
     logicalProviderKey: string;
     authType: string;
-    label: string | null;
+    /** Unique per provider; use it in `modelCredentials: [{ providerName, label }]`. */
+    label: string;
     keyHash: string;
     isActive: boolean;
     isDefault: boolean;

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "@gitterm/sdk",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "files": [
     "dist"
   ],
   "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -23,7 +25,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "rm -rf dist && bun build src/index.ts src/direct/index.ts --outdir dist --target node --format esm --external @trpc/client --external @opencode-ai/sdk --external @opencode-ai/sdk/v2 --external e2b --external @asciidev/box-sdk --external @daytonaio/sdk --external @vercel/sandbox && tsc -p tsconfig.build.json",
+    "build": "rm -rf dist && bun build src/index.ts src/direct/index.ts --outdir dist --target node --format esm --external @trpc/client --external eventsource --external @opencode-ai/sdk --external @opencode-ai/sdk/v2 --external e2b --external @asciidev/box-sdk --external @daytonaio/sdk --external @vercel/sandbox && tsc -p tsconfig.build.json",
     "prepublishOnly": "bun run check-types && bun run build",
     "check-types": "tsc --noEmit"
   },
@@ -33,7 +35,8 @@
     "@opencode-ai/sdk": "^1.18.25",
     "@trpc/client": "^11.8.1",
     "@vercel/sandbox": "^3.2.1",
-    "e2b": "^2.46.1"
+    "e2b": "^2.46.1",
+    "eventsource": "^5.1.1"
   },
   "devDependencies": {
     "@gitterm/api": "workspace:*",
@@ -42,6 +45,6 @@
     "typescript": "^5.8.2"
   },
   "engines": {
-    "node": ">=20.18.1"
+    "node": ">=22.12.0"
   }
 }