@gitterm/sdk 0.1.2 → 0.2.0

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,37 @@ 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;
+};
+/** An `AgentRun`, or any object carrying its `workspaceId` and `id`. */
+export type RunRef = {
+    workspaceId: string;
+    id: 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 +94,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 +190,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,15 +231,8 @@ 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.
-     */
-    modelCredentials?: WorkspaceModelCredentialInput[];
+    /** Omit to use dashboard defaults. An explicit block inherits nothing unless requested. */
+    models?: WorkspaceModelsInput;
     /** Ephemeral environment variables injected into this workspace only. */
     environmentVariables?: Record<string, string>;
     /**
@@ -218,6 +266,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 +287,64 @@ 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";
+/** OpenCode asked to run a tool your `permission` config does not pre-approve. */
+export type AgentPermissionRequest = {
+    id: string;
+    kind: "permission";
+    createdAt: string | null;
+    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;
+};
+/** One choice to show the user. Answer with the `label`. */
+export type AgentQuestionOption = {
+    label: string;
+    description: string;
+};
+export type AgentQuestion = {
+    /** Identifies this question in `AgentRunReply.answers`. Unique within a request. */
+    key: string;
+    header: string;
+    question: string;
+    options: AgentQuestionOption[];
+    /** More than one option may be selected. */
+    multiple: boolean;
+    /** A free-text answer outside `options` is accepted. */
+    custom: boolean;
+};
+/** The agent called OpenCode's `question` tool. Answer every question in one reply. */
+export type AgentQuestionRequest = {
+    id: string;
+    kind: "question";
+    createdAt: string | null;
+    toolCallId: string | null;
+    questions: AgentQuestion[];
+};
+/** A prompt the agent is blocked on. */
+export type AgentRunInputRequest = AgentPermissionRequest | AgentQuestionRequest;
+export type AgentRunReply = {
+    type: "permission";
+    response: "once" | "always" | "reject";
+}
+/**
+ * Keyed by `AgentQuestion.key`, each the selected option labels (or a single
+ * custom answer when the question allows one). Every question needs a key.
+ */
+ | {
+    type: "question";
+    answers: Record<string, string[]>;
+} | {
+    type: "question";
+    reject: true;
+};
 export type AgentRun = {
     id: string;
     workspaceId: string;
@@ -242,17 +352,47 @@ export type AgentRun = {
     status: AgentRunStatus;
     error: string | null;
     finalText: string | null;
+    /**
+     * Non-empty exactly while `status` is `awaiting_input`. Usually one request;
+     * several when the agent issued parallel tool calls that each need approval.
+     * Answer each with `runs.respond()`; the run resumes once none remain.
+     */
+    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;
+    workspace: WorkspaceRef;
+    /**
+     * 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;
@@ -263,22 +403,105 @@ export type AgentRunCreateInput = {
         type: "isolated";
     } | {
         type: "continue";
-        runId: string;
+        run: RunRef;
     };
-    /** 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 RunWatchOptions = {
+    /** Stop the stream early; the iterator throws with code `ABORTED`. */
+    signal?: AbortSignal;
+};
+export type RunWaitOptions = RunWatchOptions & {
+    /** Default 30 minutes. When it elapses the promise rejects with code `TIMEOUT`. */
+    timeoutMs?: number;
+    /**
+     * `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 AgentRunResult<T extends AgentRun = AgentRun> = T & {
+    status: "completed";
+};
+export type RunResultOptions = RunWatchOptions & {
+    /** Total deadline, including time spent in human-input handlers. Default 30 minutes. */
+    timeoutMs?: number;
+    onPermission?: (request: AgentPermissionRequest, options: {
+        signal: AbortSignal;
+    }) => AgentRunReplyPermission | Promise<AgentRunReplyPermission>;
+    onQuestion?: (request: AgentQuestionRequest, options: {
+        signal: AbortSignal;
+    }) => AgentRunReplyQuestion | Promise<AgentRunReplyQuestion>;
+};
+export type AgentRunReplyPermission = "once" | "always" | "reject";
+export type AgentRunReplyQuestion = {
+    answers: Record<string, string[]>;
+} | {
+    reject: true;
+};
+export type AgentRunEvent<T extends AgentRun = AgentRun> = {
+    type: "run.status";
+    run: T;
+} | {
+    type: "input.required";
+    run: T;
+    request: AgentRunInputRequest;
+} | {
+    type: "input.resolved";
+    run: T;
+    requestId: string;
+} | {
+    type: "run.completed" | "run.failed" | "run.cancelled";
+    run: T;
 };
 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;
@@ -293,19 +516,49 @@ export type WorkspaceSetupStatus = {
 export type ModelProviderInfo = {
     id: string;
     name: string;
+    /** Use this key in models.providers and provider/model references. */
+    logicalProviderKey: string;
     displayName: string;
     authType: string;
     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.
- */
-export type WorkspaceModelCredentialInput = {
-    providerName: string;
+export type ModelInfo = {
+    /** Full provider/model identifier accepted by runs.create(). */
+    id: string;
+    name: string;
+    provider: string;
+    isFree: boolean;
+    isRecommended: boolean;
+};
+/** Control-plane configuration, not a live authentication check. */
+export type WorkspaceModelAccess = {
+    providers: Array<{
+        provider: string;
+        source: "saved" | "apiKey";
+        label: string | null;
+        active: boolean;
+    }>;
+    /** Known catalog models whose provider is configured, plus free models. */
+    models: ModelInfo[];
+};
+/** Explicit credential intent. Saved sources use dashboard labels, never credential IDs. */
+export type ModelCredentialSource = {
+    source: "saved";
+    label: string;
+} | {
+    source: "default";
+} | {
+    source: "apiKey";
     apiKey: string;
 };
+export type WorkspaceModelsInput = {
+    /** Workspace default, overridden by runs.create({ model }). */
+    default?: string;
+    /** Default for an explicit block is none. */
+    inherit?: "defaults" | "none";
+    /** Keys are model provider names (e.g. openai for API keys AND ChatGPT subscriptions). */
+    providers?: Record<string, ModelCredentialSource>;
+};
 /** Safe dashboard credential metadata. Secret material is never returned by the SDK. */
 export type ModelCredential = {
     id: string;
@@ -314,7 +567,8 @@ export type ModelCredential = {
     providerDisplayName: string;
     logicalProviderKey: string;
     authType: string;
-    label: string | null;
+    /** Select with models.providers[logicalProviderKey] = { source: "saved", 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.2.0",
   "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,15 +35,17 @@
     "@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/agent-runtime": "workspace:*",
     "@gitterm/api": "workspace:*",
     "@trpc/server": "catalog:",
     "@types/bun": "^1.2.6",
     "typescript": "^5.8.2"
   },
   "engines": {
-    "node": ">=20.18.1"
+    "node": ">=22.12.0"
   }
 }