@gitterm/sdk 0.0.7 → 0.1.0

package/dist/direct/provisioning.d.ts

@@ -0,0 +1,34 @@
+import type { DirectProviderWorkspaceInput, DirectProvisioningPlan, DirectModelCredential, DirectWorkspaceCreateInput, DirectWorkspaceRuntime } from "./types.js";
+export declare const DIRECT_OPENCODE_PORT = 4096;
+export declare const DIRECT_OPENCODE_COMMAND = "opencode serve --hostname 0.0.0.0 --port 4096";
+export declare const DIRECT_OPENCODE_SERVER_IMAGE = "opeoginni/gitterm-opencode-server:latest";
+export declare const DIRECT_E2B_TEMPLATES: {
+    readonly standard: "gitterm-opencode-server";
+    readonly large: "gitterm-opencode-server-lg";
+};
+export declare function resolveDirectImage(image?: string): string;
+export declare function directModelAuth(credential: DirectModelCredential): {
+    enterpriseUrl?: string | undefined;
+    accountId?: string | undefined;
+    type: "oauth";
+    refresh: string;
+    access: string;
+    expires: number;
+} | {
+    metadata?: Record<string, string> | undefined;
+    type: "api";
+    key: string;
+};
+export declare function repositoryName(url: string): string;
+export declare function buildDirectProvisioningPlan(input: DirectWorkspaceCreateInput & {
+    id: string;
+    lifecycle: DirectProviderWorkspaceInput["lifecycle"];
+    password: string;
+}): DirectProvisioningPlan;
+export declare function railwayContainerEnvironment(plan: DirectProvisioningPlan): Record<string, string>;
+export declare function setupCommandScript(commands: string[]): string;
+export declare function shellQuote(value: string): string;
+export declare function cloneRepositoryScript(repository: NonNullable<DirectProvisioningPlan["repository"]>, directory: string): string;
+export declare function pinFloatingDockerImage(image: string): Promise<string>;
+export declare function basicAuthHeader(password: string): string;
+export declare function waitForDirectRuntime(runtime: DirectWorkspaceRuntime, timeoutMs?: number): Promise<void>;

package/dist/direct/railway.d.ts

@@ -0,0 +1,2 @@
+import type { DirectProviderAdapter, RailwayDirectProviderConfig } from "./types.js";
+export declare function createRailwayDirectProvider(config: RailwayDirectProviderConfig): DirectProviderAdapter;

package/dist/direct/types.d.ts

