@gitterm/sdk 0.0.8 → 0.1.1

package/README.md

@@ -4,6 +4,152 @@ TypeScript SDK for the [GitTerm](https://gitterm.dev) API. Used by the `gitterm`
 the OpenCode plugin, and any integration that needs to manage GitTerm workspaces with
 a user API token.
 
+## Direct provider mode
+
+Direct mode runs an agent using your cloud-provider account without a Gitterm server. It intentionally omits managed billing, proxying, policy, durable run history, and automatic cleanup; your application owns workspace state and lifecycle.
+
+All built-in compute providers use the same provisioning plan and workspace/run API:
+
+| Provider | Direct prerequisite                                            | Persistent pause | Keep-alive |
+| -------- | -------------------------------------------------------------- | ---------------- | ---------- |
+| E2B      | OpenCode-compatible template                                   | Yes              | Yes        |
+| Daytona  | Public Gitterm OpenCode server image by default                | Yes              | Yes        |
+| Vercel   | Vercel Sandbox project                                         | Yes              | Yes        |
+| Ascii    | Box API key                                                    | Yes              | Yes        |
+| exe.dev  | Lifecycle token, or an existing VM with `ls,ssh,share,ssh-key` | Yes              | No         |
+| Railway  | Project/environment and public service domains                 | With a volume    | No         |
+
+AWS remains available through `createGittermClient()` and the Gitterm control plane; it is intentionally not exposed in direct mode.
+
+Cloudflare remains available through the Gitterm control plane. Direct Cloudflare support is deferred until the OpenCode v2 Workerd runtime is stable.
+
+```ts
+import { createDirectGittermClient } from "@gitterm/sdk/direct";
+
+const direct = createDirectGittermClient({
+  provider: {
+    type: "e2b",
+    apiKey: process.env.E2B_API_KEY!,
+    size: "standard",
+  },
+});
+
+let workspace = await direct.workspaces.create({
+  repo: "https://github.com/acme/project",
+  lifecycle: "ephemeral",
+  modelCredentials: [{ providerName: "anthropic", apiKey: process.env.ANTHROPIC_API_KEY! }],
+});
+
+try {
+  const run = await direct.runs.create({ workspace, prompt: "Review the open pull request" });
+  const completed = await direct.runs.wait(run, workspace);
+  console.log(completed.finalText);
+} finally {
+  workspace = await direct.workspaces.terminate(workspace);
+}
+```
+
+`DirectWorkspace` is JSON-serializable. Persist it together with the returned `sessionId` to resume provider lifecycle and OpenCode conversation context after an application restart. The serialized workspace contains the OpenCode password and may contain provider routing tokens, so encrypt it as credential material. Custom providers can implement `DirectProviderAdapter`; use `client.provider.capabilities` rather than hard-coding lifecycle assumptions.
+
+Every adapter receives the same normalized plan: repository/ref and optional Git credentials, agent files, model credentials, environment, setup commands, serve command, and port. Provider-specific configuration only describes how to allocate and expose compute.
+
+Direct setup has explicit phases. `beforeAgent` blocks workspace creation, while
+`afterAgent` runs in the background and can be observed with `setupStatus()` or
+`waitForSetup()`:
+
+```ts
+const workspace = await direct.workspaces.create({
+  repo: "https://github.com/acme/project",
+  setup: {
+    beforeAgent: ["npm install"],
+    afterAgent: ["npm run generate"],
+  },
+  secretFiles: [
+    {
+      path: "~/.config/gcloud/service-account.json",
+      content: process.env.GCP_SERVICE_ACCOUNT_JSON!,
+      mode: 0o600,
+    },
+  ],
+});
+
+await direct.workspaces.waitForSetup(workspace);
+```
+
+To attach to an existing exe.dev VM without giving Gitterm ownership of that VM, pass
+`exedev: { existingVmName: "acme-agent-machine" }` to `workspaces.create()`. Terminating
+that workspace stops only its tracked agent process and does not remove the VM.
+
+Trusted integration context can be appended to the generated global `AGENTS.md` without changing the model system prompt:
+
+```ts
+await direct.workspaces.create({
+  repo: "https://github.com/acme/project",
+  additionalAgentInstructions:
+    "You are running as a Slack bot. Keep responses concise and suitable for a thread.",
+});
+```
+
+### Provider authentication
+
+Direct workspaces can start OpenCode provider authentication without shell access. Discover the provider's methods and select a headless or device-code OAuth method when OpenCode is running remotely:
+
+```ts
+const openai = await direct.auth.get(workspace, "openai");
+const method = openai.methods.find(
+  (item) => item.type === "oauth" && item.id === "chatgpt-headless",
+);
+if (!method || method.type !== "oauth") throw new Error("OpenAI device OAuth is unavailable");
+
+const attempt = await direct.auth.connectOAuth({
+  workspace,
+  integrationId: "openai",
+  methodId: method.id,
+  label: "Slack bot",
+});
+
+// Present these through your application UI.
+console.log(attempt.url, attempt.instructions);
+
+if (attempt.mode === "auto") {
+  await direct.auth.wait(attempt, workspace);
+} else {
+  await direct.auth.complete(attempt, workspace, await getCodeFromUser());
+}
+```
+
+OAuth started this way is stored and refreshed by OpenCode inside the workspace. Reusing a persistent workspace avoids repeated authentication; terminating an ephemeral workspace also destroys its credential store. OpenCode does not export OAuth tokens from this flow.
+
+Applications that own OAuth separately can keep the token bundle in encrypted storage and inject it into every new workspace instead:
+
+```ts
+const credential = await credentialStore.get(slackInstallationId);
+const workspace = await direct.workspaces.create({
+  lifecycle: "ephemeral",
+  modelCredentials: [
+    {
+      type: "oauth",
+      providerName: "openai",
+      refreshToken: credential.refreshToken,
+      accessToken: credential.accessToken,
+      expiresAt: credential.expiresAt,
+      accountId: credential.accountId,
+    },
+  ],
+});
+
+// Credentials can also be added or rotated on an existing runtime.
+await direct.auth.setCredential(workspace, {
+  type: "oauth",
+  providerName: "openai",
+  refreshToken: credential.refreshToken,
+  accessToken: credential.accessToken,
+  expiresAt: credential.expiresAt,
+});
+```
+
+In this mode the application owns encryption, tenant scoping, refresh, and persistence. OpenCode may refresh its workspace-local copy; the direct SDK does not copy rotated tokens back into application storage. Use the Gitterm control plane when those credential-management responsibilities should be managed centrally.
+
 ## Install
 
 ```sh
@@ -128,7 +274,10 @@ Override only the placement decisions your integration cares about:
 await client.workspaces.create({
   repo: "https://github.com/acme/product",
   agent: "opencode",
-  setupCommands: ["npm install", "npm run generate"],
+  setup: {
+    beforeAgent: ["npm install"],
+    afterAgent: ["npm run generate"],
+  },
   opencode: {
     skills: [
       {
@@ -150,12 +299,38 @@ Follow the repository's release-demo workflow.`,
 });
 ```
 
-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.
+Setup commands run in order from the checked-out repository. `beforeAgent` blocks agent
+startup; when it fails, `create()` rejects with the tail of its log. `afterAgent` starts
+after the agent is reachable and reports status independently. Provider and agent defaults
+configured by an administrator run first. Use `client.workspaces.setupStatus(workspaceId)`
+or `waitForSetup(workspaceId)` to inspect the `afterAgent` phase. GitTerm persists bounded
+logs and a recovery copy in the repository's git-excluded `.gitterm/setup/` directory.
+Setup commands can reference the checkout with `$WORKSPACE_REPO_DIR`, which is the same on
+every provider even though the underlying path differs.
+
+Secret files are created relative to the repository with restrictive permissions and are
+added to `.git/info/exclude` so the agent cannot commit them. GitTerm does not retain their
+contents; to rotate a secret, recreate the workspace. Like model credentials, they are
+delivered to the sandbox through its launch environment, so anyone who can read the
+provider's task or container definition can read them:
+
+```ts
+await client.workspaces.create({
+  repo: "https://github.com/acme/product",
+  secretFiles: [
+    {
+      path: ".secrets/gcp.json",
+      content: process.env.GCP_SERVICE_ACCOUNT_JSON!,
+      mode: "0600",
+    },
+  ],
+  setup: {
+    beforeAgent: [
+      'gcloud auth activate-service-account --key-file "$WORKSPACE_REPO_DIR/.secrets/gcp.json"',
+    ],
+  },
+});
+```
 
 `provider` is a discriminated union, so TypeScript only offers `region` for providers
 where GitTerm supports caller-selected placement. Machine keys are configured by admins
@@ -177,7 +352,7 @@ it does not claim that a pull request, upload, or other product outcome succeede
 ```ts
 const { workspace } = await client.workspaces.create({
   repo: "https://github.com/acme/product",
-  setupCommands: ["npm install", "npm run db:seed"],
+  setup: { afterAgent: ["npm install", "npm run db:seed"] },
 });
 
 const run = await client.runs.create({

package/dist/direct/ascii.d.ts

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

package/dist/direct/client.d.ts

@@ -0,0 +1,60 @@
+import type { DirectProviderAdapter, DirectProviderConfig, DirectAuthAttempt, DirectAuthAttemptStatus, DirectAuthIntegration, DirectAuthWaitOptions, DirectModelCredential, DirectRun, DirectRunCreateInput, DirectRunMessage, DirectRunWaitOptions, DirectWorkspace, DirectWorkspaceCreateInput, DirectWorkspaceSetupStatus, DirectWorkspaceSetupWaitOptions } from "./types.js";
+export type DirectGittermClientOptions = {
+    provider: DirectProviderAdapter | DirectProviderConfig;
+};
+export declare function createDirectGittermClient(options: DirectGittermClientOptions): {
+    provider: {
+        name: string;
+        capabilities: import("./types.js").DirectProviderCapabilities;
+    };
+    auth: {
+        setCredential(workspace: DirectWorkspace, credential: DirectModelCredential): Promise<void>;
+        list(workspace: DirectWorkspace): Promise<DirectAuthIntegration[]>;
+        get(workspace: DirectWorkspace, integrationId: string): Promise<DirectAuthIntegration>;
+        connectKey(input: {
+            workspace: DirectWorkspace;
+            integrationId: string;
+            key: string;
+            label?: string;
+        }): Promise<void>;
+        connectOAuth(input: {
+            workspace: DirectWorkspace;
+            integrationId: string;
+            methodId: string;
+            inputs?: Record<string, string>;
+            label?: string;
+        }): Promise<DirectAuthAttempt>;
+        status(attempt: DirectAuthAttempt, workspace: DirectWorkspace): Promise<DirectAuthAttemptStatus>;
+        complete(attempt: DirectAuthAttempt, workspace: DirectWorkspace, code: string): Promise<void>;
+        wait(attempt: DirectAuthAttempt, workspace: DirectWorkspace, wait?: DirectAuthWaitOptions): Promise<DirectAuthAttemptStatus>;
+        cancel(attempt: DirectAuthAttempt, workspace: DirectWorkspace): Promise<void>;
+    };
+    workspaces: {
+        create(input?: DirectWorkspaceCreateInput): Promise<DirectWorkspace>;
+        status(workspace: DirectWorkspace): Promise<DirectWorkspace>;
+        pause(workspace: DirectWorkspace): Promise<DirectWorkspace>;
+        resume(workspace: DirectWorkspace): Promise<DirectWorkspace>;
+        terminate(workspace: DirectWorkspace): Promise<DirectWorkspace>;
+        keepAlive(workspace: DirectWorkspace, timeoutMs: number): Promise<void>;
+        setupStatus: (workspace: DirectWorkspace) => Promise<DirectWorkspaceSetupStatus>;
+        waitForSetup(workspace: DirectWorkspace, wait?: DirectWorkspaceSetupWaitOptions): Promise<DirectWorkspaceSetupStatus>;
+    };
+    runs: {
+        create(input: DirectRunCreateInput): Promise<DirectRun>;
+        get: (run: DirectRun, workspace: DirectWorkspace) => Promise<{
+            status: "running" | "completed" | "failed" | "cancelled" | "retrying";
+            error: string | null;
+            finalText: string | null;
+            id: string;
+            workspaceId: string;
+            sessionId: string;
+            messageId: string;
+            title: string;
+            submittedAt: string;
+        }>;
+        wait(run: DirectRun, workspace: DirectWorkspace, wait?: DirectRunWaitOptions): Promise<DirectRun>;
+        messages(run: DirectRun, workspace: DirectWorkspace): Promise<DirectRunMessage[]>;
+        cancel(run: DirectRun, workspace: DirectWorkspace): Promise<boolean>;
+    };
+};
+export type DirectGittermClient = ReturnType<typeof createDirectGittermClient>;

package/dist/direct/daytona.d.ts

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

package/dist/direct/e2b.d.ts

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

package/dist/direct/exedev.d.ts

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

package/dist/direct/index.d.ts

@@ -0,0 +1,8 @@
+export { createDirectGittermClient, type DirectGittermClient, type DirectGittermClientOptions, } from "./client.js";
+export { createE2BDirectProvider } from "./e2b.js";
+export { createAsciiDirectProvider } from "./ascii.js";
+export { createDaytonaDirectProvider } from "./daytona.js";
+export { createExeDevDirectProvider } from "./exedev.js";
+export { createRailwayDirectProvider } from "./railway.js";
+export { createVercelDirectProvider } from "./vercel.js";
+export type { AsciiDirectProviderConfig, DirectAuthAttempt, DirectAuthAttemptStatus, DirectAuthIntegration, DirectAuthMethod, DirectAuthPrompt, DirectAuthWaitOptions, DirectApiModelCredential, DaytonaDirectProviderConfig, DirectModelCredential, DirectOAuthModelCredential, DirectProviderAdapter, DirectProviderCapabilities, DirectProviderConfig, DirectProviderWorkspaceInput, DirectRun, DirectRunCreateInput, DirectRunMessage, DirectRunWaitOptions, DirectSecretFile, DirectWorkspace, DirectWorkspaceCreateInput, DirectWorkspaceLifecycle, DirectWorkspaceRuntime, DirectWorkspaceSetup, DirectWorkspaceSetupStatus, DirectWorkspaceSetupWaitOptions, E2BDirectProviderConfig, ExeDevDirectProviderConfig, RailwayDirectProviderConfig, VercelDirectProviderConfig, } from "./types.js";