@stigmer/runner 3.0.1

package/dist/shared/subagent-gate.js

@@ -0,0 +1,93 @@
+/**
+ * Concurrency limiter for sub-agent execution.
+ *
+ * Wraps sub-agent runnables with a Promise-based semaphore that
+ * limits the number of concurrent sub-agent invocations. When the
+ * limit is reached, new invocations are rejected immediately with
+ * an error-shaped message (non-blocking) rather than queuing.
+ *
+ * This matches the Python `SubAgentGate` behavior: protect the
+ * parent agent's resources by hard-capping concurrency, and let
+ * the LLM adapt when a sub-agent cannot be started.
+ */
+import { RunnableLambda } from "@langchain/core/runnables";
+const DEFAULT_MAX_CONCURRENT = 3;
+export class SubAgentGate {
+    max;
+    active = 0;
+    constructor(options = {}) {
+        this.max = options.maxConcurrent ?? DEFAULT_MAX_CONCURRENT;
+        if (this.max <= 0) {
+            throw new Error(`maxConcurrent must be positive, got ${this.max}`);
+        }
+    }
+    get activeCount() {
+        return this.active;
+    }
+    get maxConcurrent() {
+        return this.max;
+    }
+    get hasCapacity() {
+        return this.active < this.max;
+    }
+    /**
+     * Wrap a sub-agent's invoke function with concurrency gating.
+     *
+     * Returns a new function that checks capacity before invoking.
+     * If no capacity, returns an error-shaped response immediately.
+     */
+    wrap(invoke, name) {
+        return async (input, config) => {
+            if (!this.hasCapacity) {
+                console.warn(`[SubAgentGate] Rejected '${name}': ${this.active}/${this.max} slots occupied`);
+                return {
+                    messages: [{
+                            role: "assistant",
+                            content: `Sub-agent '${name}' was NOT started — the maximum of ` +
+                                `${this.max} concurrent sub-agents are already running. ` +
+                                `Wait for an active sub-agent to complete before starting another, ` +
+                                `or proceed without this sub-agent.`,
+                        }],
+                };
+            }
+            this.active++;
+            try {
+                return await invoke(input, config);
+            }
+            finally {
+                this.active--;
+            }
+        };
+    }
+    /**
+     * Wrap a sub-agent Runnable for use as `CompiledSubAgent.runnable`.
+     *
+     * Returns a `RunnableLambda` that checks capacity before delegating
+     * to the underlying runnable. When at capacity, returns an error-shaped
+     * response that deepagents surfaces to the parent agent as the task result.
+     */
+    wrapRunnable(runnable, name) {
+        return RunnableLambda.from(async (input, config) => {
+            if (!this.hasCapacity) {
+                console.warn(`[SubAgentGate] Rejected '${name}': ${this.active}/${this.max} slots occupied`);
+                return {
+                    messages: [{
+                            role: "assistant",
+                            content: `Sub-agent '${name}' was NOT started — the maximum of ` +
+                                `${this.max} concurrent sub-agents are already running. ` +
+                                `Wait for an active sub-agent to complete before starting another, ` +
+                                `or proceed without this sub-agent.`,
+                        }],
+                };
+            }
+            this.active++;
+            try {
+                return await runnable.invoke(input, config);
+            }
+            finally {
+                this.active--;
+            }
+        });
+    }
+}
+//# sourceMappingURL=subagent-gate.js.map

