@stigmer/runner 3.0.1

package/src/shared/workspace/sources/git.ts

@@ -0,0 +1,285 @@
+/**
+ * Git workspace source — clones a repository into the workspace.
+ *
+ * Key behaviors ported from Python:
+ * - Idempotent: detects existing .git and skips re-clone
+ * - GitHub token injection via HTTPS URL (x-access-token)
+ * - Token is never logged; sanitized in error messages
+ * - GITHUB_TOKEN reported in consumedKeys for env stripping
+ * - Multi-entry mode: clones into target_subdir
+ * - Credential store configuration for git push/writeback
+ */
+
+import { join } from "node:path";
+import {
+  SourceType,
+  WorkspaceProvisionError,
+  type ProvisionResult,
+  type GitMetadata,
+  type WorkspaceBackend,
+} from "../types.js";
+
+export interface GitProvisionOptions {
+  url: string;
+  branch?: string;
+  backend: WorkspaceBackend;
+  envVars: Record<string, string>;
+  isLocalMode: boolean;
+  targetSubdir?: string;
+  configureCredentials?: boolean;
+}
+
+const GITHUB_HOST = "github.com";
+
+export async function provisionGit(options: GitProvisionOptions): Promise<ProvisionResult> {
+  const { url, branch, backend, envVars, isLocalMode, targetSubdir, configureCredentials } = options;
+
+  const cloneDir = targetSubdir
+    ? join(backend.rootDir, targetSubdir)
+    : backend.rootDir;
+
+  const gitExists = await backend.exists(
+    targetSubdir ? join(targetSubdir, ".git") : ".git",
+  );
+
+  if (gitExists) {
+    return reuseExistingRepo(cloneDir, url, backend, envVars, configureCredentials, targetSubdir);
+  }
+
+  const githubToken = envVars.GITHUB_TOKEN;
+  const consumedKeys: string[] = [];
+  let cloneUrl = url;
+
+  if (githubToken && url.includes(GITHUB_HOST)) {
+    cloneUrl = injectToken(url, githubToken);
+    consumedKeys.push("GITHUB_TOKEN");
+  }
+
+  try {
+    await cloneInPlace(backend, cloneDir, cloneUrl, branch);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const sanitized = githubToken
+      ? message.replaceAll(githubToken, "***")
+      : message;
+    throw new WorkspaceProvisionError(
+      SourceType.GIT_REPO,
+      `Git clone failed: ${sanitized}`,
+      { cause: err instanceof Error ? err : undefined, transient: true },
+    );
+  }
+
+  let metadata = await extractGitMetadata(cloneDir, url, backend, targetSubdir);
+
+  if (configureCredentials && githubToken && url.includes(GITHUB_HOST)) {
+    const configured = await configureGitCredentialStore(backend, cloneDir, url, githubToken);
+    if (configured) {
+      metadata = { ...metadata, gitCredentialsConfigured: true };
+    }
+  }
+
+  await addGitExcludes(backend, targetSubdir);
+
+  return {
+    rootDir: cloneDir,
+    sourceType: SourceType.GIT_REPO,
+    consumedKeys,
+    workspaceDescription:
+      `Your workspace is a git clone of ${url}` +
+      (metadata.branch ? ` (branch: ${metadata.branch})` : "") +
+      `.\nBase commit: ${metadata.baseCommit}`,
+    gitMetadata: metadata,
+    entryName: "",
+  };
+}
+
+async function reuseExistingRepo(
+  cloneDir: string,
+  url: string,
+  backend: WorkspaceBackend,
+  envVars: Record<string, string>,
+  configureCredentials?: boolean,
+  targetSubdir?: string,
+): Promise<ProvisionResult> {
+  let metadata = await extractGitMetadata(cloneDir, url, backend, targetSubdir);
+
+  const githubToken = envVars.GITHUB_TOKEN;
+  if (configureCredentials && githubToken && url.includes(GITHUB_HOST)) {
+    const configured = await configureGitCredentialStore(backend, cloneDir, url, githubToken);
+    if (configured) {
+      metadata = { ...metadata, gitCredentialsConfigured: true };
+    }
+  }
+
+  return {
+    rootDir: cloneDir,
+    sourceType: SourceType.GIT_REPO,
+    consumedKeys: [],
+    workspaceDescription:
+      `Your workspace is a git clone of ${url}` +
+      (metadata.branch ? ` (branch: ${metadata.branch})` : "") +
+      ` (existing repo detected).\nBase commit: ${metadata.baseCommit}`,
+    gitMetadata: metadata,
+    entryName: "",
+  };
+}
+
+/**
+ * Clone a repository into a directory that may already be non-empty.
+ *
+ * `git clone` refuses to write into a non-empty target, but cloud workspace
+ * mounts are not guaranteed empty — a freshly provisioned ext4 PersistentVolume
+ * ships a `lost+found` directory at its root. We therefore reproduce clone
+ * semantics in place: init the repo, add the (token-injected) origin remote,
+ * fetch all branches, and check out the requested branch (or the remote's
+ * default branch when none is requested). The result is identical to a clone —
+ * a working tree on a tracking branch — but tolerant of pre-existing content.
+ */
+async function cloneInPlace(
+  backend: WorkspaceBackend,
+  cloneDir: string,
+  cloneUrl: string,
+  branch: string | undefined,
+): Promise<void> {
+  await backend.execute(`git init -q '${cloneDir}'`);
+
+  const exec = (cmd: string) => backend.execute(cmd, { cwd: cloneDir });
+  await exec(`git remote add origin '${cloneUrl}'`);
+  await exec("git fetch --quiet origin");
+
+  const targetBranch = branch && branch.length > 0
+    ? branch
+    : await resolveDefaultBranch(backend, cloneDir);
+
+  // No target branch means the remote has no branches (empty repository).
+  // Leave the initialized repo as-is, matching `git clone` of an empty repo.
+  if (!targetBranch) return;
+
+  await exec(`git checkout '${targetBranch}'`);
+}
+
+/**
+ * Resolve the remote's default branch after a fetch. Returns an empty string
+ * when the remote exposes no default (e.g. an empty repository), so the caller
+ * can skip checkout gracefully.
+ */
+async function resolveDefaultBranch(
+  backend: WorkspaceBackend,
+  cloneDir: string,
+): Promise<string> {
+  const exec = (cmd: string) => backend.execute(cmd, { cwd: cloneDir });
+  try {
+    await exec("git remote set-head origin --auto");
+    const ref = (await exec("git symbolic-ref --short refs/remotes/origin/HEAD")).trim();
+    return ref.replace(/^origin\//, "");
+  } catch {
+    return "";
+  }
+}
+
+async function extractGitMetadata(
+  cloneDir: string,
+  url: string,
+  backend: WorkspaceBackend,
+  targetSubdir?: string,
+): Promise<GitMetadata> {
+  const cwd = targetSubdir ?? undefined;
+  let branchName = "";
+  let headSha = "";
+
+  try {
+    branchName = (await backend.execute("git rev-parse --abbrev-ref HEAD", { cwd: cloneDir })).trim();
+  } catch { /* non-fatal */ }
+
+  try {
+    headSha = (await backend.execute("git rev-parse HEAD", { cwd: cloneDir })).trim();
+  } catch { /* non-fatal */ }
+
+  return {
+    repoUrl: stripToken(url),
+    branch: branchName,
+    baseCommit: headSha,
+    gitCredentialsConfigured: false,
+  };
+}
+
+/**
+ * Working-tree entries the agent should never see as untracked changes:
+ * - `.stigmer` — platform-managed namespace (skills, inputs, attachments)
+ * - `lost+found` — present at the root of a freshly provisioned ext4
+ *   PersistentVolume, which is where single-entry sessions clone in place
+ */
+const GIT_EXCLUDE_ENTRIES = [".stigmer", "lost+found"];
+
+async function addGitExcludes(backend: WorkspaceBackend, targetSubdir?: string): Promise<void> {
+  const excludePath = targetSubdir
+    ? join(targetSubdir, ".git/info/exclude")
+    : ".git/info/exclude";
+
+  try {
+    const current = await backend.readFile(excludePath);
+    const missing = GIT_EXCLUDE_ENTRIES.filter((entry) => !current.includes(entry));
+    if (missing.length > 0) {
+      await backend.writeFile(
+        excludePath,
+        current.trimEnd() + "\n" + missing.join("\n") + "\n",
+      );
+    }
+  } catch {
+    // .git/info/exclude might not exist — non-fatal
+  }
+}
+
+/**
+ * Configure git credential store for push operations.
+ *
+ * Three-step process (each step is non-fatal):
+ * 1. Clean the remote URL — remove any embedded token from the origin remote
+ * 2. Set credential.helper to `store` with a repo-local credential file
+ * 3. Write the credential entry to the file
+ *
+ * Using repo-local config (not --global) keeps credentials scoped to
+ * the workspace and avoids polluting the host git config.
+ */
+async function configureGitCredentialStore(
+  backend: WorkspaceBackend,
+  cloneDir: string,
+  url: string,
+  token: string,
+): Promise<boolean> {
+  const exec = (cmd: string) => backend.execute(cmd, { cwd: cloneDir });
+  const credFile = join(cloneDir, ".git", ".git-credentials");
+  const cleanUrl = stripToken(url);
+
+  try {
+    await exec(`git remote set-url origin '${cleanUrl}'`);
+  } catch (err) {
+    console.warn(`[git] Failed to clean remote URL (non-fatal): ${err}`);
+    return false;
+  }
+
+  try {
+    await exec(`git config credential.helper 'store --file=${credFile}'`);
+  } catch (err) {
+    console.warn(`[git] Failed to configure credential helper (non-fatal): ${err}`);
+    return false;
+  }
+
+  const credEntry = `https://x-access-token:${token}@github.com\n`;
+  try {
+    await backend.writeFile(credFile, credEntry);
+  } catch (err) {
+    console.warn(`[git] Failed to write credential file (non-fatal): ${err}`);
+    return false;
+  }
+
+  return true;
+}
+
+function injectToken(url: string, token: string): string {
+  return url.replace("https://", `https://x-access-token:${token}@`);
+}
+
+function stripToken(url: string): string {
+  return url.replace(/https:\/\/[^@]+@/, "https://");
+}

package/src/shared/workspace/sources/local-path.ts

@@ -0,0 +1,89 @@
+/**
+ * Local-path workspace source — uses an existing host directory as-is.
+ *
+ * The user's project directory becomes the workspace root directly. No
+ * copy or clone is made; the agent operates on the original files.
+ *
+ * LocalPathSource is only valid in local mode. Cloud runners reject it
+ * with a clear error — use git_repo for cloud deployments.
+ */
+
+import { existsSync, statSync, symlinkSync, readlinkSync, unlinkSync, mkdirSync } from "node:fs";
+import { join, isAbsolute } from "node:path";
+import { realpathSync } from "node:fs";
+import {
+  SourceType,
+  WorkspaceProvisionError,
+  type ProvisionResult,
+} from "../types.js";
+
+export interface LocalPathProvisionOptions {
+  path: string;
+  isLocalMode: boolean;
+  targetSubdir?: string;
+  backendRootDir?: string;
+}
+
+export function provisionLocalPath(options: LocalPathProvisionOptions): ProvisionResult {
+  const { path, isLocalMode, targetSubdir, backendRootDir } = options;
+
+  if (!isLocalMode) {
+    throw new WorkspaceProvisionError(
+      SourceType.LOCAL_PATH,
+      "LocalPathSource is only supported in local mode. " +
+      "Use git_repo for cloud deployments.",
+    );
+  }
+
+  if (!isAbsolute(path)) {
+    throw new WorkspaceProvisionError(
+      SourceType.LOCAL_PATH,
+      `Path must be absolute, got relative path: '${path}'`,
+    );
+  }
+
+  if (!existsSync(path)) {
+    throw new WorkspaceProvisionError(
+      SourceType.LOCAL_PATH,
+      `Path does not exist: '${path}'`,
+    );
+  }
+
+  if (!statSync(path).isDirectory()) {
+    throw new WorkspaceProvisionError(
+      SourceType.LOCAL_PATH,
+      `Path is not a directory: '${path}'`,
+    );
+  }
+
+  if (targetSubdir && backendRootDir) {
+    createEntrySymlink(backendRootDir, targetSubdir, path);
+  }
+
+  return {
+    rootDir: path,
+    sourceType: SourceType.LOCAL_PATH,
+    consumedKeys: [],
+    workspaceDescription:
+      `Your workspace is the user's project directory: ${path}\n` +
+      "IMPORTANT: You are operating directly on the user's files. " +
+      "Changes are immediate and persistent.\n" +
+      "Use git to track and verify your changes before finalizing.",
+    entryName: "",
+  };
+}
+
+function createEntrySymlink(backendRootDir: string, targetSubdir: string, path: string): void {
+  const linkPath = join(backendRootDir, targetSubdir);
+
+  try {
+    const existing = readlinkSync(linkPath);
+    if (realpathSync(existing) === realpathSync(path)) return;
+    unlinkSync(linkPath);
+  } catch {
+    // link doesn't exist — will create below
+  }
+
+  mkdirSync(backendRootDir, { recursive: true });
+  symlinkSync(path, linkPath);
+}

package/src/shared/workspace/types.ts

@@ -0,0 +1,69 @@
+/**
+ * Workspace provisioning domain types.
+ *
+ * These types represent the result of workspace provisioning — they are
+ * harness-agnostic and used by both ExecuteCursor and ExecuteDeepAgent.
+ */
+
+export enum SourceType {
+  GIT_REPO = "git_repo",
+  LOCAL_PATH = "local_path",
+  EMPTY = "empty",
+}
+
+export interface GitMetadata {
+  readonly repoUrl: string;
+  readonly branch: string;
+  readonly baseCommit: string;
+  readonly gitCredentialsConfigured: boolean;
+}
+
+export interface ProvisionResult {
+  readonly rootDir: string;
+  readonly sourceType: SourceType;
+  readonly consumedKeys: readonly string[];
+  readonly workspaceDescription: string;
+  readonly fileTree?: string;
+  readonly gitMetadata?: GitMetadata;
+  readonly entryName: string;
+}
+
+export class WorkspaceProvisionError extends Error {
+  readonly sourceType: SourceType;
+  readonly cause?: Error;
+  readonly transient: boolean;
+
+  constructor(
+    sourceType: SourceType,
+    message: string,
+    options?: { cause?: Error; transient?: boolean },
+  ) {
+    super(`[${sourceType}] ${message}`);
+    this.name = "WorkspaceProvisionError";
+    this.sourceType = sourceType;
+    this.cause = options?.cause;
+    this.transient = options?.transient ?? false;
+  }
+}
+
+/**
+ * Abstraction for executing commands inside a workspace.
+ *
+ * In local mode, commands run via child_process. In cloud mode (Phase 3),
+ * commands route through the Daytona sandbox proxy.
+ *
+ * When `platformDir` is set, paths under `.stigmer/` are transparently
+ * routed to the platform directory instead of the workspace root. This
+ * keeps platform files (skills, inputs) physically separate from the
+ * user's workspace while presenting a unified `.stigmer/` namespace to
+ * the agent.
+ */
+export interface WorkspaceBackend {
+  readonly rootDir: string;
+  readonly platformDir?: string;
+  execute(command: string, options?: { cwd?: string }): Promise<string>;
+  readFile(path: string): Promise<string>;
+  writeFile(path: string, content: string): Promise<void>;
+  writeFileBuffer(path: string, content: Buffer): Promise<void>;
+  exists(path: string): Promise<boolean>;
+}

package/src/shared/zip-extract.ts

@@ -0,0 +1,193 @@
+/**
+ * Minimal, dependency-free ZIP archive parser.
+ *
+ * Handles the local file header format, supporting stored (method 0) and
+ * deflated (method 8) entries. Returns parsed entries as path + content
+ * pairs — consumers bring their own write mechanism (WorkspaceBackend,
+ * node:fs, etc.).
+ *
+ * Extracted from skill-writer.ts so both the deep-agent and Cursor
+ * harnesses can share the same ZIP parsing logic without coupling to
+ * a specific workspace abstraction.
+ */
+
+import { createInflateRaw } from "node:zlib";
+
+// ─── Public API ──────────────────────────────────────────────────────────
+
+export interface ZipFileEntry {
+  /** Relative path within the archive (forward-slash separated). */
+  readonly path: string;
+  /** Decoded text content of the file. */
+  readonly content: string;
+}
+
+/**
+ * Parse and decompress all file entries from a ZIP archive.
+ *
+ * Directory entries are always skipped. An optional `exclude` list filters
+ * entries whose filename (basename or full path) matches any excluded name.
+ *
+ * Returns an empty array for empty, truncated, or non-ZIP input rather
+ * than throwing — callers treat missing artifacts as non-fatal.
+ */
+export async function extractZipFileEntries(
+  zipBytes: Uint8Array,
+  options?: { exclude?: readonly string[] },
+): Promise<ZipFileEntry[]> {
+  if (zipBytes.length < 4) return [];
+
+  let entries: ZipEntry[];
+  try {
+    entries = parseZipEntries(zipBytes);
+  } catch {
+    return [];
+  }
+
+  const excludeSet = new Set(options?.exclude ?? []);
+  const results: ZipFileEntry[] = [];
+
+  for (const entry of entries) {
+    if (entry.isDirectory) continue;
+    if (isExcluded(entry.name, excludeSet)) continue;
+
+    const content = await decompressEntry(entry);
+    results.push({ path: entry.name, content });
+  }
+
+  return results;
+}
+
+// ─── Internals ───────────────────────────────────────────────────────────
+
+interface ZipEntry {
+  name: string;
+  isDirectory: boolean;
+  compressedData: Uint8Array;
+  compressionMethod: number;
+  uncompressedSize: number;
+}
+
+function isExcluded(name: string, excludeSet: ReadonlySet<string>): boolean {
+  if (excludeSet.size === 0) return false;
+  if (excludeSet.has(name)) return true;
+
+  const basename = name.includes("/") ? name.slice(name.lastIndexOf("/") + 1) : name;
+  return excludeSet.has(basename);
+}
+
+function parseZipEntries(data: Uint8Array): ZipEntry[] {
+  const entries: ZipEntry[] = [];
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  let offset = 0;
+
+  while (offset < data.length - 4) {
+    const signature = view.getUint32(offset, true);
+    if (signature !== 0x04034b50) break; // Local file header signature
+
+    const generalFlags = view.getUint16(offset + 6, true);
+    const hasDataDescriptor = (generalFlags & 0x08) !== 0;
+    const compressionMethod = view.getUint16(offset + 8, true);
+    let compressedSize = view.getUint32(offset + 18, true);
+    let uncompressedSize = view.getUint32(offset + 22, true);
+    const fileNameLength = view.getUint16(offset + 26, true);
+    const extraFieldLength = view.getUint16(offset + 28, true);
+
+    const fileNameStart = offset + 30;
+    const fileName = new TextDecoder().decode(
+      data.subarray(fileNameStart, fileNameStart + fileNameLength),
+    );
+
+    const dataStart = fileNameStart + fileNameLength + extraFieldLength;
+
+    if (hasDataDescriptor && compressedSize === 0) {
+      const sizes = findDataDescriptor(data, view, dataStart, compressionMethod);
+      compressedSize = sizes.compressedSize;
+      uncompressedSize = sizes.uncompressedSize;
+    }
+
+    const compressedData = data.subarray(dataStart, dataStart + compressedSize);
+
+    entries.push({
+      name: fileName,
+      isDirectory: fileName.endsWith("/"),
+      compressedData,
+      compressionMethod,
+      uncompressedSize,
+    });
+
+    let nextOffset = dataStart + compressedSize;
+    if (hasDataDescriptor) {
+      if (nextOffset + 4 <= data.length && view.getUint32(nextOffset, true) === 0x08074b50) {
+        nextOffset += 16; // signature(4) + crc(4) + compressedSize(4) + uncompressedSize(4)
+      } else {
+        nextOffset += 12; // crc(4) + compressedSize(4) + uncompressedSize(4)
+      }
+    }
+    offset = nextOffset;
+  }
+
+  return entries;
+}
+
+/**
+ * Scan forward from dataStart to find the data descriptor that contains
+ * the actual compressed and uncompressed sizes. Looks for either the
+ * optional signature 0x08074b50 or falls back to scanning the central
+ * directory for the matching entry.
+ */
+function findDataDescriptor(
+  data: Uint8Array,
+  view: DataView,
+  dataStart: number,
+  _compressionMethod: number,
+): { compressedSize: number; uncompressedSize: number } {
+  for (let pos = dataStart; pos < data.length - 16; pos++) {
+    const sig = view.getUint32(pos, true);
+    if (sig === 0x08074b50) {
+      return {
+        compressedSize: view.getUint32(pos + 8, true),
+        uncompressedSize: view.getUint32(pos + 12, true),
+      };
+    }
+    if (sig === 0x04034b50 || sig === 0x02014b50) {
+      const descStart = pos - 12;
+      if (descStart >= dataStart) {
+        return {
+          compressedSize: view.getUint32(descStart + 4, true),
+          uncompressedSize: view.getUint32(descStart + 8, true),
+        };
+      }
+      break;
+    }
+  }
+  for (let pos = dataStart; pos < data.length - 4; pos++) {
+    const sig = view.getUint32(pos, true);
+    if (sig === 0x04034b50 || sig === 0x02014b50 || sig === 0x08074b50) {
+      const compressedSize = sig === 0x08074b50
+        ? view.getUint32(pos + 8, true)
+        : pos - dataStart;
+      return { compressedSize, uncompressedSize: 0 };
+    }
+  }
+  return { compressedSize: data.length - dataStart, uncompressedSize: 0 };
+}
+
+async function decompressEntry(entry: ZipEntry): Promise<string> {
+  if (entry.compressionMethod === 0) {
+    return new TextDecoder().decode(entry.compressedData);
+  }
+
+  if (entry.compressionMethod === 8) {
+    return new Promise<string>((resolve, reject) => {
+      const inflate = createInflateRaw();
+      const chunks: Buffer[] = [];
+      inflate.on("data", (chunk: Buffer) => chunks.push(chunk));
+      inflate.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+      inflate.on("error", reject);
+      inflate.end(Buffer.from(entry.compressedData));
+    });
+  }
+
+  throw new Error(`Unsupported ZIP compression method: ${entry.compressionMethod}`);
+}