@@ -0,0 +1,285 @@
+export type DirectWorkspaceLifecycle = "ephemeral" | "persistent";
+export type DirectWorkspaceStatus = "pending" | "running" | "paused" | "failed" | "terminated" | "unknown";
+export type DirectProviderCapabilities = {
+    persistence: "supported" | "unsupported";
+    recommendedLifecycle: DirectWorkspaceLifecycle;
+    supportsPause: boolean;
+    /** Whether manually pausing an ephemeral workspace preserves its filesystem/session. */
+    ephemeralPause: "stateful" | "state-losing" | "unsupported";
+    supportsKeepAlive: boolean;
+};
+export type DirectApiModelCredential = {
+    providerName: string;
+    type?: "api";
+    apiKey: string;
+    metadata?: Record<string, string>;
+};
+export type DirectOAuthModelCredential = {
+    providerName: string;
+    type: "oauth";
+    refreshToken: string;
+    /** May be omitted when OpenCode should refresh immediately. */
+    accessToken?: string;
+    /** Unix epoch time in milliseconds. Defaults to expired when omitted. */
+    expiresAt?: number;
+    accountId?: string;
+    enterpriseUrl?: string;
+};
+export type DirectModelCredential = DirectApiModelCredential | DirectOAuthModelCredential;
+export type DirectAuthPrompt = {
+    type: "text";
+    key: string;
+    message: string;
+    placeholder?: string;
+    when?: {
+        key: string;
+        op: "eq" | "neq";
+        value: string;
+    };
+} | {
+    type: "select";
+    key: string;
+    message: string;
+    options: Array<{
+        label: string;
+        value: string;
+        hint?: string;
+    }>;
+    when?: {
+        key: string;
+        op: "eq" | "neq";
+        value: string;
+    };
+};
+export type DirectAuthMethod = {
+    type: "oauth";
+    id: string;
+    label: string;
+    prompts?: DirectAuthPrompt[];
+} | {
+    type: "key";
+    label?: string;
+} | {
+    type: "env";
+    names: string[];
+};
+export type DirectAuthIntegration = {
+    id: string;
+    name: string;
+    methods: DirectAuthMethod[];
+    connections: Array<{
+        type: "credential";
+        id: string;
+        label: string;
+    } | {
+        type: "env";
+        name: string;
+    }>;
+};
+export type DirectAuthAttempt = {
+    id: string;
+    workspaceId: string;
+    integrationId: string;
+    url: string;
+    instructions: string;
+    mode: "auto" | "code";
+    createdAt: number;
+    expiresAt: number;
+};
+export type DirectAuthAttemptStatus = {
+    status: "pending";
+    createdAt: number;
+    expiresAt: number;
+} | {
+    status: "complete";
+    createdAt: number;
+    expiresAt: number;
+} | {
+    status: "failed";
+    message: string;
+    createdAt: number;
+    expiresAt: number;
+} | {
+    status: "expired";
+    createdAt: number;
+    expiresAt: number;
+};
+export type DirectAuthWaitOptions = {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+};
+export type DirectWorkspaceCreateInput = {
+    id?: string;
+    repo?: string;
+    branch?: string;
+    baseCommit?: string;
+    checkoutRef?: string;
+    repositoryCredentials?: {
+        username?: string;
+        token: string;
+    };
+    lifecycle?: DirectWorkspaceLifecycle;
+    environmentVariables?: Record<string, string>;
+    modelCredentials?: DirectModelCredential[];
+    setupCommands?: string[];
+    opencode?: {
+        config?: Record<string, unknown>;
+        plugins?: string[];
+        skills?: Array<{
+            name: string;
+            content: string;
+        }>;
+    };
+};
+export type DirectWorkspaceRuntime = {
+    url: string;
+    directory: string;
+    headers?: Record<string, string>;
+    password?: string;
+};
+export type DirectWorkspace = {
+    id: string;
+    provider: string;
+    externalId: string;
+    status: DirectWorkspaceStatus;
+    lifecycle: DirectWorkspaceLifecycle;
+    runtime: DirectWorkspaceRuntime;
+    createdAt: string;
+};
+export type DirectProviderWorkspaceInput = DirectWorkspaceCreateInput & {
+    id: string;
+    lifecycle: DirectWorkspaceLifecycle;
+    password: string;
+    provisioning: DirectProvisioningPlan;
+};
+export type DirectAgentFile = {
+    path: string;
+    contentBase64: string;
+};
+export type DirectProvisioningPlan = {
+    workspaceId: string;
+    lifecycle: DirectWorkspaceLifecycle;
+    repository?: {
+        url: string;
+        name: string;
+        branch?: string;
+        checkoutRef?: string;
+        baseCommit?: string;
+        authUsername?: string;
+        authToken?: string;
+    };
+    agent: {
+        files: DirectAgentFile[];
+        environmentVariables: Record<string, string>;
+        command: string;
+        port: number;
+    };
+    setupCommands: string[];
+};
+export interface DirectProviderAdapter {
+    readonly name: string;
+    readonly capabilities: DirectProviderCapabilities;
+    create(input: DirectProviderWorkspaceInput): Promise<{
+        externalId: string;
+        runtime: DirectWorkspaceRuntime;
+    }>;
+    status(workspace: DirectWorkspace): Promise<DirectWorkspaceStatus>;
+    pause?(workspace: DirectWorkspace): Promise<void>;
+    resume?(workspace: DirectWorkspace): Promise<Partial<DirectWorkspaceRuntime> | void>;
+    terminate(workspace: DirectWorkspace): Promise<void>;
+    keepAlive?(workspace: DirectWorkspace, timeoutMs: number): Promise<void>;
+}
+export type E2BDirectProviderConfig = {
+    type: "e2b";
+    apiKey: string;
+    /** Optional. Defaults to standard. */
+    size?: "standard" | "large";
+    /** Optional. Overrides size with a specific E2B template. */
+    templateId?: string;
+    timeoutMs?: number;
+};
+export type DaytonaDirectProviderConfig = {
+    type: "daytona";
+    apiKey: string;
+    target: "us" | "eu";
+    /** Optional. Defaults to the public Gitterm OpenCode server image. Floating tags are pinned to a digest. */
+    image?: string;
+    cpu?: number;
+    memory?: number;
+    disk?: number;
+};
+export type VercelDirectProviderConfig = {
+    type: "vercel";
+    apiToken: string;
+    teamId: string;
+    projectId: string;
+    /** Optional VCR image. When omitted, the configured Node runtime is used. */
+    image?: string;
+    runtime?: "node26" | "node24" | "node22" | "python3.13";
+    runtimeSetupCommands?: string[];
+    vcpus?: number;
+    timeoutMs?: number;
+};
+export type AsciiDirectProviderConfig = {
+    type: "ascii";
+    apiKey: string;
+    size?: "small" | "default" | "large";
+    runtimeSetupCommands?: string[];
+    timeoutMs?: number | null;
+};
+export type ExeDevDirectProviderConfig = {
+    type: "exedev";
+    /**
+     * Token `cmds` must include `new`, `ls`, `ssh`, `share`, `ssh-key`, `pause`, `resume`, and `rm`.
+     * Default tokens cannot provision or clean up a Gitterm workspace.
+     */
+    apiToken: string;
+    /** Optional. Defaults to the public Gitterm OpenCode server image. */
+    image?: string;
+    cpu?: number;
+    memory?: string;
+    disk?: string;
+    runtimeSetupCommands?: string[];
+};
+export type RailwayDirectProviderConfig = {
+    type: "railway";
+    apiToken: string;
+    apiUrl?: string;
+    projectId: string;
+    environmentId: string;
+    region?: string;
+    /** Optional. Defaults to the public Gitterm OpenCode server image. */
+    image?: string;
+    runtimePort?: number;
+};
+export type DirectProviderConfig = E2BDirectProviderConfig | DaytonaDirectProviderConfig | VercelDirectProviderConfig | AsciiDirectProviderConfig | ExeDevDirectProviderConfig | RailwayDirectProviderConfig;
+export type DirectRunCreateInput = {
+    workspace: DirectWorkspace;
+    prompt: string;
+    title?: string;
+    agent?: string;
+    model?: string;
+    /** Reuse this native OpenCode session for conversational context. */
+    sessionId?: string;
+};
+export type DirectRun = {
+    id: string;
+    workspaceId: string;
+    sessionId: string;
+    messageId: string;
+    title: string;
+    status: "running" | "retrying" | "completed" | "failed" | "cancelled";
+    error: string | null;
+    finalText: string | null;
+    submittedAt: string;
+};
+export type DirectRunMessage = {
+    id: string;
+    role: "user" | "assistant";
+    text: string;
+    error: string | null;
+};
+export type DirectRunWaitOptions = {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+};

