@gitterm/sdk 0.0.3 → 0.0.4

package/README.md

@@ -72,13 +72,27 @@ self-hosted.
 import { createGittermClient } from "@gitterm/sdk";
 
 const client = createGittermClient({
-  serverUrl: "https://api.gitterm.dev",
   token: process.env.GITTERM_API_TOKEN,
 });
 
 const { workspaces } = await client.workspaces.list();
 ```
 
+The SDK deliberately exposes two clients. `createGittermClient()` uses a user API token and
+can manage the user's workspaces. `createGittermWorkspaceClient()` uses the scoped identity
+injected into a GitTerm workspace and can inspect only that workspace and its ports:
+
+```ts
+import { createGittermWorkspaceClient } from "@gitterm/sdk";
+
+const workspace = createGittermWorkspaceClient();
+const self = await workspace.self.get();
+const preview = await workspace.ports.open(3000, { name: "app" });
+```
+
+The workspace client never reads the CLI's saved account login and has no create, list,
+pause, restart, or terminate operations.
+
 ### With the CLI's saved login
 
 ```ts
@@ -98,18 +112,100 @@ client.workspaces.ensureRunning(workspaceId, options?);
 client.workspaces.pause(workspaceId);
 client.workspaces.restart(workspaceId);
 client.workspaces.terminate(workspaceId);
