@gitterm/sdk 0.0.8 → 0.1.1

package/dist/direct/provisioning.d.ts

@@ -0,0 +1,39 @@
+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 const DIRECT_GITTERM_INSTRUCTIONS = "You are running in a direct Gitterm workspace. Follow the user's instructions and verify outcomes before reporting success.";
+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 validateDirectFilePath(path: string): string;
+export declare function validateDirectFileMode(mode?: number): number;
+export declare function buildDirectGittermInstructions(additional?: string): 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 shellPath(path: 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,319 @@
+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 DirectSecretFile = {
+    /** Absolute path or a path below the workspace user's home (`~/...`). */
+    path: string;
+    content: string;
+    /** Unix permission bits. Defaults to owner read/write (0600). */
+    mode?: number;
+};
+export type DirectWorkspaceSetup = {
+    beforeAgent?: string[];
+    afterAgent?: string[];
+};
+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[];
+    setup?: DirectWorkspaceSetup;
+    secretFiles?: DirectSecretFile[];
+    /** Provider-specific attachment settings. */
+    exedev?: {
+        existingVmName: string;
+    };
+    /** Trusted integration context appended to the generated global AGENTS.md. */
+    additionalAgentInstructions?: 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;
+    setup: "not_requested" | "before_agent_complete" | "after_agent";
+    createdAt: string;
+};
+export type DirectWorkspaceSetupStatus = {
+    status: "not_requested" | "waiting" | "running" | "succeeded" | "failed";
+    exitCode: number | null;
+    startedAt: string | null;
+    finishedAt: string | null;
+    log: string | null;
+};
+export type DirectWorkspaceSetupWaitOptions = {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+};
+export type DirectProviderWorkspaceInput = DirectWorkspaceCreateInput & {
+    id: string;
+    lifecycle: DirectWorkspaceLifecycle;
+    password: string;
+    provisioning: DirectProvisioningPlan;
+};
+export type DirectAgentFile = {
+    path: string;
+    contentBase64: string;
+    mode?: number;
+};
+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;
+    };
+    setup: {
+        beforeAgent: string[];
+        afterAgent: 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/index.js

@@ -236,7 +236,7 @@ async function runWithServer(serverUrl, operation) {
           cause: error
         });
       }
-      throw new GittermError(code, code === "UNAUTHORIZED" ? "Not logged in or token expired. Run: gitterm login" : 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 });
   }
@@ -525,16 +525,16 @@ function createGittermWorkspaceClient(options = {}) {
   };
 }
 export {
-  saveConfig,
-  loginWithDeviceCode,
-  loadConfigSync,
-  loadConfig,
-  getWorkspaceEnvironment,
-  getConfigPath,
-  deleteConfig,
-  createGittermWorkspaceClient,
-  createGittermClient,
-  WorkspaceLifecycleError,
+  DEFAULT_GITTERM_SERVER_URL,
   GittermError,
-  DEFAULT_GITTERM_SERVER_URL
+  WorkspaceLifecycleError,
+  createGittermClient,
+  createGittermWorkspaceClient,
+  deleteConfig,
+  getConfigPath,
+  getWorkspaceEnvironment,
+  loadConfig,
+  loadConfigSync,
+  loginWithDeviceCode,
+  saveConfig
 };

package/dist/types.d.ts

@@ -180,12 +180,25 @@ 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
-     * and logs through workspaces.setupStatus()/waitForSetup().
+     * Setup phases run in order. `beforeAgent` blocks agent startup and fails
+     * create() when it exits non-zero; `afterAgent` starts after the agent is
+     * reachable and is observable with setupStatus()/waitForSetup().
      */
-    setupCommands?: string[];
+    setup?: {
+        beforeAgent?: string[];
+        afterAgent?: string[];
+    };
+    /** Secret files written relative to the repository and excluded from git. Rotate by recreating the workspace. */
+    secretFiles?: Array<{
+        path: string;
+        content: string;
+        mode?: "0400" | "0600";
+    }>;
+    /** Trusted integration context appended to the workspace's global AGENTS.md. */
+    additionalAgentInstructions?: string;
     /** OpenCode capabilities materialized only in this workspace. */
     opencode?: {
         skills?: Array<{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitterm/sdk",
-  "version": "0.0.8",
+  "version": "0.1.1",
   "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"
   }
 }