@gitterm/sdk 0.0.8 → 0.1.0

package/README.md

@@ -4,6 +4,115 @@ 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  | Token with `new,ls,ssh,share,ssh-key,pause,resume,rm`; public OpenCode image by default | 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.
+
+### 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

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,58 @@
+import type { DirectProviderAdapter, DirectProviderConfig, DirectAuthAttempt, DirectAuthAttemptStatus, DirectAuthIntegration, DirectAuthWaitOptions, DirectModelCredential, DirectRun, DirectRunCreateInput, DirectRunMessage, DirectRunWaitOptions, DirectWorkspace, DirectWorkspaceCreateInput } 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>;
+    };
+    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, DirectWorkspace, DirectWorkspaceCreateInput, DirectWorkspaceLifecycle, DirectWorkspaceRuntime, E2BDirectProviderConfig, ExeDevDirectProviderConfig, RailwayDirectProviderConfig, VercelDirectProviderConfig, } from "./types.js";