@gitterm/sdk 0.2.2 → 0.4.0

package/README.md

@@ -23,10 +23,12 @@ Create a workspace, run a prompt, and get the final result:
 import { createGittermClient } from "@gitterm/sdk";
 
 const client = createGittermClient({ token: process.env.GITTERM_API_TOKEN });
+const [github] = await client.integrations.github.list();
+if (!github) throw new Error("Connect GitHub in the Gitterm dashboard first");
 
 const { workspace } = await client.workspaces.create({
   repo: "https://github.com/acme/product",
-  repositoryCredentials: { token: process.env.GITHUB_TOKEN! },
+  gitIntegrationId: github.id,
   autoTerminateAfterMs: 2 * 60 * 60 * 1000,
 });
 
@@ -43,6 +45,22 @@ try {
 }
 ```
 
+Connected cloud identities are discoverable without returning credentials:
+
+```ts
+const [github] = await client.integrations.github.list();
+const [googleCloud] = await client.integrations.googleCloud.list();
+
+await client.workspaces.create({
+  repo: "https://github.com/acme/product",
+  gitIntegrationId: github.id,
+  googleCloudIntegrationId: googleCloud.id,
+});
+```
+
+GitHub tokens and Google workload credentials are issued inside the workspace; the SDK caller does
+not receive or forward them.
+
 `result()` returns only on successful completion. If the agent asks something and no handler is
 registered, it throws `AgentRunError` with code `INPUT_REQUIRED` and the current `error.run`.
 Register `onPermission` / `onQuestion` handlers for interactive runs, or use the event relay below.
@@ -194,6 +212,44 @@ as pull and push. Without inline credentials, `gitIntegrationId` continues to us
 dashboard integration. Omitting `models` likewise continues to
 use dashboard-managed model credentials.
 
+#### GitHub CLI authentication
+
+For GitHub repositories, GitTerm configures both Git and `gh` from the same workspace
+credentials. Agents can run commands such as `gh pr list` or `gh pr create` without
+running `gh auth login`:
+
+- `repositoryCredentials.token` takes precedence over `gitIntegrationId`. The supplied
+  token is retained in a permission-restricted file on the workspace machine and is
+  not automatically renewed. This also works with the standalone SDK's direct providers.
+- `gitIntegrationId` uses the GitHub App installation token. Git and `gh` share a
+  cached token and refresh it through GitTerm before expiry. Concurrent commands share
+  the refresh, and a failed refresh stops the command rather than using an expired token.
+- Without repository credentials or an integration, GitTerm leaves CLI authentication
+  to the environment or the CLI's existing configuration.
+
+GitTerm supplies `GH_TOKEN` only to the invoked CLI process, so there is no stale
+installation token exported into the agent's long-running environment. Explicit
+`GH_TOKEN` or `GITHUB_TOKEN` environment variables override this CLI authentication;
+they do not change the credentials used by Git. Managed credentials are for `github.com`.
+
+The generated `AGENTS.md` tells agents that `$HOME/.gitterm/bin/gh` indicates GitTerm
+authentication was provisioned. Agents install the real CLI separately when needed, keep
+the GitTerm launcher first on `PATH`, and use the normal `gh` command. `$GH_TOKEN` is
+intentionally not exported globally, and agents are instructed not to pipe it into
+`gh auth login`.
+CLI installation is left to the image or the agent as needed for the task; there is no SDK
+installation option. The guidance explains checking `gh --version` and installing the CLI
+if needed. The launcher discovers the
+actual binary on each invocation, including installations made after startup.
+It lives in `~/.gitterm/bin`, which GitTerm adds to the agent's PATH and standard shell
+profiles. Install the actual CLI elsewhere and keep `~/.gitterm/bin` first on PATH so it
+does not overwrite or bypass the launcher. Node.js and Git are required by the
+authentication runtime.
+
+Available commands depend on the token's repository access and permissions. Installation
+tokens act as the GitHub App bot; user-scoped commands may require user authentication.
+Updating an integration's token does not grant permissions absent from its installation.
+
 GitTerm does not save inline PATs in its application database. Inline PATs must be delivered to the
 selected compute provider and retained on the workspace machine for runtime Git operations, so
 provider infrastructure and processes running in that workspace may be able to access them. Prefer
@@ -394,7 +450,10 @@ Three things have to be true before a prompt can be delivered, and the SDK handl
 The shortest correct sequence is therefore:
 
 ```ts
