@stigmer/runner 3.0.1

package/src/shared/workspace/local-backend.ts

@@ -0,0 +1,140 @@
+/**
+ * Local filesystem workspace backend.
+ *
+ * Executes commands via child_process and reads/writes files directly.
+ * Used in local mode and as the default for Phase 2. The remote (Daytona
+ * sandbox) backend will be added in Phase 3.
+ *
+ * When `platformDir` is provided, paths under `.stigmer/` are
+ * transparently routed to the platform directory. The agent sees a
+ * unified namespace; the workspace directory is never polluted.
+ */
+
+import { execFile } from "node:child_process";
+import { readFile, writeFile, access, mkdir } from "node:fs/promises";
+import { join, isAbsolute, resolve, relative } from "node:path";
+import type { WorkspaceBackend } from "./types.js";
+import {
+  classifyPlatformPath,
+  resolvePlatformCommand,
+  STIGMER_PLATFORM_DIR_ENV,
+} from "./platform-mount.js";
+
+export class LocalWorkspaceBackend implements WorkspaceBackend {
+  readonly rootDir: string;
+  readonly platformDir?: string;
+
+  constructor(rootDir: string, platformDir?: string) {
+    this.rootDir = rootDir;
+    this.platformDir = platformDir;
+  }
+
+  async execute(command: string, options?: { cwd?: string }): Promise<string> {
+    const cwd = options?.cwd
+      ? (isAbsolute(options.cwd) ? options.cwd : join(this.rootDir, options.cwd))
+      : this.rootDir;
+
+    let resolvedCommand = command;
+    const env: Record<string, string> | undefined = this.platformDir
+      ? { ...process.env as Record<string, string>, [STIGMER_PLATFORM_DIR_ENV]: this.platformDir }
+      : undefined;
+
+    if (this.platformDir) {
+      resolvedCommand = resolvePlatformCommand(command);
+    }
+
+    return new Promise((resolve, reject) => {
+      execFile(
+        "sh",
+        ["-c", resolvedCommand],
+        { cwd, maxBuffer: 10 * 1024 * 1024, ...(env ? { env } : {}) },
+        (err, stdout, stderr) => {
+          if (err) {
+            reject(new Error(`Command failed: ${command}\n${stderr || err.message}`));
+          } else {
+            resolve(stdout);
+          }
+        },
+      );
+    });
+  }
+
+  async readFile(path: string): Promise<string> {
+    const full = this.resolvePath(path);
+    return readFile(full, "utf-8");
+  }
+
+  async writeFile(path: string, content: string): Promise<void> {
+    const full = this.resolvePath(path);
+    await this.ensureParentDir(path, full);
+    await writeFile(full, content, "utf-8");
+  }
+
+  async writeFileBuffer(path: string, content: Buffer): Promise<void> {
+    const full = this.resolvePath(path);
+    await this.ensureParentDir(path, full);
+    await writeFile(full, content);
+  }
+
+  private async ensureParentDir(relativePath: string, resolvedPath: string): Promise<void> {
+    if (this.platformDir && !isAbsolute(relativePath)) {
+      const { isPlatform } = classifyPlatformPath(relativePath);
+      if (isPlatform) {
+        const parentDir = join(resolvedPath, "..");
+        await mkdir(parentDir, { recursive: true });
+      }
+    }
+  }
+
+  async exists(path: string): Promise<boolean> {
+    const full = this.resolvePath(path);
+    try {
+      await access(full);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Resolve a relative path to an absolute filesystem path, routing
+   * `.stigmer/` paths to `platformDir` when configured.
+   *
+   * Absolute paths are returned as-is (backward compat with existing
+   * callers that pass absolute paths).
+   *
+   * Platform-routed paths are checked for path traversal — a remainder
+   * that escapes `platformDir` via `..` components is rejected.
+   */
+  private resolvePath(path: string): string {
+    if (isAbsolute(path)) return path;
+
+    if (this.platformDir) {
+      const { isPlatform, remainder } = classifyPlatformPath(path);
+      if (isPlatform) {
+        const resolved = resolve(this.platformDir, remainder);
+        const normalizedPlatform = resolve(this.platformDir);
+        if (!resolved.startsWith(normalizedPlatform + "/") && resolved !== normalizedPlatform) {
+          throw new Error(
+            `Path traversal detected: '${path}' resolves outside platform directory`,
+          );
+        }
+        return resolved;
+      }
+    }
+
+    return join(this.rootDir, path);
+  }
+}
+
+/**
+ * Create and initialize a local workspace backend. Ensures the root
+ * directory exists before returning.
+ */
+export async function initializeLocalWorkspace(
+  rootDir: string,
+  platformDir?: string,
+): Promise<LocalWorkspaceBackend> {
+  await mkdir(rootDir, { recursive: true });
+  return new LocalWorkspaceBackend(rootDir, platformDir);
+}

package/src/shared/workspace/platform-dir.ts

@@ -0,0 +1,38 @@
+/**
+ * Session-scoped platform directory management.
+ *
+ * Each agent execution session gets a dedicated platform directory at
+ * `~/.stigmer/sessions/{sessionId}/platform/` for storing skills,
+ * attachments, and other platform-managed files. This directory is
+ * separate from the user's workspace — the agent sees it via the
+ * `.stigmer/` virtual namespace through WorkspaceBackend routing.
+ *
+ * This module replaces the duplicated `getPlatformDir` helpers in
+ * execute-cursor/skill-resolver.ts and execute-cursor/attachment-resolver.ts.
+ */
+
+import { join } from "node:path";
+import { mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+
+/**
+ * Compute the platform directory path for a session.
+ *
+ * Pure function — does not create the directory or perform I/O.
+ */
+export function getPlatformDir(sessionId: string): string {
+  const home = process.env.HOME || process.env.USERPROFILE || homedir();
+  return join(home, ".stigmer", "sessions", sessionId, "platform");
+}
+
+/**
+ * Ensure the platform directory exists and return its path.
+ *
+ * Creates the full directory tree if it does not exist. Idempotent —
+ * safe to call multiple times for the same session.
+ */
+export async function ensurePlatformDir(sessionId: string): Promise<string> {
+  const dir = getPlatformDir(sessionId);
+  await mkdir(dir, { recursive: true });
+  return dir;
+}

package/src/shared/workspace/platform-mount.ts

@@ -0,0 +1,190 @@
+/**
+ * Virtual platform mount — path classification and display humanization
+ * for the `.stigmer/` namespace.
+ *
+ * The platform owns the `.stigmer/` namespace inside the agent's virtual
+ * view of the workspace. Platform files (skills, inputs) physically live
+ * in an external `platformDir` that is separate from the workspace
+ * `rootDir`. Backend path-resolution methods call `classifyPlatformPath`
+ * to decide whether a given path targets the platform mount or the
+ * workspace, keeping the routing decision in a single place.
+ *
+ * All functions in this module are **pure** — no I/O, no side effects.
+ * They operate exclusively on strings.
+ *
+ * See Python reference: graphton/core/backends/platform_mount.py (AD-01 v3).
+ */
+
+import { dirname } from "node:path";
+
+/** Prefix that identifies paths targeting the virtual platform mount. */
+export const PLATFORM_PREFIX = ".stigmer/";
+
+/** Directory name used in listings and equality checks. */
+export const PLATFORM_DIR_NAME = ".stigmer";
+
+/**
+ * Environment variable injected into `execute()` calls so shell commands
+ * can access platform files via `$STIGMER_PLATFORM_DIR/skills/…`.
+ */
+export const STIGMER_PLATFORM_DIR_ENV = "STIGMER_PLATFORM_DIR";
+
+/**
+ * Matches `$STIGMER_PLATFORM_DIR` and `${STIGMER_PLATFORM_DIR}` in
+ * display strings. Brace form is tried first so the replacement does not
+ * leave stray braces. The negative lookahead on the bare-dollar form
+ * prevents matching `$STIGMER_PLATFORM_DIR_OTHER` as a false positive.
+ */
+const PLATFORM_ENV_RE = new RegExp(
+  `\\$\\{${STIGMER_PLATFORM_DIR_ENV}\\}`
+  + `|\\$${STIGMER_PLATFORM_DIR_ENV}(?![A-Za-z0-9_])`,
+  "g",
+);
+
+/**
+ * Matches `.stigmer` in shell commands when it appears as a standalone
+ * path component (e.g. `.stigmer/skills/…`), not as part of a longer
+ * name (`my.stigmer`) or a subdirectory (`foo/.stigmer`).
+ */
+const STIGMER_DIR_CMD_RE = /(?<!\w)(?<!\/)\.stigmer(?![a-zA-Z0-9_])/g;
+
+/**
+ * Classify whether `relPath` targets the virtual platform mount.
+ *
+ * Strips leading slashes before checking so that absolute-looking paths
+ * (`/.stigmer/skills/…`) are handled identically to relative ones.
+ *
+ * @returns An object with `isPlatform` (true when path falls under
+ *   `.stigmer/`) and `remainder` (the path relative to whichever root
+ *   applies — `platformDir` when platform, `rootDir` when workspace).
+ */
+export function classifyPlatformPath(relPath: string): {
+  isPlatform: boolean;
+  remainder: string;
+} {
+  const clean = relPath.replace(/^\/+/, "");
+
+  if (clean.startsWith(PLATFORM_PREFIX)) {
+    return { isPlatform: true, remainder: clean.slice(PLATFORM_PREFIX.length) };
+  }
+
+  if (clean === PLATFORM_DIR_NAME || clean === PLATFORM_DIR_NAME + "/") {
+    return { isPlatform: true, remainder: "" };
+  }
+
+  return { isPlatform: false, remainder: clean };
+}
+
+/**
+ * Replace platform environment-variable references with the user-facing
+ * `.stigmer` virtual-mount prefix.
+ *
+ * Intended for **display strings only** (approval previews, messages) —
+ * not for the actual command executed in the sandbox, where the shell
+ * must expand the real environment variable.
+ *
+ * Handles both `$STIGMER_PLATFORM_DIR` and `${STIGMER_PLATFORM_DIR}`.
+ */
+export function humanizePlatformRefs(text: string): string {
+  if (!text) return text;
+  return text.replace(PLATFORM_ENV_RE, PLATFORM_DIR_NAME);
+}
+
+/**
+ * Replace `.stigmer` virtual-mount references in a shell command with
+ * the `$STIGMER_PLATFORM_DIR` environment variable.
+ *
+ * The execute environment already has `STIGMER_PLATFORM_DIR` set, so
+ * the shell expands the variable at runtime.
+ *
+ * This is the inverse of `humanizePlatformRefs`: that function rewrites
+ * `$STIGMER_PLATFORM_DIR` → `.stigmer` for display, while this function
+ * rewrites `.stigmer` → `$STIGMER_PLATFORM_DIR` for execution.
+ *
+ * Callers **must** guard this behind a `platformDir != null` check to
+ * avoid replacing `.stigmer` when it is a real directory.
+ */
+export function resolvePlatformCommand(command: string): string {
+  if (!command) return command;
+  return command.replace(STIGMER_DIR_CMD_RE, `$${STIGMER_PLATFORM_DIR_ENV}`);
+}
+
+/**
+ * Replace absolute sandbox workspace paths with workspace-relative
+ * display paths.
+ *
+ * Intended for **display strings only** (approval previews, streamed
+ * messages) — not for the actual command executed in the sandbox.
+ *
+ * Performs three ordered replacements:
+ * 1. `workspaceRoot + "/"` → empty string (workspace-relative paths)
+ * 2. `workspaceRoot` (exact) → `"."` (the workspace root itself)
+ * 3. Sandbox home dir (parent of workspaceRoot) → `"~"` (paths outside
+ *    the workspace, e.g. `/home/daytona/.bashrc` → `~/.bashrc`)
+ *
+ * Returns `text` unchanged when `workspaceRoot` is empty.
+ */
+export function humanizeSandboxPaths(
+  text: string,
+  workspaceRoot: string,
+): string {
+  if (!text || !workspaceRoot) return text;
+
+  const wsRoot = workspaceRoot.replace(/\/+$/, "");
+
+  // 1) workspace_root + "/" → "" (relative paths)
+  text = text.replaceAll(wsRoot + "/", "");
+
+  // 2) bare workspace_root → "." (must run after slash-suffixed above)
+  text = text.replaceAll(wsRoot, ".");
+
+  // 3) sandbox home → "~" (parent of workspace root)
+  const sandboxHome = dirname(wsRoot);
+  if (sandboxHome && sandboxHome !== "/") {
+    text = text.replaceAll(sandboxHome + "/", "~/");
+    text = text.replaceAll(sandboxHome, "~");
+  }
+
+  return text;
+}
+
+/**
+ * Resolve agent environment-variable references to their values in a
+ * display string.
+ *
+ * Replaces `$KEY` and `${KEY}` with the corresponding value from
+ * `envVars` for every key that is **not** marked as secret.
+ *
+ * `$STIGMER_PLATFORM_DIR` is handled separately by
+ * `humanizePlatformRefs` and is always skipped here.
+ *
+ * Call this **after** `humanizePlatformRefs` so platform paths are
+ * humanized before general env-var resolution runs.
+ */
+export function resolveDisplayEnvVars(
+  text: string,
+  envVars: Record<string, string>,
+  secretKeys?: ReadonlySet<string>,
+): string {
+  if (!text || !envVars || Object.keys(envVars).length === 0) return text;
+
+  const secrets = secretKeys ?? new Set<string>();
+
+  for (const [key, value] of Object.entries(envVars)) {
+    if (key === STIGMER_PLATFORM_DIR_ENV) continue;
+    if (secrets.has(key)) continue;
+
+    const pattern = new RegExp(
+      `\\$\\{${escapeRegExp(key)}\\}`
+      + `|\\$${escapeRegExp(key)}(?![A-Za-z0-9_])`,
+      "g",
+    );
+    text = text.replace(pattern, value);
+  }
+
+  return text;
+}
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/shared/workspace/provisioner.ts

@@ -0,0 +1,150 @@
+/**
+ * Workspace provisioner — dispatches on WorkspaceSource proto type to
+ * populate a workspace directory.
+ *
+ * Supports three source variants:
+ * - git_repo: clone a repository
+ * - local_path: use an existing host directory
+ * - empty: create an empty workspace
+ *
+ * Multi-entry sessions provision each WorkspaceEntry into its own
+ * subdirectory of the workspace root.
+ *
+ * Phase 2 scope: local backend only. The remote (Daytona sandbox)
+ * backend will be added in Phase 3.
+ */
+
+import type { ProvisionResult, WorkspaceBackend } from "./types.js";
+import { SourceType, WorkspaceProvisionError } from "./types.js";
+import { provisionEmpty } from "./sources/empty.js";
+import { provisionLocalPath } from "./sources/local-path.js";
+import { provisionGit } from "./sources/git.js";
+
+const PROVISION_KEY_PREFIX = "WORKSPACE_PROVISION_";
+
+export interface WorkspaceEntry {
+  name: string;
+  source?: WorkspaceSource;
+}
+
+export interface WorkspaceSource {
+  source: { case: "gitRepo"; value: GitRepoSource }
+    | { case: "localPath"; value: LocalPathSource }
+    | { case: undefined; value?: undefined };
+}
+
+export interface GitRepoSource {
+  url: string;
+  branch?: string;
+}
+
+export interface LocalPathSource {
+  path: string;
+}
+
+export class WorkspaceProvisioner {
+  async provision(
+    workspaceSource: WorkspaceSource | undefined,
+    backend: WorkspaceBackend,
+    mergedEnv: Record<string, string>,
+    isLocalMode: boolean,
+    options?: {
+      targetSubdir?: string;
+      configureCredentials?: boolean;
+    },
+  ): Promise<ProvisionResult> {
+    const result = await this.dispatch(
+      workspaceSource, backend, mergedEnv, isLocalMode, options,
+    );
+
+    const prefixKeys = Object.keys(mergedEnv)
+      .filter(k => k.startsWith(PROVISION_KEY_PREFIX));
+
+    const allConsumed = mergeConsumedKeys(result.consumedKeys, prefixKeys);
+    if (allConsumed.length !== result.consumedKeys.length) {
+      return { ...result, consumedKeys: allConsumed };
+    }
+    return result;
+  }
+
+  async provisionAll(
+    entries: WorkspaceEntry[],
+    backend: WorkspaceBackend,
+    mergedEnv: Record<string, string>,
+    isLocalMode: boolean,
+    configureCredentials = false,
+  ): Promise<ProvisionResult[]> {
+    if (entries.length === 0) return [];
+
+    const useSubdirs = entries.length > 1;
+    const results: ProvisionResult[] = [];
+
+    for (const entry of entries) {
+      const targetSubdir = useSubdirs ? entry.name : undefined;
+      const result = await this.provision(
+        entry.source,
+        backend,
+        mergedEnv,
+        isLocalMode,
+        { targetSubdir, configureCredentials },
+      );
+      results.push({ ...result, entryName: entry.name });
+    }
+
+    return results;
+  }
+
+  private async dispatch(
+    workspaceSource: WorkspaceSource | undefined,
+    backend: WorkspaceBackend,
+    mergedEnv: Record<string, string>,
+    isLocalMode: boolean,
+    options?: {
+      targetSubdir?: string;
+      configureCredentials?: boolean;
+    },
+  ): Promise<ProvisionResult> {
+    if (!workspaceSource || !workspaceSource.source?.case) {
+      return provisionEmpty(backend);
+    }
+
+    switch (workspaceSource.source.case) {
+      case "gitRepo": {
+        const gitSource = workspaceSource.source.value;
+        return provisionGit({
+          url: gitSource.url,
+          branch: gitSource.branch,
+          backend,
+          envVars: mergedEnv,
+          isLocalMode,
+          targetSubdir: options?.targetSubdir,
+          configureCredentials: options?.configureCredentials,
+        });
+      }
+
+      case "localPath": {
+        const localSource = workspaceSource.source.value;
+        return provisionLocalPath({
+          path: localSource.path,
+          isLocalMode,
+          targetSubdir: options?.targetSubdir,
+          backendRootDir: options?.targetSubdir ? backend.rootDir : undefined,
+        });
+      }
+
+      default:
+        return provisionEmpty(backend);
+    }
+  }
+}
+
+function mergeConsumedKeys(
+  sourceKeys: readonly string[],
+  prefixKeys: string[],
+): string[] {
+  if (prefixKeys.length === 0) return [...sourceKeys];
+  const merged = new Map<string, true>();
+  for (const k of sourceKeys) merged.set(k, true);
+  for (const k of prefixKeys) merged.set(k, true);
+  return [...merged.keys()];
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Empty workspace source — the default when no WorkspaceSource is configured.
+ *
+ * The workspace directory already exists (created by initializeLocalWorkspace).
+ * This handler simply records the fact and returns the existing root.
+ */
+
+import { SourceType, type ProvisionResult, type WorkspaceBackend } from "../types.js";
+
+export function provisionEmpty(backend: WorkspaceBackend): ProvisionResult {
+  return {
+    rootDir: backend.rootDir,
+    sourceType: SourceType.EMPTY,
+    consumedKeys: [],
+    workspaceDescription:
+      "Your workspace is empty. " +
+      "Create files and directories as needed for your task.",
+    entryName: "",
+  };
+}