package/dist/direct/vercel.d.ts

@@ -0,0 +1,2 @@
+import type { DirectProviderAdapter, VercelDirectProviderConfig } from "./types.js";
+export declare function createVercelDirectProvider(config: VercelDirectProviderConfig): DirectProviderAdapter;

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`. */
@@ -169,6 +180,8 @@ export type WorkspaceCreateInput = {
      * inline; connect those in the dashboard.
      */
     modelCredentials?: WorkspaceModelCredentialInput[];
+    /** Ephemeral environment variables injected into this workspace only. */
+    environmentVariables?: Record<string, string>;
     /**
      * Ordered commands launched in the repository after the agent server starts.
      * They do not block workspace readiness; inspect ~/.gitterm/setup for status
@@ -183,6 +196,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 = {
@@ -232,6 +251,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 = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitterm/sdk",
-  "version": "0.0.7",
+  "version": "0.1.0",
   "files": [
     "dist"
   ],
@@ -11,18 +11,29 @@
       "bun": "./dist/index.js",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./direct": {
+      "types": "./dist/direct/index.d.ts",
+      "bun": "./dist/direct/index.js",
+      "import": "./dist/direct/index.js",
+      "default": "./dist/direct/index.js"
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "rm -rf dist && bun build src/index.ts --outdir dist --target node --format esm --external @trpc/client && 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 @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"
   },
   "dependencies": {
-    "@trpc/client": "^11.8.1"
+    "@asciidev/box-sdk": "^0.0.34",
+    "@daytonaio/sdk": "^0.207.0",
+    "@opencode-ai/sdk": "^1.18.25",
+    "@trpc/client": "^11.8.1",
+    "@vercel/sandbox": "^3.2.1",
+    "e2b": "^2.46.1"
   },
   "devDependencies": {
     "@gitterm/api": "workspace:*",
@@ -31,6 +42,6 @@
     "typescript": "^5.8.2"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20.18.1"
   }
 }