-const { workspace } = await client.workspaces.create({ repo, setup: { afterAgent: ["npm ci"] } });
+const { workspace } = await client.workspaces.create({
+  repo,
+  setup: { afterAgent: ["npm ci"] },
+});
 const run = await client.runs.create({
   workspace,
   idempotencyKey: `review-${sha}`,
@@ -626,11 +685,10 @@ would otherwise change them for other runs on the same runtime.
 
 ## OpenCode API versions
 
-Managed workspaces continue to run `opencode-ai@latest` (`opencodeApi: "v1"`). OpenCode 2
-changes the server API; callers testing it must supply their own compatible image and create the
-workspace with `opencode: { api: "v2" }`. Runs, questions, permissions, and events behave the
-same from the SDK's point of view; the flag only tells GitTerm which protocol to speak to the
-workspace. `v2` is experimental until OpenCode 2 ships.
+Managed workspaces default to OpenCode V1 from `opencode-ai` and use `opencodeApi: "v1"`.
+Credentials are written to OpenCode's `auth.json` before the runtime starts. Runs, questions,
+permissions, and events use GitTerm's V1 runtime adapter. V2 remains selectable only for explicitly
+compatible images.
 
 ## Errors
 
@@ -729,12 +787,17 @@ let workspace = await direct.workspaces.create({
   repo: "https://github.com/acme/project",
   lifecycle: "ephemeral",
   models: {
-    providers: { anthropic: { source: "apiKey", apiKey: process.env.ANTHROPIC_API_KEY! } },
+    providers: {
+      anthropic: { source: "apiKey", apiKey: process.env.ANTHROPIC_API_KEY! },
+    },
   },
 });
 
 try {
-  const run = await direct.runs.create({ workspace, prompt: "Review the open pull request" });
+  const run = await direct.runs.create({
+    workspace,
+    prompt: "Review the open pull request",
+  });
   const completed = await direct.runs.result(run);
   console.log(completed.finalText);
 } finally {

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { AgentType, AgentRun, AgentRunCreateInput, AgentRunListOptions, AgentRunListResult, AgentRunMessage, AgentRunReply, AuthStatus, CloudProvider, RunRef, RunWaitOptions, RunWatchOptions, WaitOptions, Workspace, WorkspaceCreateInput, WorkspaceCreateResult, WorkspaceEnsureRunningResult, WorkspaceListOptions, WorkspaceListResult, WorkspaceRef, WorkspaceRestartResult, WorkspaceRuntimeAccess, WorkspacePauseResult, WorkspaceTerminateResult, WorkspaceCatalog, WorkspaceSetupStatus, ModelCredential, ModelProviderInfo } from "./types.js";
+import type { AgentType, AgentRun, AgentRunCreateInput, AgentRunListOptions, AgentRunListResult, AgentRunMessage, AgentRunReply, AuthStatus, CloudProvider, RunRef, RunWaitOptions, RunWatchOptions, WaitOptions, Workspace, WorkspaceCreateInput, WorkspaceCreateResult, WorkspaceEnsureRunningResult, WorkspaceListOptions, WorkspaceListResult, WorkspaceRef, WorkspaceRestartResult, WorkspaceRuntimeAccess, WorkspacePauseResult, WorkspaceTerminateResult, WorkspaceCatalog, WorkspaceSetupStatus, ModelCredential, ModelProviderInfo, GitHubIntegration, GoogleCloudIntegration } from "./types.js";
 import type { AgentRunEvent, AgentRunResult, RunResultOptions, ModelInfo, WorkspaceModelAccess } from "./types.js";
 export type GittermClientOptions = {
     serverUrl?: string;
@@ -69,6 +69,14 @@ export type GittermClient = {
         list(): Promise<ModelCredential[]>;
         listProviders(): Promise<ModelProviderInfo[]>;
     };
+    integrations: {
+        github: {
+            list(): Promise<GitHubIntegration[]>;
+        };
+        googleCloud: {
+            list(): Promise<GoogleCloudIntegration[]>;
+        };
+    };
     models: {
         list(options?: {
             provider?: string;

package/dist/direct/index.js

@@ -1273,6 +1273,243 @@ import {
 // src/direct/ascii.ts
 import { BoxApi, Configuration, waitUntilReady } from "@asciidev/box-sdk";
 
+// ../agent-runtime/src/github-auth.ts
+var GITHUB_AUTH_PATH = 'export PATH="$HOME/.gitterm/bin:$PATH"';
+var GITHUB_CLI_INSTRUCTIONS = `GitHub CLI authentication:
+- The user may have supplied repository credentials or selected a GitHub integration for this workspace. GitTerm authentication is configured only when $HOME/.gitterm/bin/gh exists. Check for that executable, but never read or print files under $HOME/.gitterm/github.
+- The image may not include the real GitHub CLI. Run gh --version. If the GitTerm launcher says the CLI is missing, install the official gh binary using the image's package manager or in another directory.
+- Keep $HOME/.gitterm/bin first on PATH after installation. For a downloaded CLI, use: export PATH="$HOME/.gitterm/bin:/path/to/installed/gh/bin:$PATH". Never prepend the real CLI ahead of $HOME/.gitterm/bin and never overwrite $HOME/.gitterm/bin/gh.
+- With the launcher first, use the normal gh command (for example, gh pr create). The launcher supplies the user-provided token or a fresh integration token only to that operation.
+- Never run gh auth login, pipe $GH_TOKEN, copy tokens, or use gh auth status for this workspace authentication. $GH_TOKEN is intentionally not exported to the agent shell.
+- If $HOME/.gitterm/bin/gh is absent, tell the user that this workspace has no GitTerm-provided GitHub credentials. If an authenticated operation is denied, report the denied operation and ask for repository access or the required GitHub App/token permission.`;
+function githubAuthCommand(command) {
+  return `env PATH="$HOME/.gitterm/bin:$PATH" sh -c '${command.replaceAll("'", `'"'"'`)}'`;
+}
+function hasGithubAuth(repo) {
+  return Boolean(repo?.authToken && /^(https:\/\/github\.com\/|git@github\.com:|ssh:\/\/git@github\.com\/)/i.test(repo.url));
+}
+function githubAuthProvisioning(repo) {
+  if (!hasGithubAuth(repo)) {
+    return;
+  }
+  const config = {
+    username: repo.authUsername ?? "x-access-token",
+    renewable: !repo.inlineAuth,
+    expiresAt: repo.authExpiresAt
+  };
+  return {
+    files: [
+      {
+        path: "~/.gitterm/github/runtime.cjs",
+        contentBase64: Buffer.from(GITHUB_AUTH_RUNTIME).toString("base64"),
+        mode: 384
+      },
+      {
+        path: "~/.gitterm/github/config.json",
+        contentBase64: Buffer.from(JSON.stringify(config)).toString("base64"),
+        mode: 384
+      },
+      {
+        path: "/run/gitterm/github/credential.json",
+        contentBase64: Buffer.from(JSON.stringify({
+          token: repo.authToken,
+          username: repo.authUsername ?? "x-access-token",
+          expiresAt: repo.authExpiresAt
+        })).toString("base64"),
+        mode: 384
+      }
+    ],
+    setup: `node "$HOME/.gitterm/github/runtime.cjs" setup || exit $?
+${GITHUB_AUTH_PATH}`
+  };
+}
+var GITHUB_AUTH_RUNTIME = String.raw`
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+const cp = require("node:child_process");
+const { randomUUID } = require("node:crypto");
+const directory = path.join(os.homedir(), ".gitterm/github");
+const runtimeDirectory = path.join(process.env.GITTERM_RUNTIME_DIR || "/run/gitterm", "github");
+const bin = path.join(os.homedir(), ".gitterm/bin");
+const configFile = path.join(directory, "config.json");
+const credentialFile = path.join(runtimeDirectory, "credential.json");
+const cacheFile = path.join(runtimeDirectory, "cache.json");
+const read = (file) => JSON.parse(fs.readFileSync(file, "utf8"));
+const valid = (value) => typeof value === "string" && value.length > 0 && !/[\r\n\0]/.test(value);
+const fresh = (value) => valid(value?.token) && Date.parse(value.expiresAt) > Date.now() + 300000;
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function atomicWrite(file, value) {
+  const temporary = file + "." + randomUUID();
+  try {
+    fs.writeFileSync(temporary, JSON.stringify(value), { mode: 0o600, flag: "wx" });
+    fs.renameSync(temporary, file);
+  } finally {
+    fs.rmSync(temporary, { force: true });
+  }
+}
+
+async function credential() {
+  const config = read(configFile);
+  const initial = read(credentialFile);
+  if (!config.renewable) {
+    if (!valid(initial.token) || !valid(initial.username)) throw new Error("invalid credential");
+    return initial;
+  }
+  const cached = () => {
+    try { const value = read(cacheFile); if (fresh(value)) return value; } catch {}
+    if (fresh(initial)) return initial;
+  };
+  let value = cached();
+  if (value) return value;
+  const lock = path.join(runtimeDirectory, "refresh.lock");
+  const deadline = Date.now() + 15000;
+  while (true) {
+    try { fs.mkdirSync(lock, { mode: 0o700 }); break; }
+    catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      try {
+        if (Date.now() - fs.statSync(lock).mtimeMs > 30000) fs.rmdirSync(lock);
+      } catch {}
+      if (Date.now() > deadline) throw new Error("refresh busy");
+      await delay(100);
+      value = cached();
+      if (value) return value;
+    }
+  }
+  try {
+    value = cached();
+    if (value) return value;
+    const url = process.env.WORKSPACE_API_URL;
+    const auth = process.env.WORKSPACE_AGENT_AUTH_TOKEN;
+    if (!url || !auth) throw new Error("refresh unavailable");
+    const response = await fetch(url.replace(/\/$/, "") + "/workspaceOps.gitCredential", {
+      method: "POST",
+      headers: { Authorization: "Bearer " + auth, "Content-Type": "application/json" },
+      body: "{}",
+      redirect: "error",
+      signal: AbortSignal.timeout(10000),
+    });
+    if (!response.ok) throw new Error("refresh failed");
+    const body = await response.json();
+    const data = body.result?.data?.json ?? body.result?.data;
+    if (!fresh(data)) throw new Error("invalid credential");
+    value = { token: data.token, expiresAt: data.expiresAt, username: "x-access-token" };
+    atomicWrite(cacheFile, value);
+    return value;
+  } finally { fs.rmdirSync(lock); }
+}
+
+function setup() {
+  fs.mkdirSync(bin, { recursive: true, mode: 0o700 });
+  fs.mkdirSync(runtimeDirectory, { recursive: true, mode: 0o700 });
+  fs.chmodSync(directory, 0o700);
+  fs.chmodSync(runtimeDirectory, 0o700);
+  fs.chmodSync(configFile, 0o600);
+  fs.chmodSync(credentialFile, 0o600);
+  for (const [name, mode] of [["gh", "gh"], ["git-credential-gitterm", "credential"]]) {
+    const file = path.join(bin, name);
+    fs.writeFileSync(file, '#!/bin/sh\nexec node "$HOME/.gitterm/github/runtime.cjs" ' + mode + ' "$@"\n', { mode: 0o700 });
+    fs.chmodSync(file, 0o700);
+  }
+  // Reset only GitHub's helper chain. Other hosts retain their own credentials.
+  // Retire our clone-time helpers, which predate host-scoped runtime auth.
+  let helpers = [];
+  try { helpers = cp.execFileSync("git", ["config", "--global", "--get-all", "credential.helper"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim().split("\n"); } catch {}
+  for (const helper of helpers) {
+    if (["/usr/local/bin/gitterm-git-credential", "/run/gitterm/git-credential-helper.sh", "/tmp/gitterm-repository-auth/git-credential-helper.sh", "/workspace/.git-credential-helper.sh"].includes(helper) || helper.includes('password=$GITHUB_APP_TOKEN')) {
+      cp.execFileSync("git", ["config", "--global", "--fixed-value", "--unset-all", "credential.helper", helper]);
+    }
+  }
+  const key = "credential.https://github.com.helper";
+  cp.execFileSync("git", ["config", "--global", "--replace-all", key, ""]);
+  cp.execFileSync("git", ["config", "--global", "--add", key, '!node "$HOME/.gitterm/github/runtime.cjs" credential']);
+  // Login shells and interactive agent shells may reset PATH. No secrets in profiles.
+  const line = 'export PATH="$HOME/.gitterm/bin:$PATH" # gitterm-github-cli';
+  for (const name of [".profile", ".bashrc", ".zshrc"]) {
+    const file = path.join(os.homedir(), name);
+    const text = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+    if (!text.includes(line)) fs.appendFileSync(file, "\n" + line + "\n", { mode: 0o600 });
+  }
+}
+
+function githubTarget(args) {
+  let host = process.env.GH_HOST;
+  let repo = process.env.GH_REPO;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--hostname") host = args[++i];
+    else if (args[i].startsWith("--hostname=")) host = args[i].slice(11);
+    else if (args[i] === "--repo" || args[i] === "-R") repo = args[++i];
+    else if (args[i].startsWith("--repo=")) repo = args[i].slice(7);
+    else if (args[i].startsWith("-R") && args[i].length > 2) repo = args[i].slice(2);
+  }
+  if (host && host.toLowerCase() !== "github.com") return false;
+  if (repo && !/^(https:\/\/github\.com\/|github\.com\/)?[^/]+\/[^/]+\/?$/.test(repo)) return false;
+  if (args.some((arg) => /^https?:\/\//.test(arg) && !/^https:\/\/(api\.)?github\.com\//.test(arg))) return false;
+  if (!host && !repo) {
+    try {
+      const origin = cp.execFileSync("git", ["remote", "get-url", "origin"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+      if (!/^(https:\/\/github\.com\/|git@github\.com:|ssh:\/\/git@github\.com\/)/i.test(origin)) return false;
+    } catch {}
+  }
+  return true;
+}
+
+async function main() {
+  const [mode, ...args] = process.argv.slice(2);
+  if (mode === "setup") return setup();
+  if (mode === "credential") {
+    if (args[0] !== "get") return;
+    const input = fs.readFileSync(0, "utf8");
+    const fields = Object.fromEntries(input.trim().split("\n").map((line) => { const i = line.indexOf("="); return [line.slice(0, i), line.slice(i + 1)]; }));
+    if (fields.protocol !== "https" || fields.host !== "github.com") return;
+    const value = await credential();
+    process.stdout.write("username=" + (value.username ?? "x-access-token") + "\npassword=" + value.token + "\n");
+    return;
+  }
+  if (mode !== "gh") throw new Error("invalid mode");
+  // Find the actual binary on every invocation, including installations made later.
+  const wrapper = fs.realpathSync(path.join(bin, "gh"));
+  let executable;
+  for (const entry of (process.env.PATH ?? "").split(path.delimiter)) {
+    if (!entry) continue;
+    const candidate = path.resolve(entry, "gh");
+    try {
+      if (fs.statSync(candidate).isFile() && fs.realpathSync(candidate) !== wrapper) {
+        fs.accessSync(candidate, fs.constants.X_OK); executable = candidate; break;
+      }
+    } catch {}
+  }
+  if (!executable) {
+    console.error("GitHub CLI is not installed in this image. Install gh, then retry.");
+    process.exitCode = 127;
+    return;
+  }
+  const env = { ...process.env };
+  if (!env.GH_TOKEN && !env.GITHUB_TOKEN && args.length && githubTarget(args) && !args.some((arg) => ["--help", "--version"].includes(arg)) && args[0] !== "help") {
+    env.GH_TOKEN = (await credential()).token;
+  }
+  const child = cp.spawn(executable, args, { env, stdio: "inherit" });
+  const handlers = new Map();
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+    const handler = () => child.kill(signal);
+    handlers.set(signal, handler);
+    process.on(signal, handler);
+  }
+  child.on("error", () => { console.error("Could not start GitHub CLI."); process.exitCode = 127; });
+  child.on("exit", (code, signal) => {
+    for (const [name, handler] of handlers) process.removeListener(name, handler);
+    if (signal) process.kill(process.pid, signal);
+    else process.exitCode = code ?? 1;
+  });
+}
+main().catch(() => {
+  console.error("GitTerm GitHub authentication failed; check the workspace credentials or integration.");
+  process.exitCode = 1;
+});
+`;
+
 // src/direct/provisioning.ts
 var DIRECT_OPENCODE_PORT = 4096;
 var DIRECT_OPENCODE_COMMAND = `opencode serve --hostname 0.0.0.0 --port ${DIRECT_OPENCODE_PORT}`;
@@ -1281,7 +1518,9 @@ var DIRECT_E2B_TEMPLATES = {
   standard: "gitterm-opencode-server",
   large: "gitterm-opencode-server-lg"
 };
-var DIRECT_GITTERM_INSTRUCTIONS = "You are running in a direct Gitterm workspace. Follow the user's instructions and verify outcomes before reporting success.";
+var DIRECT_GITTERM_INSTRUCTIONS = `You are running in a direct Gitterm workspace. Follow the user's instructions and verify outcomes before reporting success.
+
+${GITHUB_CLI_INSTRUCTIONS}`;
 var MAX_ADDITIONAL_AGENT_INSTRUCTIONS = 50000;
 function resolveDirectImage(image) {
   return image?.trim() || DIRECT_OPENCODE_SERVER_IMAGE;
@@ -1372,7 +1611,10 @@ function buildDirectProvisioningPlan(input) {
     throw new GittermError("MODEL_CREDENTIAL_INVALID", "Direct mode cannot inherit dashboard credentials");
   }
   for (const [key, source] of Object.entries(input.models?.providers ?? {})) {
-    const credential = { ...source, providerName: key };
+    const credential = {
+      ...source,
+      providerName: key
+    };
     const providerName = key.trim();
     if (!providerName)
       throw new Error("Model credential providerName is required");
@@ -1398,7 +1640,14 @@ function buildDirectProvisioningPlan(input) {
     },
     ...plugins.length ? { plugin: plugins } : {}
   };
+  const github = githubAuthProvisioning(input.repo ? {
+    url: input.repo,
+    authToken: input.repositoryCredentials?.token,
+    authUsername: input.repositoryCredentials?.username,
+    inlineAuth: true
+  } : undefined);
   const files = [
+    ...github?.files ?? [],
     {
       path: "~/.local/share/opencode/auth.json",
       contentBase64: base64(JSON.stringify(Object.fromEntries(credentials)))
@@ -1442,11 +1691,11 @@ function buildDirectProvisioningPlan(input) {
         ...environmentVariables,
         OPENCODE_SERVER_PASSWORD: input.password
       },
-      command: DIRECT_OPENCODE_COMMAND,
+      command: github ? githubAuthCommand(DIRECT_OPENCODE_COMMAND) : DIRECT_OPENCODE_COMMAND,
       port: DIRECT_OPENCODE_PORT
     },
     setup: {
-      beforeAgent: input.setup?.beforeAgent ?? [],
+      beforeAgent: [...github ? [github.setup] : [], ...input.setup?.beforeAgent ?? []],
       afterAgent: input.setup?.afterAgent ?? []
     }
   };
@@ -1471,7 +1720,9 @@ function railwayContainerEnvironment(plan) {
       } : {}
     } : {},
     AGENT_FILES_BASE64: base64(JSON.stringify(plan.agent.files)),
-    ...beforeAgent.length ? { WORKSPACE_SETUP_COMMAND_BASE64: base64(setupCommandScript(beforeAgent)) } : {},
+    ...beforeAgent.length ? {
+      WORKSPACE_SETUP_COMMAND_BASE64: base64(setupCommandScript(beforeAgent))
+    } : {},
     GITTERM_DIRECT_PROVIDER: "railway"
   };
 }
@@ -2793,7 +3044,7 @@ function runtimeClient(workspace, fetchImpl) {
 }
 function createAuthClient(workspace, fetchImpl) {
   if (workspace.opencodeApi !== "v2")
-    throw new GittermError("BAD_REQUEST", "Runtime OAuth connection management requires OpenCode v2; use inline credentials or a managed workspace with v1");
+    throw new GittermError("BAD_REQUEST", "Runtime OAuth connection management requires OpenCode v2");
   const authorization = workspace.runtime.password ? `Basic ${Buffer.from(`opencode:${workspace.runtime.password}`).toString("base64")}` : undefined;
   return createOpencodeV2Client({
     fetch: fetchImpl,

package/dist/direct/provisioning.d.ts

@@ -6,7 +6,7 @@ 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 const DIRECT_GITTERM_INSTRUCTIONS = "You are running in a direct Gitterm workspace. Follow the user's instructions and verify outcomes before reporting success.\n\nGitHub CLI authentication:\n- The user may have supplied repository credentials or selected a GitHub integration for this workspace. GitTerm authentication is configured only when $HOME/.gitterm/bin/gh exists. Check for that executable, but never read or print files under $HOME/.gitterm/github.\n- The image may not include the real GitHub CLI. Run gh --version. If the GitTerm launcher says the CLI is missing, install the official gh binary using the image's package manager or in another directory.\n- Keep $HOME/.gitterm/bin first on PATH after installation. For a downloaded CLI, use: export PATH=\"$HOME/.gitterm/bin:/path/to/installed/gh/bin:$PATH\". Never prepend the real CLI ahead of $HOME/.gitterm/bin and never overwrite $HOME/.gitterm/bin/gh.\n- With the launcher first, use the normal gh command (for example, gh pr create). The launcher supplies the user-provided token or a fresh integration token only to that operation.\n- Never run gh auth login, pipe $GH_TOKEN, copy tokens, or use gh auth status for this workspace authentication. $GH_TOKEN is intentionally not exported to the agent shell.\n- If $HOME/.gitterm/bin/gh is absent, tell the user that this workspace has no GitTerm-provided GitHub credentials. If an authenticated operation is denied, report the denied operation and ask for repository access or the required GitHub App/token permission.";
 export declare function resolveDirectImage(image?: string): string;
 export declare function directModelAuth(credential: DirectModelCredential): {
     enterpriseUrl?: string | undefined;

package/dist/direct/types.d.ts

@@ -126,6 +126,7 @@ export type DirectWorkspaceCreateInput = {
     branch?: string;
     baseCommit?: string;
     checkoutRef?: string;
+    /** Git credentials; also configure runtime Git/gh authentication for github.com. Not auto-renewed. */
     repositoryCredentials?: {
         username?: string;
         token: string;

package/dist/index.d.ts

@@ -6,4 +6,4 @@ export type { DeviceCodeInfo, LoginWithDeviceCodeOptions } from "./device-login.
 export { AgentRunError, GittermError, WorkspaceLifecycleError } from "./errors.js";
 export { createGittermWorkspaceClient, getWorkspaceEnvironment, type GittermWorkspaceClient, type WorkspaceClientOptions, type WorkspaceEnvironment, type WorkspacePort, type WorkspaceSelf, } from "./workspace-client.js";
 export type { CredentialErrorCode, GittermErrorCode, WorkspaceLifecycleErrorCode, } from "./errors.js";
-export type { AgentPermissionRequest, AgentQuestion, AgentQuestionOption, AgentQuestionRequest, AgentRun, AgentRunCreateInput, AgentRunInputRequest, AgentRunMessage, AgentRunMessagePart, AgentRunReply, AgentRunStatus, AgentRunEvent, AgentRunResult, AgentRunReplyPermission, AgentRunReplyQuestion, RunResultOptions, RunRef, RunWaitOptions, RunWatchOptions, OpencodeApi, AgentType, AgentKey, AuthStatus, BuiltInAgentKey, CloudProvider, ProviderKey, Workspace, WorkspaceCreateInput, WorkspaceCreateResult, WorkspaceCatalog, WorkspaceEnsureRunningResult, WorkspaceHostingType, WorkspaceListOptions, WorkspaceListResult, WorkspaceRestartResult, WorkspaceRuntimeAccess, WorkspaceStatus, WorkspaceSetupStatus, ModelCredential, ModelProviderInfo, ModelInfo, ModelCredentialSource, WorkspaceModelsInput, WorkspaceModelAccess, WorkspacePauseResult, WorkspaceTerminateResult, WorkspaceProviderSelection, } from "./types.js";
+export type { AgentPermissionRequest, AgentQuestion, AgentQuestionOption, AgentQuestionRequest, AgentRun, AgentRunCreateInput, AgentRunInputRequest, AgentRunMessage, AgentRunMessagePart, AgentRunReply, AgentRunStatus, AgentRunEvent, AgentRunResult, AgentRunReplyPermission, AgentRunReplyQuestion, RunResultOptions, RunRef, RunWaitOptions, RunWatchOptions, OpencodeApi, AgentType, AgentKey, AuthStatus, BuiltInAgentKey, CloudProvider, ProviderKey, Workspace, WorkspaceCreateInput, WorkspaceCreateResult, WorkspaceCatalog, WorkspaceEnsureRunningResult, WorkspaceHostingType, WorkspaceListOptions, WorkspaceListResult, WorkspaceRestartResult, WorkspaceRuntimeAccess, WorkspaceStatus, WorkspaceSetupStatus, ModelCredential, ModelProviderInfo, ModelInfo, ModelCredentialSource, WorkspaceModelsInput, WorkspaceModelAccess, WorkspacePauseResult, WorkspaceTerminateResult, WorkspaceProviderSelection, GitHubIntegration, GoogleCloudIntegration, } from "./types.js";

package/dist/index.js

@@ -686,6 +686,34 @@ ${log}` : ""}`);
         })).filter((model) => !listOptions?.provider || model.provider === listOptions.provider);
       })
     },
+    integrations: {
+      github: {
+        list: () => run(async () => {
+          const result = await trpc.workspace.listUserInstallations.query();
+          return result.installations.map(({ git_integration, github_app_installation }) => ({
+            id: git_integration.id,
+            accountLogin: git_integration.providerAccountLogin,
+            accountType: github_app_installation.accountType,
+            repositorySelection: github_app_installation.repositorySelection,
+            suspended: github_app_installation.suspended,
+            connectedAt: toIso(git_integration.connectedAt)
+          }));
+        })
+      },
+      googleCloud: {
+        list: () => run(async () => {
+          const result = await trpc.googleCloud.list.query();
+          return result.map((integration) => ({
+            id: integration.id,
+            name: integration.name,
+            projectId: integration.projectId,
+            workloadIdentityProvider: integration.workloadIdentityProvider,
+            serviceAccountEmail: integration.serviceAccountEmail,
+            connectedAt: toIso(integration.connectedAt)
+          }));
+        })
+      }
+    },
     credentials: {
       list: () => run(async () => {
         const result = await trpc.modelCredentials.listMyCredentials.query();

package/dist/types.d.ts

@@ -63,7 +63,7 @@ export type RunRef = {
     workspaceId: string;
     id: string;
 };
-/** `v1` = OpenCode 1.x (`/event`, `/session/*`); `v2` = OpenCode 2 (`/api/*`), experimental until 2.0 ships. */
+/** `v1` = OpenCode 1.x (`/event`, `/session/*`) and the default; `v2` = OpenCode 2 (`/api/*`). */
 export type OpencodeApi = "v1" | "v2";
 export type WaitOptions = {
     timeoutMs?: number;
@@ -161,6 +161,7 @@ export type WorkspaceProviderSelection = {
 } | ({
     type: "aws";
     region?: string;
+    accessProfile?: string;
 } & Omit<ProviderSelectionBase, "machine"> & {
     machine?: FlexibleMachine<AwsResources>;
 }) | ({
@@ -223,11 +224,15 @@ export type WorkspaceCreateInput = {
     /** Provider intent. Defaults to the user's or deployment's preferred provider. */
     provider?: WorkspaceProviderSelection;
     /** Inline Git credentials for repository validation, cloning, and runtime pull/push. */
+    /** Runtime Git/gh authentication. Takes precedence over gitIntegrationId; not auto-renewed. */
     repositoryCredentials?: {
         username?: string;
         token: string;
     };
+    /** Dashboard GitHub App integration; runtime Git/gh credentials are renewed automatically. */
     gitIntegrationId?: string;
+    /** Google Workload Identity Federation integration; injects keyless ADC/gcloud auth. */
+    googleCloudIntegrationId?: string;
     /** Defaults from the selected provider. */
     persistent?: boolean;
     workspaceProfile?: "standard" | "ssh-enabled";
@@ -268,11 +273,27 @@ export type WorkspaceCreateInput = {
         config?: Record<string, unknown>;
         /**
          * OpenCode API generation served by the image. Defaults to `v1`. Use `v2`
-         * with an image built on OpenCode 2 (`@opencode-ai/cli`); experimental.
+         * only with an explicitly compatible image.
          */
         api?: OpencodeApi;
     };
 };
+export type GitHubIntegration = {
+    id: string;
+    accountLogin: string;
+    accountType: string;
+    repositorySelection: string;
+    suspended: boolean;
+    connectedAt: string;
+};
+export type GoogleCloudIntegration = {
+    id: string;
+    name: string;
+    projectId: string;
+    workloadIdentityProvider: string;
+    serviceAccountEmail: string;
+    connectedAt: string;
+};
 export type WorkspaceRestartResult = {
     status: WorkspaceStatus;
 };
@@ -594,6 +615,12 @@ export type AgentType = {
 export type CloudProvider = {
     id: string;
     name: string;
+    awsAccessProfiles?: Array<{
+        id: string;
+        name: string;
+        description: string;
+        roleArn: string;
+    }>;
     providerKey: ProviderKey | string;
     regions?: Array<{
         id: string;
@@ -623,6 +650,12 @@ export type WorkspaceCatalog = {
             name: string;
             location: string;
         }>;
+        accessProfiles?: Array<{
+            id: string;
+            name: string;
+            description: string;
+            roleArn: string;
+        }>;
         machines: Array<{
             id: string;
             key: string;

package/package.json

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