-client.workspaces.createSandbox({
-  idempotencyKey, repo, branch, baseCommit, checkoutRef,
-  agent, provider, persistent, // provider is optional
+client.workspaces.create({
+  repo: "https://github.com/acme/product",
 });
 client.catalog.agentTypes();
 client.catalog.cloudProviders();
-client.catalog.resolveSandboxDefaults({ agent, provider });
+client.catalog.workspaceOptions();
+```
+
+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:
+
+```ts
+await client.workspaces.create({
+  repo: "https://github.com/acme/product",
+  agent: "opencode",
+  setupCommands: ["npm install", "npm run generate"],
+  opencode: {
+    skills: [
+      {
+        name: "release-demo",
+        content: `---
+name: release-demo
+description: Record and publish a product release demo.
+---
+
+Follow the repository's release-demo workflow.`,
+      },
+    ],
+    plugins: ["@acme/opencode-browser@1.2.3"],
+  },
+  provider: {
+    type: "exedev",
+    machine: { type: "profile", key: "content-rendering" },
+  },
+});
+```
+
+Setup commands run in order from the checked-out repository after the agent server is
+ready. They do not delay workspace creation or stop the agent if they fail. Provider and
+agent defaults configured by an administrator run first. Use
+`client.workspaces.setupStatus(workspaceId)` or `waitForSetup(workspaceId)` to inspect them.
+GitTerm persists the reported state and bounded log; a recovery copy also lives in the
+repository's git-excluded `.gitterm/setup/` directory.
+
+`provider` is a discriminated union, so TypeScript only offers `region` for providers
+where GitTerm supports caller-selected placement. Machine keys are configured by admins
+and returned by `client.catalog.workspaceOptions()`; raw CPU, memory, credentials, and
+provider account configuration are never supplied by SDK callers.
+
+This makes release automation a normal workspace task: create an OpenCode workspace,
+run UI review or browser capture tools in the sandbox, upload the resulting media, update
+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.
+
+### 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.
+
+```ts
+const { workspace } = await client.workspaces.create({
+  repo: "https://github.com/acme/product",
+  setupCommands: ["npm install", "npm run db:seed"],
+});
+
+const run = await client.runs.create({
+  workspaceId: workspace.id,
+  idempotencyKey: "onboarding-v2",
+  waitForSetup: true,
+  prompt: "Record the new onboarding flow and open a pull request adding it to the changelog.",
+});
+
+const completed = await client.runs.wait(workspace.id, run.id);
+const messages = await client.runs.messages(workspace.id, run.id);
+```
+
+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:
+
+```ts
+const next = await client.runs.create({
+  workspaceId: workspace.id,
+  idempotencyKey: "onboarding-tests-v1",
+  prompt: "Now add tests for that change.",
+  context: { type: "continue", runId: completed.id },
+});
 ```
 
-`agent` is the unique enabled agent name (for example `"OpenCode"`).
-`provider` is the unique enabled provider name (for example `"E2B"`).
-Omit `provider` to use the preferred default sandbox provider.
+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.
 
 ### Errors
 
@@ -130,7 +226,7 @@ try {
 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
-`NOT_LOGGED_IN`, `UNAUTHORIZED`, `NOT_FOUND`, `FORBIDDEN`, `BAD_REQUEST`,
+`NOT_LOGGED_IN`, `UNAUTHORIZED`, `NOT_FOUND`, `FORBIDDEN`, `BAD_REQUEST`, `CONFLICT`,
 `SERVER_ERROR`, and `NETWORK`.
 
 The package ships self-contained declarations from `dist`; TypeScript consumers do not

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { AgentType, AuthStatus, CloudProvider, Workspace, WorkspaceCreateInput, WorkspaceCreateResult, WorkspaceEnsureRunningResult, WorkspaceListOptions, WorkspaceListResult, WorkspaceRestartResult, WorkspaceRuntimeAccess, WorkspacePauseResult, WorkspaceTerminateResult, SandboxDefaults, SandboxDefaultsInput } from "./types.js";
+import type { AgentType, AgentRun, AgentRunCreateInput, AgentRunMessage, AuthStatus, CloudProvider, Workspace, WorkspaceCreateInput, WorkspaceCreateResult, WorkspaceEnsureRunningResult, WorkspaceListOptions, WorkspaceListResult, WorkspaceRestartResult, WorkspaceRuntimeAccess, WorkspacePauseResult, WorkspaceTerminateResult, WorkspaceCatalog, WorkspaceSetupStatus } from "./types.js";
 export type GittermClientOptions = {
     serverUrl?: string;
     token?: string;
@@ -22,7 +22,23 @@ export type GittermClient = {
         restart(workspaceId: string): Promise<WorkspaceRestartResult>;
         terminate(workspaceId: string): Promise<WorkspaceTerminateResult>;
         create(input: WorkspaceCreateInput): Promise<WorkspaceCreateResult>;
-        createSandbox(input: WorkspaceCreateInput): Promise<WorkspaceCreateResult>;
+        setupStatus(workspaceId: string): Promise<WorkspaceSetupStatus>;
+        waitForSetup(workspaceId: string, options?: {
+            timeoutMs?: number;
+            pollIntervalMs?: number;
+        }): Promise<WorkspaceSetupStatus>;
+    };
+    runs: {
+        create(input: AgentRunCreateInput): Promise<AgentRun>;
+        get(workspaceId: string, runId: string): Promise<AgentRun>;
+        messages(workspaceId: string, runId: string): Promise<AgentRunMessage[]>;
+        cancel(workspaceId: string, runId: string): Promise<{
+            cancelled: boolean;
+        }>;
+        wait(workspaceId: string, runId: string, options?: {
+            timeoutMs?: number;
+            pollIntervalMs?: number;
+        }): Promise<AgentRun>;
     };
     catalog: {
         agentTypes(input?: {
@@ -34,7 +50,7 @@ export type GittermClient = {
             sandboxOnly?: boolean;
             nonSandboxOnly?: boolean;
         }): Promise<CloudProvider[]>;
-        resolveSandboxDefaults(input: SandboxDefaultsInput): Promise<SandboxDefaults>;
+        workspaceOptions(): Promise<WorkspaceCatalog>;
     };
 };
 export declare function createGittermClient(options?: GittermClientOptions): GittermClient;

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-export type GittermErrorCode = "NOT_LOGGED_IN" | "UNAUTHORIZED" | "NOT_FOUND" | "FORBIDDEN" | "BAD_REQUEST" | "SERVER_ERROR" | "NETWORK" | WorkspaceLifecycleErrorCode;
+export type GittermErrorCode = "NOT_LOGGED_IN" | "UNAUTHORIZED" | "NOT_FOUND" | "FORBIDDEN" | "BAD_REQUEST" | "CONFLICT" | "SERVER_ERROR" | "NETWORK" | WorkspaceLifecycleErrorCode;
 export type WorkspaceLifecycleErrorCode = "WORKSPACE_TERMINATED" | "WORKSPACE_NON_RECOVERABLE" | "WORKSPACE_START_TIMEOUT" | "WORKSPACE_RESTART_FAILED";
 export declare class GittermError extends Error {
     readonly code: GittermErrorCode;

package/dist/index.d.ts

@@ -4,5 +4,6 @@ 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 { createGittermWorkspaceClient, getWorkspaceEnvironment, type GittermWorkspaceClient, type WorkspaceClientOptions, type WorkspaceEnvironment, type WorkspacePort, type WorkspaceSelf, } from "./workspace-client.js";
 export type { GittermErrorCode, WorkspaceLifecycleErrorCode } from "./errors.js";
-export type { AgentType, AuthStatus, CloudProvider, SandboxDefaults, Workspace, WorkspaceCreateInput, WorkspaceCreateResult, WorkspaceEnsureRunningResult, WorkspaceHostingType, WorkspaceListOptions, WorkspaceListResult, WorkspaceRestartResult, WorkspaceRuntimeAccess, WorkspaceStatus, WorkspacePauseResult, WorkspaceTerminateResult, SandboxDefaultsInput, } from "./types.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, WorkspacePauseResult, WorkspaceTerminateResult, WorkspaceProviderSelection, } from "./types.js";

package/dist/index.js

@@ -69,6 +69,36 @@ class WorkspaceLifecycleError extends GittermError {
   }
 }
 
+// src/transport.ts
+var LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+function normalizeServerUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`Invalid GitTerm server URL: ${value}`);
+  }
+  if (url.username || url.password) {
+    throw new Error("GitTerm server URL must not contain credentials");
+  }
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname))) {
+    throw new Error("GitTerm server URL must use HTTPS (HTTP is allowed only for loopback)");
+  }
+  url.hash = "";
+  url.search = "";
+  return url.toString().replace(/\/$/, "");
+}
+function createNoRedirectFetch(fetchImpl = fetch) {
+  return async (input, init) => {
+    const response = await fetchImpl(input, { ...init, redirect: "manual" });
+    if (response.status >= 300 && response.status < 400) {
+      const location = response.headers.get("location");
+      throw new Error(location ? `GitTerm server redirects are not allowed: ${location}` : "GitTerm server redirects are not allowed");
+    }
+    return response;
+  };
+}
+
 // src/client.ts
 function envValue(name) {
   const value = typeof process !== "undefined" ? process.env[name] : undefined;
@@ -76,12 +106,12 @@ function envValue(name) {
 }
 function resolveCredentials(options) {
   const config = !options.serverUrl || !options.token ? loadConfigSync(options.configPath) : null;
-  const serverUrl = options.serverUrl ?? envValue("GITTERM_SERVER_URL") ?? config?.serverUrl;
+  const serverUrl = options.serverUrl ?? envValue("GITTERM_SERVER_URL") ?? config?.serverUrl ?? DEFAULT_GITTERM_SERVER_URL;
   const token = options.token ?? envValue("GITTERM_API_TOKEN") ?? config?.token;
   if (!serverUrl || !token) {
     throw new GittermError("NOT_LOGGED_IN", "Not logged in. Run: gitterm login");
   }
-  return { serverUrl, token };
+  return { serverUrl: normalizeServerUrl(serverUrl), token };
 }
 function toTrpcUrl(serverUrl) {
   return new URL("/trpc", serverUrl).toString();
@@ -161,6 +191,8 @@ function mapTrpcCode(code) {
       return "FORBIDDEN";
     case "BAD_REQUEST":
       return "BAD_REQUEST";
+    case "CONFLICT":
+      return "CONFLICT";
     default:
       return "SERVER_ERROR";
   }
@@ -208,22 +240,13 @@ function createGittermClient(options = {}) {
     links: [
       httpBatchLink({
         url: toTrpcUrl(credentials.serverUrl),
-        fetch: options.fetch,
+        fetch: createNoRedirectFetch(options.fetch),
         headers: () => ({ authorization: `Bearer ${credentials.token}` })
       })
     ]
   });
   const run = (operation) => runWithServer(credentials.serverUrl, operation);
-  const createWorkspace = (input) => run(async () => {
-    const { agent, provider, regionId, ...workspaceInput } = input;
-    const defaults = await trpc.workspace.resolveSandboxDefaults.query({ agent, provider });
-    const apiInput = {
-      ...workspaceInput,
-      agentTypeId: defaults.agentTypeId,
-      cloudProviderId: defaults.cloudProviderId,
-      regionId: regionId ?? defaults.regionId
-    };
-    const result = await trpc.workspace.createWorkspace.mutate(apiInput);
+  const normalizeCreateResult = (result) => {
     const workspace = normalizeWorkspace(result.workspace);
     if (!workspace)
       throw new GittermError("SERVER_ERROR", "Workspace creation failed");
@@ -241,7 +264,30 @@ function createGittermClient(options = {}) {
       providerKey: null
     };
     return { workspace, runtime };
+  };
+  const createWorkspace = (input) => run(async () => {
+    const result = await trpc.workspace.createWorkspace.mutate(input);
+    return normalizeCreateResult(result);
   });
+  const waitForWorkspaceSetup = async (workspaceId, waitOptions) => {
+    const timeoutMs = waitOptions?.timeoutMs ?? 10 * 60000;
+    const pollIntervalMs = waitOptions?.pollIntervalMs ?? 2000;
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+      const result = await trpc.workspace.getSetupStatus.query({ workspaceId });
+      if (result.status === "not_requested" || result.status === "succeeded")
+        return result;
+      if (result.status === "failed") {
+        const log = result.log?.trim();
+        throw new GittermError("BAD_REQUEST", `Workspace setup failed${result.exitCode === null ? "" : ` with exit code ${result.exitCode}`}${log ? `
+${log}` : ""}`);
+      }
+      if (Date.now() >= deadline) {
+        throw new GittermError("NETWORK", `Timed out waiting for workspace ${workspaceId} setup`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+  };
   return {
     serverUrl: credentials.serverUrl,
     auth: {
@@ -306,7 +352,28 @@ function createGittermClient(options = {}) {
         };
       }),
       create: createWorkspace,
-      createSandbox: createWorkspace
+      setupStatus: (workspaceId) => run(async () => trpc.workspace.getSetupStatus.query({ workspaceId })),
+      waitForSetup: (workspaceId, waitOptions) => run(() => waitForWorkspaceSetup(workspaceId, 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));
+        }
+      })
     },
     catalog: {
       agentTypes: (input) => run(async () => {
@@ -317,7 +384,7 @@ function createGittermClient(options = {}) {
         const result = await trpc.workspace.listCloudProviders.query(input);
         return result.cloudProviders;
       }),
-      resolveSandboxDefaults: (input) => run(async () => trpc.workspace.resolveSandboxDefaults.query(input))
+      workspaceOptions: () => run(async () => trpc.workspace.getWorkspaceCatalog.query())
     }
   };
 }
@@ -326,8 +393,9 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 async function loginWithDeviceCode(serverUrl, options = {}) {
-  const fetchImpl = options.fetch ?? fetch;
-  const codeRes = await fetchImpl(new URL("/api/device/code", serverUrl), {
+  const normalizedServerUrl = normalizeServerUrl(serverUrl);
+  const fetchImpl = createNoRedirectFetch(options.fetch);
+  const codeRes = await fetchImpl(new URL("/api/device/code", normalizedServerUrl), {
     method: "POST",
     headers: { "content-type": "application/json" },
     body: JSON.stringify({ clientName: options.clientName ?? "gitterm" })
@@ -343,7 +411,7 @@ async function loginWithDeviceCode(serverUrl, options = {}) {
   });
   const deadline = Date.now() + codeJson.expiresInSeconds * 1000;
   while (Date.now() < deadline) {
-    const tokenRes = await fetchImpl(new URL("/api/device/token", serverUrl), {
+    const tokenRes = await fetchImpl(new URL("/api/device/token", normalizedServerUrl), {
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify({ deviceCode: codeJson.deviceCode })
@@ -360,13 +428,76 @@ async function loginWithDeviceCode(serverUrl, options = {}) {
   }
   throw new Error("Device code expired; try again.");
 }
+// src/workspace-client.ts
+import { TRPCClientError as TRPCClientError2, createTRPCClient as createTRPCClient2, httpBatchLink as httpBatchLink2 } from "@trpc/client";
+function getWorkspaceEnvironment(environment) {
+  environment ??= typeof process === "undefined" ? {} : process.env;
+  const serverUrl = environment.WORKSPACE_API_URL;
+  const token = environment.WORKSPACE_AUTH_TOKEN;
+  const workspaceId = environment.WORKSPACE_ID;
+  const workspaceEnvironmentPresent = Boolean(serverUrl || token || workspaceId);
+  if (!workspaceEnvironmentPresent)
+    return null;
+  if (!serverUrl || !token || !workspaceId) {
+    throw new GittermError("UNAUTHORIZED", "Incomplete GitTerm workspace environment: WORKSPACE_API_URL, WORKSPACE_AUTH_TOKEN, and WORKSPACE_ID are required");
+  }
+  return { serverUrl: normalizeServerUrl(serverUrl), token, workspaceId };
+}
+function errorCode(code) {
+  if (code === "UNAUTHORIZED" || code === "NOT_FOUND" || code === "FORBIDDEN")
+    return code;
+  if (code === "BAD_REQUEST")
+    return code;
+  return "SERVER_ERROR";
+}
+function createGittermWorkspaceClient(options = {}) {
+  const detected = options.serverUrl && options.token && options.workspaceId ? null : getWorkspaceEnvironment();
+  const rawServerUrl = options.serverUrl ?? detected?.serverUrl;
+  const token = options.token ?? detected?.token;
+  const workspaceId = options.workspaceId ?? detected?.workspaceId;
+  if (!rawServerUrl || !token || !workspaceId) {
+    throw new GittermError("UNAUTHORIZED", "This command must run inside a GitTerm workspace");
+  }
+  const serverUrl = normalizeServerUrl(rawServerUrl);
+  const trpc = createTRPCClient2({
+    links: [
+      httpBatchLink2({
+        url: new URL("/trpc", serverUrl).toString(),
+        fetch: createNoRedirectFetch(options.fetch),
+        headers: () => ({ authorization: `Bearer ${token}` })
+      })
+    ]
+  });
+  async function run(operation) {
+    try {
+      return await operation();
+    } catch (error) {
+      if (error instanceof TRPCClientError2) {
+        throw new GittermError(errorCode(error.data?.code), error.message, { cause: error });
+      }
+      throw new GittermError("NETWORK", error instanceof Error ? error.message : "Network request failed", { cause: error });
+    }
+  }
+  return {
+    workspaceId,
+    serverUrl,
+    self: { get: () => run(() => trpc.workspaceOps.getSelf.query()) },
+    ports: {
+      list: () => run(() => trpc.workspaceOps.listPorts.query()),
+      open: (port, input) => run(() => trpc.workspaceOps.openPort.mutate({ port, ...input })),
+      close: (port) => run(() => trpc.workspaceOps.closePort.mutate({ port }))
+    }
+  };
+}
 export {
   saveConfig,
   loginWithDeviceCode,
   loadConfigSync,
   loadConfig,
+  getWorkspaceEnvironment,
   getConfigPath,
   deleteConfig,
+  createGittermWorkspaceClient,
   createGittermClient,
   WorkspaceLifecycleError,
   GittermError,

package/dist/transport.d.ts

@@ -0,0 +1,2 @@
+export declare function normalizeServerUrl(value: string): string;
+export declare function createNoRedirectFetch(fetchImpl?: typeof fetch): typeof fetch;

package/dist/types.d.ts

@@ -72,23 +72,110 @@ export type WorkspaceListResult = {
         hasMore: boolean;
     };
 };
+export type ProviderKey = "railway" | "aws" | "e2b" | "daytona" | "cloudflare" | "vercel" | "ascii" | "exedev";
+type ProviderSelectionBase = {
+    /** Select a specific provider installation. Usually omitted. */
+    providerId?: string;
+    /** An admin-defined profile or flexible resources within the provider's allowed limits. */
+    machine?: {
+        type: "profile";
+        key: string;
+    };
+};
+type FlexibleMachine<T> = {
+    type: "profile";
+    key: string;
+} | {
+    type: "custom";
+    resources: T;
+};
+type AwsResources = {
+    cpu?: number;
+    memory?: number;
+    ephemeralStorageGiB?: number;
+    architecture?: "X86_64" | "ARM64";
+};
+type DaytonaResources = {
+    resources?: {
+        cpu?: number;
+        memory?: number;
+        disk?: number;
+    };
+    editorResources?: {
+        cpu?: number;
+        memory?: number;
+        disk?: number;
+    };
+};
+type VercelResources = {
+    vcpus?: number;
+};
+type ExeDevResources = {
+    cpu?: number;
+    memory?: string;
+    disk?: string;
+};
+export type WorkspaceProviderSelection = {
+    type: "railway";
+    providerId?: string;
+    region?: string;
+} | ({
+    type: "aws";
+    region?: string;
+} & Omit<ProviderSelectionBase, "machine"> & {
+    machine?: FlexibleMachine<AwsResources>;
+}) | ({
+    type: "daytona";
+} & Omit<ProviderSelectionBase, "machine"> & {
+    machine?: FlexibleMachine<DaytonaResources>;
+}) | ({
+    type: "vercel";
+} & Omit<ProviderSelectionBase, "machine"> & {
+    machine?: FlexibleMachine<VercelResources>;
+}) | ({
+    type: "exedev";
+} & Omit<ProviderSelectionBase, "machine"> & {
+    machine?: FlexibleMachine<ExeDevResources>;
+}) | ({
+    type: "e2b" | "ascii";
+} & ProviderSelectionBase) | {
+    type: "cloudflare";
+    providerId?: string;
+};
+export type BuiltInAgentKey = "opencode-ttyd" | "opencode" | "t3code";
+export type AgentKey = BuiltInAgentKey | (string & {});
 export type WorkspaceCreateInput = {
     idempotencyKey?: string;
     name?: string;
-    repo?: string;
+    repo: string;
     branch?: string;
     baseCommit?: string;
     checkoutRef?: string;
     subdomain?: string;
-    /** Unique enabled agent name. */
-    agent: string;
-    /** Unique enabled provider name. Optional when a preferred default exists. */
-    provider?: string;
-    regionId?: string;
+    /** Stable agent key. Defaults to `opencode`. */
+    agent?: AgentKey;
+    /** Provider intent. Defaults to the user's or deployment's preferred provider. */
+    provider?: WorkspaceProviderSelection;
     gitIntegrationId?: string;
-    persistent: boolean;
+    /** Defaults from the selected provider. */
+    persistent?: boolean;
     workspaceProfile?: "standard" | "ssh-enabled";
     modelCredentialIds?: string[];
+    /**
+     * Ordered commands launched in the repository after the agent server starts.
+     * They do not block workspace readiness; inspect ~/.gitterm/setup for status
+     * and logs through workspaces.setupStatus()/waitForSetup().
+     */
+    setupCommands?: string[];
+    /** OpenCode capabilities materialized only in this workspace. */
+    opencode?: {
+        skills?: Array<{
+            name: string;
+            content: string;
+        }>;
+        /** NPM package specs or plugin paths accepted by OpenCode. Pin versions for repeatable runs. */
+        plugins?: string[];
+    };
 };
 export type WorkspaceRestartResult = {
     status: WorkspaceStatus;
@@ -104,8 +191,59 @@ export type WorkspaceEnsureRunningResult = {
     workspace: Workspace;
     runtime: WorkspaceRuntimeAccess;
 };
+export type AgentRunStatus = "pending" | "running" | "retrying" | "completed" | "failed" | "cancelled";
+export type AgentRun = {
+    id: string;
+    workspaceId: string;
+    title: string;
+    status: AgentRunStatus;
+    error: string | null;
+    finalText: string | null;
+    context: {
+        type: "isolated";
+    } | {
+        type: "continued";
+        runId: string;
+    };
+};
+export type AgentRunCreateInput = {
+    workspaceId: string;
+    /** Stable key used to return the same run when a request is retried. */
+    idempotencyKey: string;
+    prompt: string;
+    title?: string;
+    agent?: string;
+    /** OpenCode model in provider/model format. */
+    model?: string;
+    /** Start with fresh context (default), or continue a terminal run's context. */
+    context?: {
+        type: "isolated";
+    } | {
+        type: "continue";
+        runId: string;
+    };
+    /** Wait for workspace setup commands before submitting the prompt. */
+    waitForSetup?: boolean;
+    setupTimeoutMs?: number;
+};
+export type AgentRunMessage = {
+    id: string;
+    role: "user" | "assistant";
+    createdAt: string;
+    completedAt: string | null;
+    text: string;
+    error: string | null;
+};
+export type WorkspaceSetupStatus = {
+    status: "not_requested" | "waiting" | "running" | "succeeded" | "failed";
+    exitCode: number | null;
+    startedAt: string | null;
+    finishedAt: string | null;
+    log: string | null;
+};
 export type AgentType = {
     id: string;
+    key: string;
     name: string;
     description: string | null;
     serverOnly: boolean;
@@ -116,18 +254,44 @@ export type AgentType = {
 export type CloudProvider = {
     id: string;
     name: string;
-    providerKey: string;
-    regions?: Array<Record<string, unknown>>;
-    [key: string]: unknown;
-};
-export type SandboxDefaults = {
-    agent: string;
-    provider: string;
-    agentTypeId: string;
-    cloudProviderId: string;
-    regionId?: string;
+    providerKey: ProviderKey | string;
+    regions?: Array<{
+        id: string;
+        name: string;
+        location: string;
+        externalRegionIdentifier: string;
+    }>;
 };
-export type SandboxDefaultsInput = {
-    agent: string;
-    provider?: string;
+export type WorkspaceCatalog = {
+    agents: Array<{
+        id: string;
+        key: string;
+        name: string;
+        description: string | null;
+        serverOnly: boolean;
+    }>;
+    providers: Array<{
+        id: string;
+        type: ProviderKey;
+        name: string;
+        isDefault: boolean;
+        persistence: "required" | "optional" | "unsupported";
+        regionSelection: "none" | "user" | "admin";
+        regions: Array<{
+            id: string;
+            key: string;
+            name: string;
+            location: string;
+        }>;
+        machines: Array<{
+            id: string;
+            key: string;
+            name: string;
+            description: string | null;
+            isDefault: boolean;
+        }>;
+        agentKeys: string[];
+        ssh: boolean;
+    }>;
 };
+export {};

package/dist/workspace-client.d.ts

@@ -0,0 +1,44 @@
+export type WorkspaceEnvironment = {
+    serverUrl: string;
+    token: string;
+    workspaceId: string;
+};
+export type WorkspaceSelf = {
+    id: string;
+    name: string | null;
+    status: "pending" | "running" | "paused" | "terminated";
+    repositoryUrl: string | null;
+    repositoryBranch: string | null;
+    baseCommit: string | null;
+    checkoutRef: string | null;
+    providerKey: string | null;
+    url: string | null;
+    ports: WorkspacePort[];
+};
+export type WorkspacePort = {
+    port: number;
+    name: string | null;
+    url: string | null;
+};
+export type WorkspaceClientOptions = Partial<WorkspaceEnvironment> & {
+    fetch?: typeof globalThis.fetch;
+};
+export type GittermWorkspaceClient = {
+    workspaceId: string;
+    serverUrl: string;
+    self: {
+        get(): Promise<WorkspaceSelf>;
+    };
+    ports: {
+        list(): Promise<WorkspacePort[]>;
+        open(port: number, options?: {
+            name?: string;
+        }): Promise<WorkspacePort>;
+        close(port: number): Promise<{
+            port: number;
+            closed: boolean;
+        }>;
+    };
+};
+export declare function getWorkspaceEnvironment(environment?: Record<string, string | undefined>): WorkspaceEnvironment | null;
+export declare function createGittermWorkspaceClient(options?: WorkspaceClientOptions): GittermWorkspaceClient;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitterm/sdk",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "files": [
     "dist"
   ],