@gitterm/sdk 0.0.6 → 0.0.8

package/README.md

@@ -203,6 +203,56 @@ 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.
+
+```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),
+});
+```
+
+**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.
+
+```ts
+const { workspace } = await client.workspaces.create({
+  repo: "https://github.com/acme/product",
+  modelCredentials: [{ providerName: "anthropic", apiKey: process.env.ANTHROPIC_API_KEY! }],
+});
+
+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",
+});
+```
+
+Rules and errors:
+
+- Omit both fields to inject the dashboard defaults.
+- 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`.
+- 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.

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 } from "./types.js";
+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";
 export type GittermClientOptions = {
     serverUrl?: string;
     token?: string;
@@ -52,5 +52,9 @@ export type GittermClient = {
         }): Promise<CloudProvider[]>;
         workspaceOptions(): Promise<WorkspaceCatalog>;
     };
+    credentials: {
+        list(): Promise<ModelCredential[]>;
+        listProviders(): Promise<ModelProviderInfo[]>;
+    };
 };
 export declare function createGittermClient(options?: GittermClientOptions): GittermClient;

package/dist/errors.d.ts

@@ -1,4 +1,5 @@
-export type GittermErrorCode = "NOT_LOGGED_IN" | "UNAUTHORIZED" | "NOT_FOUND" | "FORBIDDEN" | "BAD_REQUEST" | "CONFLICT" | "SERVER_ERROR" | "NETWORK" | WorkspaceLifecycleErrorCode;
+export type GittermErrorCode = "NOT_LOGGED_IN" | "UNAUTHORIZED" | "NOT_FOUND" | "FORBIDDEN" | "BAD_REQUEST" | "CONFLICT" | "SERVER_ERROR" | "NETWORK" | 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 declare class GittermError extends Error {
     readonly code: GittermErrorCode;

package/dist/index.d.ts

@@ -5,5 +5,5 @@ 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 { 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";
+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";

package/dist/index.js

@@ -197,6 +197,10 @@ function mapTrpcCode(code) {
       return "SERVER_ERROR";
   }
 }
+function credentialErrorCode(message) {
+  const match = /^(MODEL_CREDENTIAL_(?:UNAVAILABLE|DUPLICATE_PROVIDER|INVALID|REQUIRED)):\s*/.exec(message);
+  return match?.[1];
+}
 async function runWithServer(serverUrl, operation) {
   try {
     return await operation();
@@ -211,6 +215,9 @@ async function runWithServer(serverUrl, operation) {
         });
       }
       const code = mapTrpcCode(trpcCode);
+      const credentialCode = credentialErrorCode(error.message);
+      if (credentialCode)
+        throw new GittermError(credentialCode, error.message, { cause: error });
       if (/WORKSPACE_TERMINATED/.test(error.message)) {
         throw new WorkspaceLifecycleError("WORKSPACE_TERMINATED", error.message, { cause: error });
       }
@@ -283,7 +290,9 @@ function createGittermClient(options = {}) {
 ${log}` : ""}`);
       }
       if (Date.now() >= deadline) {
-        throw new GittermError("NETWORK", `Timed out waiting for workspace ${workspaceId} setup`);
+        const log = result.log?.trim();
+        throw new GittermError("NETWORK", `Timed out waiting for workspace ${workspaceId} setup (last status: ${result.status})${log ? `
+${log}` : ""}`);
       }
       await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
     }
@@ -385,6 +394,28 @@ ${log}` : ""}`);
         return result.cloudProviders;
       }),
       workspaceOptions: () => run(async () => trpc.workspace.getWorkspaceCatalog.query())
+    },
+    credentials: {
+      list: () => run(async () => {
+        const result = await trpc.modelCredentials.listMyCredentials.query();
+        return result.credentials.map((credential) => ({
+          ...credential,
+          lastUsedAt: toIso(credential.lastUsedAt),
+          oauthExpiresAt: toIso(credential.oauthExpiresAt),
+          createdAt: toIso(credential.createdAt),
+          updatedAt: toIso(credential.updatedAt)
+        }));
+      }),
+      listProviders: () => run(async () => {
+        const result = await trpc.modelCredentials.listProviders.query();
+        return result.providers.map((provider) => ({
+          id: provider.id,
+          name: provider.name,
+          displayName: provider.displayName,
+          authType: provider.authType,
+          isRecommended: provider.isRecommended
+        }));
+      })
     }
   };
 }

package/dist/types.d.ts

@@ -115,6 +115,11 @@ type ExeDevResources = {
     memory?: string;
     disk?: string;
 };
+/** E2B fixes CPU/RAM per template, so resources select a template build. */
+type E2bResources = {
+    templateId?: string;
+    sshTemplateId?: string;
+};
 export type WorkspaceProviderSelection = {
     type: "railway";
     providerId?: string;
@@ -137,7 +142,11 @@ export type WorkspaceProviderSelection = {
 } & Omit<ProviderSelectionBase, "machine"> & {
     machine?: FlexibleMachine<ExeDevResources>;
 }) | ({
-    type: "e2b" | "ascii";
+    type: "e2b";
+} & Omit<ProviderSelectionBase, "machine"> & {
+    machine?: FlexibleMachine<E2bResources>;
+}) | ({
+    type: "ascii";
 } & ProviderSelectionBase) | {
     type: "cloudflare";
     providerId?: string;
@@ -149,7 +158,9 @@ export type WorkspaceCreateInput = {
     name?: string;
     repo: string;
     branch?: string;
+    /** Commit SHA to pin the checkout to after cloning `branch`/`checkoutRef`. */
     baseCommit?: string;
+    /** Branch or tag to clone when distinct from the display `branch`. Not a commit SHA — use `baseCommit` to pin a revision. */
     checkoutRef?: string;
     subdomain?: string;
     /** Stable agent key. Defaults to `opencode`. */
@@ -160,7 +171,15 @@ 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[];
     /**
      * Ordered commands launched in the repository after the agent server starts.
      * They do not block workspace readiness; inspect ~/.gitterm/setup for status
@@ -175,6 +194,12 @@ export type WorkspaceCreateInput = {
         }>;
         /** NPM package specs or plugin paths accepted by OpenCode. Pin versions for repeatable runs. */
         plugins?: string[];
+        /**
+         * OpenCode config (opencode.json keys) merged over your saved config for
+         * this workspace only. e.g. { permission: { edit: "allow", bash: "allow",
+         * webfetch: "allow" } } disables tool approval prompts in headless runs.
+         */
+        config?: Record<string, unknown>;
     };
 };
 export type WorkspaceRestartResult = {
@@ -224,6 +249,7 @@ export type AgentRunCreateInput = {
     };
     /** Wait for workspace setup commands before submitting the prompt. */
     waitForSetup?: boolean;
+    /** How long to wait for setup, in ms. Server maximum is 600000 (10 minutes). */
     setupTimeoutMs?: number;
 };
 export type AgentRunMessage = {
@@ -241,6 +267,44 @@ export type WorkspaceSetupStatus = {
     finishedAt: string | null;
     log: string | null;
 };
+/**
+ * A model provider from the Gitterm registry. `name` is what credential
+ * inputs reference; `authType` tells you whether it accepts inline API keys
+ * ("api_key") or requires the dashboard OAuth flow ("oauth").
+ */
+export type ModelProviderInfo = {
+    id: string;
+    name: 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;
+    apiKey: string;
+};
+/** Safe dashboard credential metadata. Secret material is never returned by the SDK. */
+export type ModelCredential = {
+    id: string;
+    providerId: string;
+    providerName: string;
+    providerDisplayName: string;
+    logicalProviderKey: string;
+    authType: string;
+    label: string | null;
+    keyHash: string;
+    isActive: boolean;
+    isDefault: boolean;
+    lastUsedAt: string | null;
+    oauthExpiresAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
 export type AgentType = {
     id: string;
     key: string;
@@ -292,6 +356,13 @@ export type WorkspaceCatalog = {
         }>;
         agentKeys: string[];
         ssh: boolean;
+        /**
+         * Whether workspaces on this provider can call the gitterm API from
+         * inside the sandbox (scoped CLI, setup push reports, credential
+         * refresh). False for e.g. Daytona Tier 1/2 organizations, where setup
+         * status is reconciled by server-side polling instead.
+         */
+        workspaceApiAccess: boolean;
     }>;
 };
 export {};

package/package.json

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