@gitterm/sdk 0.1.0 → 0.1.2

package/README.md

@@ -10,14 +10,14 @@ Direct mode runs an agent using your cloud-provider account without a Gitterm se
 
 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         |
+| 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.
 
@@ -53,6 +53,43 @@ try {
 
 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:
@@ -187,6 +224,49 @@ const client = createGittermClient({
 const { workspaces } = await client.workspaces.list();
 ```
 
+### Managed private repositories
+
+For renewable, short-lived repository authentication, connect the GitHub App in the GitTerm
+dashboard and copy its **SDK integration ID** from the Integrations page:
+
+```ts
+const { workspace, runtime } = await client.workspaces.create({
+  repo: "https://github.com/acme/private-repo",
+  branch: "main",
+  gitIntegrationId: "your-dashboard-integration-id",
+});
+```
+
+Managed workspaces can also use dashboard-managed model subscriptions while accepting an
+application-owned GitHub PAT inline:
+
+```ts
+const client = createGittermClient({
+  token: process.env.GITTERM_API_TOKEN,
+});
+
+const { workspace, runtime } = await client.workspaces.create({
+  repo: "https://github.com/acme/private-repo",
+  branch: "main",
+  repositoryCredentials: {
+    username: "x-access-token",
+    token: process.env.GITHUB_TOKEN!,
+  },
+});
+```
+
+The username defaults to `x-access-token`. Inline repository credentials take precedence over
+`gitIntegrationId` and authenticate repository validation, cloning, and runtime Git operations such
+as pull and push. Without inline credentials, `gitIntegrationId` continues to use the connected
+dashboard integration. Omitting `modelCredentialIds` and `modelCredentials` likewise continues to
+use dashboard-managed model credentials.
+
+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
+`gitIntegrationId` for durable managed workspaces and use narrowly scoped, short-lived PATs when
+inline credentials are necessary.
+
 The SDK deliberately exposes two clients. `createGittermClient()` uses a user API token and
 can manage the user's workspaces. `createGittermWorkspaceClient()` uses the scoped identity
 injected into a GitTerm workspace and can inspect only that workspace and its ports:
@@ -237,7 +317,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: [
       {
@@ -259,12 +342,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
@@ -286,7 +395,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/client.d.ts

@@ -1,4 +1,4 @@
-import type { DirectProviderAdapter, DirectProviderConfig, DirectAuthAttempt, DirectAuthAttemptStatus, DirectAuthIntegration, DirectAuthWaitOptions, DirectModelCredential, DirectRun, DirectRunCreateInput, DirectRunMessage, DirectRunWaitOptions, DirectWorkspace, DirectWorkspaceCreateInput } from "./types.js";
+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;
 };
@@ -36,6 +36,8 @@ export declare function createDirectGittermClient(options: DirectGittermClientOp
         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>;

package/dist/direct/index.d.ts

@@ -5,4 +5,4 @@ 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";
+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";

package/dist/direct/index.js

@@ -16,6 +16,8 @@ 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 MAX_ADDITIONAL_AGENT_INSTRUCTIONS = 50000;
 function resolveDirectImage(image) {
   return image?.trim() || DIRECT_OPENCODE_SERVER_IMAGE;
 }
@@ -46,6 +48,28 @@ function directModelAuth(credential) {
 function base64(value) {
   return Buffer.from(value).toString("base64");
 }
+function validateDirectFilePath(path) {
+  if (path.includes("\x00") || !path.startsWith("/") && !path.startsWith("~/") || path.split("/").some((part) => part === ".." || part === ".") || path === "/" || path === "~/") {
+    throw new Error(`Invalid secret file path: ${path}`);
+  }
+  return path;
+}
+function validateDirectFileMode(mode = 384) {
+  if (!Number.isInteger(mode) || mode < 0 || mode > 511) {
+    throw new Error("Secret file mode must be an integer between 0000 and 0777");
+  }
+  return mode;
+}
+function buildDirectGittermInstructions(additional) {
+  const trimmed = additional?.trim();
+  if (trimmed && trimmed.length > MAX_ADDITIONAL_AGENT_INSTRUCTIONS) {
+    throw new Error("additionalAgentInstructions is too large");
+  }
+  return trimmed ? `${DIRECT_GITTERM_INSTRUCTIONS}
+
+${trimmed}
+` : DIRECT_GITTERM_INSTRUCTIONS;
+}
 function validateName(value, kind) {
   if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(value) || value === "." || value === "..") {
     throw new Error(`Invalid ${kind}: ${value}`);
@@ -89,10 +113,15 @@ function buildDirectProvisioningPlan(input) {
   const environmentVariables = { ...input.environmentVariables };
   delete environmentVariables.OPENCODE_SERVER_USERNAME;
   delete environmentVariables.GITTERM_DIRECT_PROVIDER;
+  const userPermission = input.opencode?.config?.permission && typeof input.opencode.config.permission === "object" && !Array.isArray(input.opencode.config.permission) ? input.opencode.config.permission : {};
   const config = {
     $schema: "https://opencode.ai/config.json",
     ...input.opencode?.config,
     username: "Gitterm direct",
+    permission: {
+      external_directory: "allow",
+      ...userPermission
+    },
     ...plugins.length ? { plugin: plugins } : {}
   };
   const files = [
@@ -106,13 +135,21 @@ function buildDirectProvisioningPlan(input) {
     },
     {
       path: "~/.config/opencode/AGENTS.md",
-      contentBase64: base64("You are running in a direct Gitterm workspace. Follow the user's instructions and verify outcomes before reporting success.")
+      contentBase64: base64(buildDirectGittermInstructions(input.additionalAgentInstructions))
     },
     ...(input.opencode?.skills ?? []).map((skill) => ({
       path: `~/.config/opencode/skills/${validateName(skill.name, "skill name")}/SKILL.md`,
       contentBase64: base64(skill.content)
+    })),
+    ...(input.secretFiles ?? []).map((file) => ({
+      path: validateDirectFilePath(file.path),
+      contentBase64: base64(file.content),
+      mode: validateDirectFileMode(file.mode)
     }))
   ];
+  const duplicatePath = files.find((file, index) => files.findIndex((candidate) => candidate.path === file.path) !== index);
+  if (duplicatePath)
+    throw new Error(`Duplicate provisioned file path: ${duplicatePath.path}`);
   return {
     workspaceId: input.id,
     lifecycle: input.lifecycle,
@@ -134,11 +171,18 @@ function buildDirectProvisioningPlan(input) {
       command: DIRECT_OPENCODE_COMMAND,
       port: DIRECT_OPENCODE_PORT
     },
-    setupCommands: input.setupCommands ?? []
+    setup: {
+      beforeAgent: input.setup?.beforeAgent ?? [],
+      afterAgent: input.setup?.afterAgent ?? []
+    }
   };
 }
 function railwayContainerEnvironment(plan) {
   const repository = plan.repository;
+  const beforeAgent = [
+    ...plan.agent.files.flatMap((file) => file.mode == null ? [] : [`chmod ${file.mode.toString(8)} ${shellPath(file.path)}`]),
+    ...plan.setup.beforeAgent
+  ];
   return {
     ...plan.agent.environmentVariables,
     ...repository ? {
@@ -153,7 +197,7 @@ function railwayContainerEnvironment(plan) {
       } : {}
     } : {},
     AGENT_FILES_BASE64: base64(JSON.stringify(plan.agent.files)),
-    ...plan.setupCommands.length ? { WORKSPACE_SETUP_COMMAND_BASE64: base64(setupCommandScript(plan.setupCommands)) } : {},
+    ...beforeAgent.length ? { WORKSPACE_SETUP_COMMAND_BASE64: base64(setupCommandScript(beforeAgent)) } : {},
     GITTERM_DIRECT_PROVIDER: "railway"
   };
 }
@@ -164,6 +208,9 @@ function setupCommandScript(commands) {
 function shellQuote(value) {
   return `'${value.replaceAll("'", `'"'"'`)}'`;
 }
+function shellPath(path) {
+  return path.startsWith("~/") ? `"$HOME"/${shellQuote(path.slice(2))}` : shellQuote(path);
+}
 function cloneRepositoryScript(repository, directory) {
   const ref = repository.checkoutRef ?? repository.branch;
   const commands = [
@@ -333,9 +380,12 @@ function createAsciiDirectProvider(config) {
             boxId: handle.boxId,
             fileWriteRequest: { path, content: file.contentBase64, encoding: "base64" }
           });
+          if (file.mode != null) {
+            await runCommand(handle.boxId, `chmod ${file.mode.toString(8)} ${shellQuote(`${HOME}/${path}`)}`);
+          }
         }
-        if (plan.setupCommands.length) {
-          await runCommand(handle.boxId, setupCommandScript(plan.setupCommands), directory, 600);
+        if (plan.setup.beforeAgent.length) {
+          await runCommand(handle.boxId, setupCommandScript(plan.setup.beforeAgent), directory, 600);
         }
         await startRuntime(handle);
         const runtime = {
@@ -499,10 +549,10 @@ function createDaytonaDirectProvider(config) {
         for (const file of plan.agent.files) {
           const target = file.path.replace(/^~/, home);
           const parent = target.slice(0, target.lastIndexOf("/"));
-          await execute(sandbox, `mkdir -p ${shellQuote(parent)} && printf %s ${shellQuote(file.contentBase64)} | base64 -d > ${shellQuote(target)}`);
+          await execute(sandbox, `mkdir -p ${shellQuote(parent)} && printf %s ${shellQuote(file.contentBase64)} | base64 -d > ${shellQuote(target)}${file.mode == null ? "" : ` && chmod ${file.mode.toString(8)} ${shellQuote(target)}`}`);
         }
-        if (plan.setupCommands.length) {
-          await execute(sandbox, setupCommandScript(plan.setupCommands), directory);
+        if (plan.setup.beforeAgent.length) {
+          await execute(sandbox, setupCommandScript(plan.setup.beforeAgent), directory);
         }
         await startAgent(sandbox, handle);
         const runtime = await runtimeFor(sandbox, handle, input.password);
@@ -625,10 +675,12 @@ function createE2BDirectProvider(config) {
         for (const file of plan.agent.files) {
           const path = file.path.replace(/^~/, "/home/user");
           const parent = path.slice(0, path.lastIndexOf("/"));
-          await sandbox.commands.run(`mkdir -p ${shellQuote(parent)} && printf %s ${shellQuote(file.contentBase64)} | base64 -d > ${shellQuote(path)}`);
+          await sandbox.commands.run(`mkdir -p ${shellQuote(parent)} && printf %s ${shellQuote(file.contentBase64)} | base64 -d > ${shellQuote(path)}${file.mode == null ? "" : ` && chmod ${file.mode.toString(8)} ${shellQuote(path)}`}`);
         }
-        if (plan.setupCommands.length) {
-          await sandbox.commands.run(setupCommandScript(plan.setupCommands), { cwd: directory });
+        if (plan.setup.beforeAgent.length) {
+          await sandbox.commands.run(setupCommandScript(plan.setup.beforeAgent), {
+            cwd: directory
+          });
         }
         await sandbox.commands.run(plan.agent.command, {
           cwd: directory,
@@ -697,7 +749,7 @@ function serializeHandle2(handle) {
 function parseHandle3(value) {
   try {
     const handle = JSON.parse(value);
-    if (!handle.vmName || !handle.repoDir || !handle.serve?.command || !handle.serve.port) {
+    if (!handle.vmName || !handle.repoDir || !handle.serve?.command || !handle.serve.port || !handle.pidFile || typeof handle.owned !== "boolean") {
       throw new Error("missing required fields");
     }
     return handle;
@@ -748,8 +800,9 @@ function createExeDevDirectProvider(config) {
   }
   const runVmCommand = (handle, command) => execute(`ssh ${handle.vmName} -- bash -lc ${shellQuote(command)}`);
   async function startRuntime(handle) {
-    await runVmCommand(handle, `cd ${shellQuote(handle.repoDir)} && nohup setsid bash -lc ${shellQuote(handle.serve.command)} > /tmp/opencode-server.log 2>&1 </dev/null &`);
+    await runVmCommand(handle, `cd ${shellQuote(handle.repoDir)} && nohup setsid bash -lc ${shellQuote(handle.serve.command)} > /tmp/opencode-server.log 2>&1 </dev/null & printf %s "$!" > ${shellQuote(handle.pidFile)}`);
   }
+  const stopRuntime = (handle) => runVmCommand(handle, `if [ -f ${shellQuote(handle.pidFile)} ]; then kill "$(cat ${shellQuote(handle.pidFile)})" 2>/dev/null || true; rm -f ${shellQuote(handle.pidFile)}; fi`);
   async function accessToken(vmName) {
     const token = findToken(await execute(`ssh-key generate-api-key --vm=${vmName} --label=gitterm-direct --exp=never`));
     if (!token)
@@ -787,11 +840,19 @@ function createExeDevDirectProvider(config) {
     async create(input) {
       const plan = input.provisioning;
       const vmSuffix = input.id.replace(/[^a-zA-Z0-9]/g, "").slice(0, 20).toLowerCase();
-      const vmName = `gitterm-${vmSuffix}`;
+      const attachedVmName = input.exedev?.existingVmName.trim();
+      if (input.exedev && !attachedVmName)
+        throw new Error("exe.dev existingVmName is required");
+      if (attachedVmName && !/^[a-zA-Z0-9][a-zA-Z0-9-]*$/.test(attachedVmName)) {
+        throw new Error("Invalid exe.dev existingVmName");
+      }
+      const vmName = attachedVmName ?? `gitterm-${vmSuffix}`;
       const handle = {
         vmName,
         repoDir: `${HOME2}/${plan.repository?.name ?? "workspace"}`,
-        serve: { command: plan.agent.command, port: plan.agent.port }
+        serve: { command: plan.agent.command, port: plan.agent.port },
+        pidFile: `/tmp/gitterm-${vmSuffix}.pid`,
+        owned: !attachedVmName
       };
       const createArgs = [
         `new --name=${vmName}`,
@@ -803,7 +864,8 @@ function createExeDevDirectProvider(config) {
         config.disk ? `--disk=${shellQuote(config.disk)}` : "",
         ...Object.entries(plan.agent.environmentVariables).map(([key, value]) => `--env=${shellQuote(`${key}=${value}`)}`)
       ].filter(Boolean).join(" ");
-      await execute(createArgs);
+      if (handle.owned)
+        await execute(createArgs);
       try {
         await waitUntilRunning(vmName);
         await runVmCommand(handle, `mkdir -p ${shellQuote(handle.repoDir)}`);
@@ -815,10 +877,10 @@ function createExeDevDirectProvider(config) {
         }
         for (const file of plan.agent.files) {
           const path = file.path.startsWith("~/") ? `${HOME2}/${file.path.slice(2)}` : file.path;
-          await runVmCommand(handle, `mkdir -p ${shellQuote(path.slice(0, path.lastIndexOf("/")))} && printf %s ${shellQuote(file.contentBase64)} | base64 -d > ${shellQuote(path)}`);
+          await runVmCommand(handle, `mkdir -p ${shellQuote(path.slice(0, path.lastIndexOf("/")))} && printf %s ${shellQuote(file.contentBase64)} | base64 -d > ${shellQuote(path)}${file.mode == null ? "" : ` && chmod ${file.mode.toString(8)} ${shellQuote(path)}`}`);
         }
-        if (plan.setupCommands.length) {
-          await runVmCommand(handle, `cd ${shellQuote(handle.repoDir)} && ${setupCommandScript(plan.setupCommands)}`);
+        if (plan.setup.beforeAgent.length) {
+          await runVmCommand(handle, `cd ${shellQuote(handle.repoDir)} && ${setupCommandScript(plan.setup.beforeAgent)}`);
         }
         await startRuntime(handle);
         await execute(`share port ${vmName} ${handle.serve.port}`);
@@ -827,9 +889,15 @@ function createExeDevDirectProvider(config) {
         await waitForDirectRuntime(directRuntime);
         return { externalId: serializeHandle2(handle), runtime: directRuntime };
       } catch (error) {
-        await execute(`rm ${vmName}`).catch(() => {
-          return;
-        });
+        if (handle.owned) {
+          await execute(`rm ${vmName}`).catch(() => {
+            return;
+          });
+        } else {
+          await stopRuntime(handle).catch(() => {
+            return;
+          });
+        }
         throw error;
       }
     },
@@ -859,7 +927,12 @@ function createExeDevDirectProvider(config) {
       return directRuntime;
     },
     async terminate(workspace) {
-      await execute(`rm ${parseHandle3(workspace.externalId).vmName}`);
+      const handle = parseHandle3(workspace.externalId);
+      if (handle.owned) {
+        await execute(`rm ${handle.vmName}`);
+      } else {
+        await stopRuntime(handle);
+      }
     }
   };
 }
@@ -908,6 +981,7 @@ var SERVICE_DEPLOY = `
 `;
 var LATEST_DEPLOYMENT = `
   query DirectLatestDeployment($environmentId: String!, $serviceId: String!) {
+    service(id: $serviceId) { id deletedAt }
     serviceInstance(environmentId: $environmentId, serviceId: $serviceId) {
       latestDeployment { id status }
     }
@@ -1000,10 +1074,31 @@ function createRailwayDirectProvider(config) {
       throw new Error("Railway GraphQL response did not include data");
     return result.data;
   };
-  const latestDeployment = async (serviceId) => {
-    const result = await request(LATEST_DEPLOYMENT, { environmentId: config.environmentId, serviceId });
-    return result.serviceInstance?.latestDeployment ?? undefined;
+  const missingService = (error) => error instanceof Error && /not found|does not exist|deleted|no service/i.test(error.message);
+  const serviceSnapshot = async (serviceId) => {
+    const response = await fetch(apiUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${config.apiToken}`
+      },
+      body: JSON.stringify({
+        query: LATEST_DEPLOYMENT,
+        variables: { environmentId: config.environmentId, serviceId }
+      })
+    });
+    if (!response.ok) {
+      throw new Error(`Railway API request failed (${response.status} ${response.statusText})`);
+    }
+    const result = await response.json();
+    if (result.data)
+      return result.data;
+    if (result.errors?.length) {
+      throw new Error(`Railway GraphQL error: ${result.errors.map((error) => error.message).join(", ")}`);
+    }
+    throw new Error("Railway GraphQL response did not include data");
   };
+  const latestDeployment = async (serviceId) => (await serviceSnapshot(serviceId)).serviceInstance?.latestDeployment ?? undefined;
   const waitForDeployment = async (serviceId, previousDeploymentId) => {
     const deadline = Date.now() + DEPLOYMENT_TIMEOUT_MS;
     while (Date.now() < deadline) {
@@ -1149,12 +1244,16 @@ function createRailwayDirectProvider(config) {
     async status(workspace) {
       const handle = parseHandle4(workspace.externalId);
       try {
-        const deployment = await latestDeployment(handle.serviceId);
-        return deployment ? workspaceStatus(deployment.status) : "terminated";
+        const snapshot = await serviceSnapshot(handle.serviceId);
+        if (!snapshot.service || snapshot.service.deletedAt)
+          return "terminated";
+        const deployment = snapshot.serviceInstance?.latestDeployment;
+        if (!deployment)
+          return "paused";
+        return workspaceStatus(deployment.status);
       } catch (error) {
-        if (error instanceof Error && /not found|does not exist/i.test(error.message)) {
+        if (missingService(error))
           return "terminated";
-        }
         throw error;
       }
     },
@@ -1307,11 +1406,15 @@ esac
           const parent = target.slice(0, target.lastIndexOf("/"));
           await run(sandbox, `mkdir -p ${shellQuote(parent)}`);
           await sandbox.writeFiles([
-            { path: target, content: Buffer.from(file.contentBase64, "base64") }
+            {
+              path: target,
+              content: Buffer.from(file.contentBase64, "base64"),
+              ...file.mode == null ? {} : { mode: file.mode }
+            }
           ]);
         }
-        if (plan.setupCommands.length) {
-          await run(sandbox, setupCommandScript(plan.setupCommands), handle.directory);
+        if (plan.setup.beforeAgent.length) {
+          await run(sandbox, setupCommandScript(plan.setup.beforeAgent), handle.directory);
         }
         await startAgent(sandbox, handle);
         const runtime = {
@@ -1383,6 +1486,7 @@ esac
 }
 
 // src/direct/client.ts
+var SETUP_DIR = ".gitterm/setup";
 function resolveProvider(provider) {
   if ("create" in provider)
     return provider;
@@ -1480,6 +1584,38 @@ function modelParts(model) {
   }
   return { providerID: model.slice(0, separator), modelID: model.slice(separator + 1) };
 }
+function validateEnvironmentVariables(values) {
+  for (const key of Object.keys(values)) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+      throw new Error(`Invalid environment variable name: ${key}`);
+    }
+    if (key === "OPENCODE_SERVER_PASSWORD" || key === "OPENCODE_SERVER_USERNAME" || key === "GITTERM_DIRECT_PROVIDER") {
+      throw new Error(`Environment variable ${key} is managed by Gitterm`);
+    }
+  }
+  return values;
+}
+function setupRunner(commands) {
+  const body = Buffer.from(setupCommandScript(commands)).toString("base64");
+  return [
+    "set -u",
+    `SETUP_DIR=${shellQuote(SETUP_DIR)}`,
+    'mkdir -p "$SETUP_DIR"',
+    'if [ -d .git/info ]; then grep -qxF "/.gitterm/" .git/info/exclude 2>/dev/null || printf "/.gitterm/\\n" >> .git/info/exclude; fi',
+    'printf "waiting\\n" > "$SETUP_DIR/state"',
+    `printf %s ${shellQuote(body)} | base64 -d > "$SETUP_DIR/script.sh"`,
+    'chmod 700 "$SETUP_DIR/script.sh"',
+    'date -u +%Y-%m-%dT%H:%M:%SZ > "$SETUP_DIR/started-at"',
+    'printf "running\\n" > "$SETUP_DIR/state"',
+    'bash -e "$SETUP_DIR/script.sh" > "$SETUP_DIR/setup.log" 2>&1',
+    "code=$?",
+    'printf "%s\\n" "$code" > "$SETUP_DIR/exit-code"',
+    'date -u +%Y-%m-%dT%H:%M:%SZ > "$SETUP_DIR/finished-at"',
+    'if [ "$code" -eq 0 ]; then printf "succeeded\\n" > "$SETUP_DIR/state"; else printf "failed\\n" > "$SETUP_DIR/state"; fi',
+    "exit $code"
+  ].join(`
+`);
+}
 function createDirectGittermClient(options) {
   const provider = resolveProvider(options.provider);
   function assertWorkspace(workspace) {
@@ -1537,6 +1673,63 @@ function createDirectGittermClient(options) {
       finalText: finalText || null
     };
   }
+  async function startPty(workspace, command, title) {
+    const result = await authClient(workspace).pty.create({
+      command: "bash",
+      args: ["-lc", command],
+      cwd: workspace.runtime.directory,
+      directory: workspace.runtime.directory,
+      title
+    });
+    if (result.error || !result.data)
+      throw new Error(errorMessage(result.error));
+    return result.data;
+  }
+  async function setupFile(workspace, name) {
+    const result = await authClient(workspace).file.read({
+      directory: workspace.runtime.directory,
+      path: `${SETUP_DIR}/${name}`
+    });
+    if (result.error || !result.data || result.data.type !== "text")
+      return null;
+    return result.data.content.trim();
+  }
+  async function getSetupStatus(workspace) {
+    assertWorkspace(workspace);
+    if (workspace.setup === "not_requested") {
+      return {
+        status: "not_requested",
+        exitCode: null,
+        startedAt: null,
+        finishedAt: null,
+        log: null
+      };
+    }
+    if (workspace.setup === "before_agent_complete") {
+      return {
+        status: "succeeded",
+        exitCode: 0,
+        startedAt: null,
+        finishedAt: null,
+        log: null
+      };
+    }
+    const [state, exitCode, startedAt, finishedAt, log] = await Promise.all([
+      setupFile(workspace, "state"),
+      setupFile(workspace, "exit-code"),
+      setupFile(workspace, "started-at"),
+      setupFile(workspace, "finished-at"),
+      setupFile(workspace, "setup.log")
+    ]);
+    const status = ["waiting", "running", "succeeded", "failed"].includes(state ?? "") ? state : "waiting";
+    return {
+      status,
+      exitCode: exitCode != null && Number.isInteger(Number(exitCode)) ? Number(exitCode) : null,
+      startedAt,
+      finishedAt,
+      log: log?.slice(-50000) ?? null
+    };
+  }
   return {
     provider: { name: provider.name, capabilities: provider.capabilities },
     auth: {
@@ -1654,17 +1847,30 @@ function createDirectGittermClient(options) {
         }
         const id = input.id ?? randomUUID();
         const password = randomUUID();
+        validateEnvironmentVariables(input.environmentVariables ?? {});
         const provisioning = buildDirectProvisioningPlan({ ...input, id, lifecycle, password });
         const created = await provider.create({ ...input, id, lifecycle, password, provisioning });
-        return {
+        const workspace = {
           id,
           provider: provider.name,
           externalId: created.externalId,
           status: "running",
           lifecycle,
           runtime: created.runtime,
+          setup: provisioning.setup.afterAgent.length ? "after_agent" : provisioning.setup.beforeAgent.length ? "before_agent_complete" : "not_requested",
           createdAt: new Date().toISOString()
         };
+        if (provisioning.setup.afterAgent.length) {
+          try {
+            await startPty(workspace, setupRunner(provisioning.setup.afterAgent), "Gitterm setup");
+          } catch (error) {
+            await provider.terminate(workspace).catch(() => {
+              return;
+            });
+            throw error;
+          }
+        }
+        return workspace;
       },
       async status(workspace) {
         assertWorkspace(workspace);
@@ -1701,6 +1907,24 @@ function createDirectGittermClient(options) {
         if (!provider.keepAlive)
           throw new Error(`${provider.name} does not support keep-alive`);
         await provider.keepAlive(workspace, timeoutMs);
+      },
+      setupStatus: getSetupStatus,
+      async waitForSetup(workspace, wait = {}) {
+        const { timeoutMs, pollIntervalMs } = pollTiming(wait, 10 * 60000);
+        const deadline = Date.now() + timeoutMs;
+        while (true) {
+          const status = await getSetupStatus(workspace);
+          if (status.status === "not_requested" || status.status === "succeeded")
+            return status;
+          if (status.status === "failed") {
+            throw new Error(`Workspace setup failed${status.exitCode == null ? "" : ` with exit code ${status.exitCode}`}${status.log ? `
+${status.log}` : ""}`);
+          }
+          if (Date.now() >= deadline) {
+            throw new Error(`Workspace setup timed out after ${timeoutMs}ms`);
+          }
+          await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+        }
       }
     },
     runs: {
@@ -1792,11 +2016,11 @@ function createDirectGittermClient(options) {
   };
 }
 export {
-  createVercelDirectProvider,
-  createRailwayDirectProvider,
-  createExeDevDirectProvider,
-  createE2BDirectProvider,
-  createDirectGittermClient,
+  createAsciiDirectProvider,
   createDaytonaDirectProvider,
-  createAsciiDirectProvider
+  createDirectGittermClient,
+  createE2BDirectProvider,
+  createExeDevDirectProvider,
+  createRailwayDirectProvider,
+  createVercelDirectProvider
 };

package/dist/direct/provisioning.d.ts

@@ -6,6 +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 function resolveDirectImage(image?: string): string;
 export declare function directModelAuth(credential: DirectModelCredential): {
     enterpriseUrl?: string | undefined;
@@ -19,6 +20,9 @@ export declare function directModelAuth(credential: DirectModelCredential): {
     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;
@@ -28,6 +32,7 @@ export declare function buildDirectProvisioningPlan(input: DirectWorkspaceCreate
 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;

package/dist/direct/types.d.ts

@@ -108,6 +108,17 @@ 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;
@@ -121,7 +132,14 @@ export type DirectWorkspaceCreateInput = {
     lifecycle?: DirectWorkspaceLifecycle;
     environmentVariables?: Record<string, string>;
     modelCredentials?: DirectModelCredential[];
-    setupCommands?: string[];
+    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[];
@@ -144,8 +162,20 @@ export type DirectWorkspace = {
     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;
@@ -155,6 +185,7 @@ export type DirectProviderWorkspaceInput = DirectWorkspaceCreateInput & {
 export type DirectAgentFile = {
     path: string;
     contentBase64: string;
+    mode?: number;
 };
 export type DirectProvisioningPlan = {
     workspaceId: string;
@@ -174,7 +205,10 @@ export type DirectProvisioningPlan = {
         command: string;
         port: number;
     };
-    setupCommands: string[];
+    setup: {
+        beforeAgent: string[];
+        afterAgent: string[];
+    };
 };
 export interface DirectProviderAdapter {
     readonly name: string;

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

@@ -167,6 +167,11 @@ export type WorkspaceCreateInput = {
     agent?: AgentKey;
     /** 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. */
+    repositoryCredentials?: {
+        username?: string;
+        token: string;
+    };
     gitIntegrationId?: string;
     /** Defaults from the selected provider. */
     persistent?: boolean;
@@ -183,11 +188,22 @@ export type WorkspaceCreateInput = {
     /** 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.1.0",
+  "version": "0.1.2",
   "files": [
     "dist"
   ],