package/dist/shared/subagent-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-gate.js","sourceRoot":"","sources":["../../src/shared/subagent-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,cAAc,EAAuB,MAAM,2BAA2B,CAAC;AAEhF,MAAM,sBAAsB,GAAG,CAAC,CAAC;AAMjC,MAAM,OAAO,YAAY;IACN,GAAG,CAAS;IACrB,MAAM,GAAG,CAAC,CAAC;IAEnB,YAAY,UAA+B,EAAE;QAC3C,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,aAAa,IAAI,sBAAsB,CAAC;QAC3D,IAAI,IAAI,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,uCAAuC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QACrE,CAAC;IACH,CAAC;IAED,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,GAAG,CAAC;IAClB,CAAC;IAED,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC;IAChC,CAAC;IAED;;;;;OAKG;IACH,IAAI,CACF,MAA6E,EAC7E,IAAY;QAEZ,OAAO,KAAK,EAAE,KAAa,EAAE,MAAgC,EAAoB,EAAE;YACjF,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;gBACtB,OAAO,CAAC,IAAI,CACV,4BAA4B,IAAI,MAAM,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,GAAG,iBAAiB,CAC/E,CAAC;gBACF,OAAO;oBACL,QAAQ,EAAE,CAAC;4BACT,IAAI,EAAE,WAAW;4BACjB,OAAO,EACL,cAAc,IAAI,qCAAqC;gCACvD,GAAG,IAAI,CAAC,GAAG,8CAA8C;gCACzD,oEAAoE;gCACpE,oCAAoC;yBACvC,CAAC;iBACQ,CAAC;YACf,CAAC;YAED,IAAI,CAAC,MAAM,EAAE,CAAC;YACd,IAAI,CAAC;gBACH,OAAO,MAAM,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YACrC,CAAC;oBAAS,CAAC;gBACT,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,CAAC;QACH,CAAC,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,YAAY,CACV,QAAkF,EAClF,IAAY;QAEZ,OAAO,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,KAAa,EAAE,MAAuB,EAAoB,EAAE;YAC5F,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;gBACtB,OAAO,CAAC,IAAI,CACV,4BAA4B,IAAI,MAAM,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,GAAG,iBAAiB,CAC/E,CAAC;gBACF,OAAO;oBACL,QAAQ,EAAE,CAAC;4BACT,IAAI,EAAE,WAAW;4BACjB,OAAO,EACL,cAAc,IAAI,qCAAqC;gCACvD,GAAG,IAAI,CAAC,GAAG,8CAA8C;gCACzD,oEAAoE;gCACpE,oCAAoC;yBACvC,CAAC;iBACQ,CAAC;YACf,CAAC;YAED,IAAI,CAAC,MAAM,EAAE,CAAC;YACd,IAAI,CAAC;gBACH,OAAO,MAAM,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YAC9C,CAAC;oBAAS,CAAC;gBACT,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/shared/tool-kind.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Harness-agnostic tool classification for the runner.
+ *
+ * Both harnesses emit engine-specific tool names — the native (deepagents)
+ * harness uses snake_case (edit_file, execute, grep), the Cursor harness uses
+ * PascalCase (StrReplace, Shell, Grep). This module is the single place that
+ * maps a tool name to the wire-level ToolKind, so every client renders a tool
+ * the same way regardless of which harness produced it.
+ *
+ * The SDK fallback resolver and the Go CLI mirror this mapping. The shared,
+ * machine-checked contract is test/fixtures/tool-view/classification.json — keep
+ * this table and that fixture in lockstep.
+ */
+import { ToolKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+/**
+ * Classifies a tool call into its harness-agnostic ToolKind.
+ *
+ * Built-in names are matched first; any unrecognized name with a non-empty
+ * mcpServerSlug is an MCP tool; everything else is UNSPECIFIED (clients fall
+ * back to a name lookup, so this is never worse than no classification).
+ */
+export declare function classifyTool(name: string, mcpServerSlug?: string): ToolKind;

package/dist/shared/tool-kind.js

@@ -0,0 +1,79 @@
+/**
+ * Harness-agnostic tool classification for the runner.
+ *
+ * Both harnesses emit engine-specific tool names — the native (deepagents)
+ * harness uses snake_case (edit_file, execute, grep), the Cursor harness uses
+ * PascalCase (StrReplace, Shell, Grep). This module is the single place that
+ * maps a tool name to the wire-level ToolKind, so every client renders a tool
+ * the same way regardless of which harness produced it.
+ *
+ * The SDK fallback resolver and the Go CLI mirror this mapping. The shared,
+ * machine-checked contract is test/fixtures/tool-view/classification.json — keep
+ * this table and that fixture in lockstep.
+ */
+import { ToolKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+// Bare tool name -> ToolKind, covering both harness naming conventions. A name
+// found here is a built-in and wins over a non-empty mcp_server_slug (an MCP
+// server is not expected to shadow a built-in name; matching the legacy resolver).
+const TOOL_NAME_TO_KIND = new Map([
+    ["read", ToolKind.FILE_READ],
+    ["read_file", ToolKind.FILE_READ],
+    ["Read", ToolKind.FILE_READ],
+    ["write", ToolKind.FILE_WRITE],
+    ["write_file", ToolKind.FILE_WRITE],
+    ["create_file", ToolKind.FILE_WRITE],
+    ["overwrite_file", ToolKind.FILE_WRITE],
+    ["Write", ToolKind.FILE_WRITE],
+    ["edit", ToolKind.FILE_EDIT],
+    ["edit_file", ToolKind.FILE_EDIT],
+    ["str_replace_editor", ToolKind.FILE_EDIT],
+    ["StrReplace", ToolKind.FILE_EDIT],
+    ["EditNotebook", ToolKind.FILE_EDIT],
+    ["delete", ToolKind.FILE_DELETE],
+    ["delete_file", ToolKind.FILE_DELETE],
+    ["remove_file", ToolKind.FILE_DELETE],
+    ["Delete", ToolKind.FILE_DELETE],
+    ["shell", ToolKind.SHELL],
+    ["bash", ToolKind.SHELL],
+    ["execute", ToolKind.SHELL],
+    ["execute_command", ToolKind.SHELL],
+    ["run_command", ToolKind.SHELL],
+    ["terminal", ToolKind.SHELL],
+    ["Shell", ToolKind.SHELL],
+    ["grep", ToolKind.SEARCH],
+    ["glob", ToolKind.SEARCH],
+    ["search", ToolKind.SEARCH],
+    ["ripgrep", ToolKind.SEARCH],
+    ["find_files", ToolKind.SEARCH],
+    ["Grep", ToolKind.SEARCH],
+    ["Glob", ToolKind.SEARCH],
+    ["SemanticSearch", ToolKind.SEARCH],
+    ["ls", ToolKind.LIST],
+    ["list_directory", ToolKind.LIST],
+    ["WebFetch", ToolKind.FETCH],
+    ["WebSearch", ToolKind.WEB_SEARCH],
+    ["think", ToolKind.THINK],
+    ["write_todos", ToolKind.TODO],
+    ["updateTodos", ToolKind.TODO],
+    ["TodoWrite", ToolKind.TODO],
+    ["task", ToolKind.SUBAGENT],
+    ["Task", ToolKind.SUBAGENT],
+]);
+/**
+ * Classifies a tool call into its harness-agnostic ToolKind.
+ *
+ * Built-in names are matched first; any unrecognized name with a non-empty
+ * mcpServerSlug is an MCP tool; everything else is UNSPECIFIED (clients fall
+ * back to a name lookup, so this is never worse than no classification).
+ */
+export function classifyTool(name, mcpServerSlug) {
+    const builtin = TOOL_NAME_TO_KIND.get(name);
+    if (builtin !== undefined) {
+        return builtin;
+    }
+    if (mcpServerSlug && mcpServerSlug.length > 0) {
+        return ToolKind.MCP;
+    }
+    return ToolKind.UNSPECIFIED;
+}
+//# sourceMappingURL=tool-kind.js.map

package/dist/shared/tool-kind.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-kind.js","sourceRoot":"","sources":["../../src/shared/tool-kind.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,8DAA8D,CAAC;AAExF,+EAA+E;AAC/E,6EAA6E;AAC7E,mFAAmF;AACnF,MAAM,iBAAiB,GAAkC,IAAI,GAAG,CAAC;IAC/D,CAAC,MAAM,EAAE,QAAQ,CAAC,SAAS,CAAC;IAC5B,CAAC,WAAW,EAAE,QAAQ,CAAC,SAAS,CAAC;IACjC,CAAC,MAAM,EAAE,QAAQ,CAAC,SAAS,CAAC;IAE5B,CAAC,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC;IAC9B,CAAC,YAAY,EAAE,QAAQ,CAAC,UAAU,CAAC;IACnC,CAAC,aAAa,EAAE,QAAQ,CAAC,UAAU,CAAC;IACpC,CAAC,gBAAgB,EAAE,QAAQ,CAAC,UAAU,CAAC;IACvC,CAAC,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC;IAE9B,CAAC,MAAM,EAAE,QAAQ,CAAC,SAAS,CAAC;IAC5B,CAAC,WAAW,EAAE,QAAQ,CAAC,SAAS,CAAC;IACjC,CAAC,oBAAoB,EAAE,QAAQ,CAAC,SAAS,CAAC;IAC1C,CAAC,YAAY,EAAE,QAAQ,CAAC,SAAS,CAAC;IAClC,CAAC,cAAc,EAAE,QAAQ,CAAC,SAAS,CAAC;IAEpC,CAAC,QAAQ,EAAE,QAAQ,CAAC,WAAW,CAAC;IAChC,CAAC,aAAa,EAAE,QAAQ,CAAC,WAAW,CAAC;IACrC,CAAC,aAAa,EAAE,QAAQ,CAAC,WAAW,CAAC;IACrC,CAAC,QAAQ,EAAE,QAAQ,CAAC,WAAW,CAAC;IAEhC,CAAC,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC;IACzB,CAAC,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC;IACxB,CAAC,SAAS,EAAE,QAAQ,CAAC,KAAK,CAAC;IAC3B,CAAC,iBAAiB,EAAE,QAAQ,CAAC,KAAK,CAAC;IACnC,CAAC,aAAa,EAAE,QAAQ,CAAC,KAAK,CAAC;IAC/B,CAAC,UAAU,EAAE,QAAQ,CAAC,KAAK,CAAC;IAC5B,CAAC,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC;IAEzB,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC;IACzB,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC;IACzB,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC;IAC3B,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC;IAC5B,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC;IAC/B,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC;IACzB,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC;IACzB,CAAC,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC;IAEnC,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC;IACrB,CAAC,gBAAgB,EAAE,QAAQ,CAAC,IAAI,CAAC;IAEjC,CAAC,UAAU,EAAE,QAAQ,CAAC,KAAK,CAAC;IAC5B,CAAC,WAAW,EAAE,QAAQ,CAAC,UAAU,CAAC;IAElC,CAAC,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC;IAEzB,CAAC,aAAa,EAAE,QAAQ,CAAC,IAAI,CAAC;IAC9B,CAAC,aAAa,EAAE,QAAQ,CAAC,IAAI,CAAC;IAC9B,CAAC,WAAW,EAAE,QAAQ,CAAC,IAAI,CAAC;IAE5B,CAAC,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC;IAC3B,CAAC,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC;CAC5B,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,aAAsB;IAC/D,MAAM,OAAO,GAAG,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,IAAI,aAAa,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9C,OAAO,QAAQ,CAAC,GAAG,CAAC;IACtB,CAAC;IACD,OAAO,QAAQ,CAAC,WAAW,CAAC;AAC9B,CAAC"}

package/dist/shared/workspace/file-tree.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Generates a concise workspace file tree for system prompts.
+ *
+ * Produces a markdown-formatted directory listing that helps the agent
+ * understand the project structure. Respects .gitignore when present
+ * and caps depth to keep the system prompt manageable.
+ */
+export interface FileTreeOptions {
+    headingLevel?: number;
+    maxDepth?: number;
+    maxEntries?: number;
+}
+export declare function buildWorkspaceFileTree(rootDir: string, options?: FileTreeOptions): string | null;

package/dist/shared/workspace/file-tree.js

@@ -0,0 +1,101 @@
+/**
+ * Generates a concise workspace file tree for system prompts.
+ *
+ * Produces a markdown-formatted directory listing that helps the agent
+ * understand the project structure. Respects .gitignore when present
+ * and caps depth to keep the system prompt manageable.
+ */
+import { readdirSync, statSync, readFileSync } from "node:fs";
+import { join, relative, basename } from "node:path";
+const MAX_DEPTH = 4;
+const MAX_ENTRIES = 200;
+const DEFAULT_IGNORES = new Set([
+    "node_modules",
+    ".git",
+    "__pycache__",
+    ".venv",
+    ".mypy_cache",
+    ".ruff_cache",
+    ".pytest_cache",
+    "dist",
+    "build",
+    ".next",
+    ".stigmer",
+    ".cursor",
+]);
+export function buildWorkspaceFileTree(rootDir, options) {
+    const headingLevel = options?.headingLevel ?? 3;
+    const maxDepth = options?.maxDepth ?? MAX_DEPTH;
+    const maxEntries = options?.maxEntries ?? MAX_ENTRIES;
+    const gitignorePatterns = loadGitignore(rootDir);
+    const lines = [];
+    let count = 0;
+    function walk(dir, depth, prefix) {
+        if (depth > maxDepth)
+            return false;
+        let entries;
+        try {
+            entries = readdirSync(dir).sort();
+        }
+        catch {
+            return false;
+        }
+        for (const entry of entries) {
+            if (count >= maxEntries)
+                return true;
+            if (DEFAULT_IGNORES.has(entry))
+                continue;
+            if (entry.startsWith(".") && entry !== ".env.example")
+                continue;
+            const fullPath = join(dir, entry);
+            const rel = relative(rootDir, fullPath);
+            if (isGitignored(rel, gitignorePatterns))
+                continue;
+            let isDir = false;
+            try {
+                isDir = statSync(fullPath).isDirectory();
+            }
+            catch {
+                continue;
+            }
+            lines.push(`${prefix}${isDir ? `${entry}/` : entry}`);
+            count++;
+            if (isDir) {
+                const truncated = walk(fullPath, depth + 1, prefix + "  ");
+                if (truncated)
+                    return true;
+            }
+        }
+        return false;
+    }
+    const truncated = walk(rootDir, 0, "");
+    if (lines.length === 0)
+        return null;
+    const heading = "#".repeat(headingLevel);
+    const tree = lines.join("\n");
+    const suffix = truncated ? "\n  ... (truncated)" : "";
+    return `${heading} Project Structure\n\n\`\`\`\n${tree}${suffix}\n\`\`\``;
+}
+function loadGitignore(rootDir) {
+    try {
+        const content = readFileSync(join(rootDir, ".gitignore"), "utf-8");
+        return content
+            .split("\n")
+            .map(l => l.trim())
+            .filter(l => l && !l.startsWith("#"));
+    }
+    catch {
+        return [];
+    }
+}
+function isGitignored(relativePath, patterns) {
+    const name = basename(relativePath);
+    for (const pattern of patterns) {
+        if (pattern.endsWith("/") && name === pattern.slice(0, -1))
+            return true;
+        if (name === pattern)
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=file-tree.js.map

package/dist/shared/workspace/file-tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-tree.js","sourceRoot":"","sources":["../../../src/shared/workspace/file-tree.ts"],"names":[],"mappings":"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"}

package/dist/shared/workspace/local-backend.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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 type { WorkspaceBackend } from "./types.js";
+export declare class LocalWorkspaceBackend implements WorkspaceBackend {
+    readonly rootDir: string;
+    readonly platformDir?: string;
+    constructor(rootDir: string, 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>;
+    private ensureParentDir;
+    exists(path: string): Promise<boolean>;
+    /**
+     * 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;
+}
+/**
+ * Create and initialize a local workspace backend. Ensures the root
+ * directory exists before returning.
+ */
+export declare function initializeLocalWorkspace(rootDir: string, platformDir?: string): Promise<LocalWorkspaceBackend>;

package/dist/shared/workspace/local-backend.js

@@ -0,0 +1,113 @@
+/**
+ * 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 } from "node:path";
+import { classifyPlatformPath, resolvePlatformCommand, STIGMER_PLATFORM_DIR_ENV, } from "./platform-mount.js";
+export class LocalWorkspaceBackend {
+    rootDir;
+    platformDir;
+    constructor(rootDir, platformDir) {
+        this.rootDir = rootDir;
+        this.platformDir = platformDir;
+    }
+    async execute(command, options) {
+        const cwd = options?.cwd
+            ? (isAbsolute(options.cwd) ? options.cwd : join(this.rootDir, options.cwd))
+            : this.rootDir;
+        let resolvedCommand = command;
+        const env = this.platformDir
+            ? { ...process.env, [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) {
+        const full = this.resolvePath(path);
+        return readFile(full, "utf-8");
+    }
+    async writeFile(path, content) {
+        const full = this.resolvePath(path);
+        await this.ensureParentDir(path, full);
+        await writeFile(full, content, "utf-8");
+    }
+    async writeFileBuffer(path, content) {
+        const full = this.resolvePath(path);
+        await this.ensureParentDir(path, full);
+        await writeFile(full, content);
+    }
+    async ensureParentDir(relativePath, resolvedPath) {
+        if (this.platformDir && !isAbsolute(relativePath)) {
+            const { isPlatform } = classifyPlatformPath(relativePath);
+            if (isPlatform) {
+                const parentDir = join(resolvedPath, "..");
+                await mkdir(parentDir, { recursive: true });
+            }
+        }
+    }
+    async exists(path) {
+        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.
+     */
+    resolvePath(path) {
+        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, platformDir) {
+    await mkdir(rootDir, { recursive: true });
+    return new LocalWorkspaceBackend(rootDir, platformDir);
+}
+//# sourceMappingURL=local-backend.js.map

package/dist/shared/workspace/local-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-backend.js","sourceRoot":"","sources":["../../../src/shared/workspace/local-backend.ts"],"names":[],"mappings":"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"}

package/dist/shared/workspace/platform-dir.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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.
+ */
+/**
+ * Compute the platform directory path for a session.
+ *
+ * Pure function — does not create the directory or perform I/O.
+ */
+export declare function getPlatformDir(sessionId: string): string;
+/**
+ * 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 declare function ensurePlatformDir(sessionId: string): Promise<string>;

package/dist/shared/workspace/platform-dir.js

@@ -0,0 +1,36 @@
+/**
+ * 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) {
+    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) {
+    const dir = getPlatformDir(sessionId);
+    await mkdir(dir, { recursive: true });
+    return dir;
+}
+//# sourceMappingURL=platform-dir.js.map

package/dist/shared/workspace/platform-dir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-dir.js","sourceRoot":"","sources":["../../../src/shared/workspace/platform-dir.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAElC;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,OAAO,EAAE,CAAC;IACtE,OAAO,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;AACnE,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,SAAiB;IACvD,MAAM,GAAG,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;IACtC,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtC,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/shared/workspace/platform-mount.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 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).
+ */
+/** Prefix that identifies paths targeting the virtual platform mount. */
+export declare const PLATFORM_PREFIX = ".stigmer/";
+/** Directory name used in listings and equality checks. */
+export declare const PLATFORM_DIR_NAME = ".stigmer";
+/**
+ * Environment variable injected into `execute()` calls so shell commands
+ * can access platform files via `$STIGMER_PLATFORM_DIR/skills/…`.
+ */
+export declare const STIGMER_PLATFORM_DIR_ENV = "STIGMER_PLATFORM_DIR";
+/**
+ * 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 declare function classifyPlatformPath(relPath: string): {
+    isPlatform: boolean;
+    remainder: string;
+};
+/**
+ * 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 declare function humanizePlatformRefs(text: string): string;
+/**
+ * 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 declare function resolvePlatformCommand(command: string): string;
+/**
+ * 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 declare function humanizeSandboxPaths(text: string, workspaceRoot: string): string;
+/**
+ * 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 declare function resolveDisplayEnvVars(text: string, envVars: Record<string, string>, secretKeys?: ReadonlySet<string>): string;