@stigmer/runner 3.0.1

package/src/shared/__tests__/zip-extract.test.ts

@@ -0,0 +1,204 @@
+import { describe, it, expect } from "vitest";
+import { deflateRawSync } from "node:zlib";
+import { extractZipFileEntries } from "../zip-extract.js";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────
+
+/**
+ * Build a minimal valid ZIP archive from an array of { name, content } entries.
+ * Uses stored (method 0) compression for simplicity. Produces local file
+ * headers only (no central directory) — sufficient for our parser.
+ */
+function buildStoredZip(files: { name: string; content: string }[]): Uint8Array {
+  const parts: Uint8Array[] = [];
+
+  for (const file of files) {
+    const nameBytes = new TextEncoder().encode(file.name);
+    const contentBytes = new TextEncoder().encode(file.content);
+    const isDir = file.name.endsWith("/");
+
+    // Local file header: 30 bytes
+    const header = new ArrayBuffer(30);
+    const view = new DataView(header);
+    view.setUint32(0, 0x04034b50, true);  // signature
+    view.setUint16(4, 20, true);           // version needed
+    view.setUint16(6, 0, true);            // general purpose flags
+    view.setUint16(8, 0, true);            // compression method (stored)
+    view.setUint16(10, 0, true);           // last mod time
+    view.setUint16(12, 0, true);           // last mod date
+    view.setUint32(14, 0, true);           // crc-32 (unused for our purposes)
+    view.setUint32(18, isDir ? 0 : contentBytes.length, true); // compressed size
+    view.setUint32(22, isDir ? 0 : contentBytes.length, true); // uncompressed size
+    view.setUint16(26, nameBytes.length, true);  // file name length
+    view.setUint16(28, 0, true);           // extra field length
+
+    parts.push(new Uint8Array(header));
+    parts.push(nameBytes);
+    if (!isDir) {
+      parts.push(contentBytes);
+    }
+  }
+
+  const totalLength = parts.reduce((sum, p) => sum + p.length, 0);
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const part of parts) {
+    result.set(part, offset);
+    offset += part.length;
+  }
+  return result;
+}
+
+/**
+ * Build a ZIP archive with a single deflated (method 8) entry.
+ */
+function buildDeflatedZip(name: string, content: string): Uint8Array {
+  const nameBytes = new TextEncoder().encode(name);
+  const contentBytes = new TextEncoder().encode(content);
+  const compressed = deflateRawSync(contentBytes);
+
+  const header = new ArrayBuffer(30);
+  const view = new DataView(header);
+  view.setUint32(0, 0x04034b50, true);
+  view.setUint16(4, 20, true);
+  view.setUint16(6, 0, true);
+  view.setUint16(8, 8, true);            // deflated
+  view.setUint16(10, 0, true);
+  view.setUint16(12, 0, true);
+  view.setUint32(14, 0, true);
+  view.setUint32(18, compressed.length, true);
+  view.setUint32(22, contentBytes.length, true);
+  view.setUint16(26, nameBytes.length, true);
+  view.setUint16(28, 0, true);
+
+  const totalLength = 30 + nameBytes.length + compressed.length;
+  const result = new Uint8Array(totalLength);
+  result.set(new Uint8Array(header), 0);
+  result.set(nameBytes, 30);
+  result.set(new Uint8Array(compressed.buffer, compressed.byteOffset, compressed.length), 30 + nameBytes.length);
+  return result;
+}
+
+// ─── extractZipFileEntries ───────────────────────────────────────────────
+
+describe("extractZipFileEntries", () => {
+  it("extracts stored files from a ZIP archive", async () => {
+    const zip = buildStoredZip([
+      { name: "SKILL.md", content: "# My Skill" },
+      { name: "references/schema.md", content: "# Schema\n\nTable definitions." },
+    ]);
+
+    const entries = await extractZipFileEntries(zip);
+    expect(entries).toHaveLength(2);
+    expect(entries[0]).toEqual({ path: "SKILL.md", content: "# My Skill" });
+    expect(entries[1]).toEqual({ path: "references/schema.md", content: "# Schema\n\nTable definitions." });
+  });
+
+  it("extracts deflated files", async () => {
+    const content = "This content is compressed with deflate.";
+    const zip = buildDeflatedZip("notes.txt", content);
+
+    const entries = await extractZipFileEntries(zip);
+    expect(entries).toHaveLength(1);
+    expect(entries[0]).toEqual({ path: "notes.txt", content });
+  });
+
+  it("skips directory entries", async () => {
+    const zip = buildStoredZip([
+      { name: "references/", content: "" },
+      { name: "references/data.md", content: "data" },
+    ]);
+
+    const entries = await extractZipFileEntries(zip);
+    expect(entries).toHaveLength(1);
+    expect(entries[0].path).toBe("references/data.md");
+  });
+
+  it("excludes files by basename", async () => {
+    const zip = buildStoredZip([
+      { name: "SKILL.md", content: "# Skill" },
+      { name: "references/schema.md", content: "# Schema" },
+      { name: "scripts/run.py", content: "print('hi')" },
+    ]);
+
+    const entries = await extractZipFileEntries(zip, { exclude: ["SKILL.md"] });
+    expect(entries).toHaveLength(2);
+    expect(entries.map(e => e.path)).toEqual(["references/schema.md", "scripts/run.py"]);
+  });
+
+  it("excludes files by full path", async () => {
+    const zip = buildStoredZip([
+      { name: "a.md", content: "a" },
+      { name: "nested/a.md", content: "nested" },
+    ]);
+
+    const entries = await extractZipFileEntries(zip, { exclude: ["nested/a.md"] });
+    expect(entries).toHaveLength(1);
+    expect(entries[0].path).toBe("a.md");
+  });
+
+  it("excludes entries matching basename even when nested", async () => {
+    const zip = buildStoredZip([
+      { name: "SKILL.md", content: "root" },
+      { name: "sub/SKILL.md", content: "sub" },
+      { name: "data.md", content: "data" },
+    ]);
+
+    const entries = await extractZipFileEntries(zip, { exclude: ["SKILL.md"] });
+    expect(entries).toHaveLength(1);
+    expect(entries[0].path).toBe("data.md");
+  });
+
+  it("returns empty array for empty input", async () => {
+    const entries = await extractZipFileEntries(new Uint8Array(0));
+    expect(entries).toEqual([]);
+  });
+
+  it("returns empty array for truncated input", async () => {
+    const entries = await extractZipFileEntries(new Uint8Array([1, 2, 3]));
+    expect(entries).toEqual([]);
+  });
+
+  it("returns empty array for non-ZIP data", async () => {
+    const garbage = new TextEncoder().encode("this is not a zip file at all");
+    const entries = await extractZipFileEntries(garbage);
+    expect(entries).toEqual([]);
+  });
+
+  it("handles multiple files with nested directories", async () => {
+    const zip = buildStoredZip([
+      { name: "SKILL.md", content: "# Skill" },
+      { name: "references/", content: "" },
+      { name: "references/database-schema.md", content: "# Schema" },
+      { name: "references/player-segments.md", content: "# Segments" },
+      { name: "references/retention-benchmarks.md", content: "# Benchmarks" },
+    ]);
+
+    const entries = await extractZipFileEntries(zip, { exclude: ["SKILL.md"] });
+    expect(entries).toHaveLength(3);
+    expect(entries.map(e => e.path)).toEqual([
+      "references/database-schema.md",
+      "references/player-segments.md",
+      "references/retention-benchmarks.md",
+    ]);
+  });
+
+  it("returns all entries when no exclude option is provided", async () => {
+    const zip = buildStoredZip([
+      { name: "a.txt", content: "aaa" },
+      { name: "b.txt", content: "bbb" },
+    ]);
+
+    const entries = await extractZipFileEntries(zip);
+    expect(entries).toHaveLength(2);
+  });
+
+  it("returns all entries when exclude list is empty", async () => {
+    const zip = buildStoredZip([
+      { name: "a.txt", content: "aaa" },
+    ]);
+
+    const entries = await extractZipFileEntries(zip, { exclude: [] });
+    expect(entries).toHaveLength(1);
+  });
+});

package/src/shared/approval-policy.ts

@@ -0,0 +1,146 @@
+/**
+ * Tool approval policy evaluation — harness-agnostic.
+ *
+ * Implements the four-level policy chain:
+ * 1. McpServerStatus.tool_approvals — system-generated defaults
+ * 2. McpServerSpec.pinned_tool_approvals — manual overrides
+ * 3. McpServerUsage.tool_approval_overrides — per-agent customization
+ * 4. AgentExecutionSpec.auto_approve_all — runtime bypass
+ *
+ * Used by both ExecuteCursor (hook-deny model) and ExecuteDeepAgent
+ * (middleware interruptOn model) to determine which tools need approval.
+ */
+
+import type { ToolApprovalPolicy } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
+import type { ToolApprovalOverride } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { ResolvedMcpServer } from "./mcp-resolver.js";
+
+/**
+ * Returns true if any tool call in the execution history (root or sub-agent)
+ * carries an APPROVE_ALL decision.
+ *
+ * This is the runner-side realization of the APPROVE_ALL contract (see the
+ * ApprovalAction doc in enum.proto): once a user has chosen "approve and don't
+ * ask again" at any gate, the rest of THIS execution runs un-gated — exactly as
+ * if spec.auto_approve_all were true. Both harnesses (native deepagents and
+ * cursor) call this so the behavior is defined in exactly one place.
+ */
+export function hasApproveAllDecision(execution: AgentExecution): boolean {
+  const status = execution.status;
+  if (!status) return false;
+
+  for (const message of status.messages) {
+    for (const tc of message.toolCalls) {
+      if (tc.approvalAction === ApprovalAction.APPROVE_ALL) return true;
+    }
+  }
+  for (const sa of status.subAgentExecutions) {
+    for (const message of sa.messages) {
+      for (const tc of message.toolCalls) {
+        if (tc.approvalAction === ApprovalAction.APPROVE_ALL) return true;
+      }
+    }
+  }
+  return false;
+}
+
+export interface MergedToolPolicy {
+  toolName: string;
+  mcpServerSlug: string;
+  requiresApproval: boolean;
+  approvalMessage: string;
+}
+
+/**
+ * Merge approval policies from all four levels into a single lookup map.
+ *
+ * Keys are "serverSlug/toolName" to avoid collisions between servers.
+ * When autoApproveAll is true, the returned map is empty.
+ */
+export function mergeApprovalPolicies(
+  resolvedServers: ResolvedMcpServer[],
+  agentOverrides: ToolApprovalOverride[],
+  autoApproveAll: boolean,
+): Map<string, MergedToolPolicy> {
+  const merged = new Map<string, MergedToolPolicy>();
+
+  if (autoApproveAll) return merged;
+
+  for (const server of resolvedServers) {
+    const serverPolicies = new Map<string, { requiresApproval: boolean; message: string }>();
+
+    for (const policy of server.toolApprovals) {
+      if (!policy.toolName) continue;
+      serverPolicies.set(policy.toolName, {
+        requiresApproval: true,
+        message: policy.message || `Execute tool: ${policy.toolName}`,
+      });
+    }
+
+    for (const pinned of server.pinnedToolApprovals) {
+      if (!pinned.toolName) continue;
+      serverPolicies.set(pinned.toolName, {
+        requiresApproval: true,
+        message: pinned.message || serverPolicies.get(pinned.toolName)?.message || `Execute tool: ${pinned.toolName}`,
+      });
+    }
+
+    for (const override of agentOverrides) {
+      if (!override.toolName) continue;
+      const existing = serverPolicies.get(override.toolName);
+      if (existing) {
+        existing.requiresApproval = override.requiresApproval;
+        if (override.message) {
+          existing.message = override.message;
+        }
+      } else if (override.requiresApproval) {
+        serverPolicies.set(override.toolName, {
+          requiresApproval: true,
+          message: override.message || `Execute tool: ${override.toolName}`,
+        });
+      }
+    }
+
+    for (const [toolName, policy] of serverPolicies) {
+      if (!policy.requiresApproval) continue;
+      const key = `${server.slug}/${toolName}`;
+      merged.set(key, {
+        toolName,
+        mcpServerSlug: server.slug,
+        requiresApproval: true,
+        approvalMessage: policy.message,
+      });
+    }
+  }
+
+  return merged;
+}
+
+export function lookupMcpToolPolicy(
+  toolName: string,
+  mcpServerSlug: string,
+  policies: Map<string, MergedToolPolicy>,
+): MergedToolPolicy | undefined {
+  return policies.get(`${mcpServerSlug}/${toolName}`);
+}
+
+/**
+ * Resolve {{args.field}} placeholders in an approval message using the
+ * tool's actual arguments.
+ */
+export function resolveApprovalMessage(
+  template: string,
+  toolName: string,
+  args: Record<string, unknown>,
+): string {
+  return template
+    .replace(/\{\{tool_name\}\}/g, toolName)
+    .replace(/\{\{args\.(\w+)\}\}/g, (_match, field: string) => {
+      const value = args[field];
+      if (value === undefined || value === null) return "<unknown>";
+      if (typeof value === "string") return value;
+      return JSON.stringify(value);
+    });
+}

package/src/shared/artifact-storage.ts

@@ -0,0 +1,207 @@
+/**
+ * Artifact storage abstraction for the unified runner.
+ *
+ * Two backends:
+ * - Local: writes to the filesystem, served by stigmer-server (OSS mode).
+ * - Proxy: uses presigned URLs from the Stigmer Side-Channel Proxy (cloud mode).
+ *
+ * The runner never holds R2/S3 credentials — in cloud mode it calls the proxy
+ * to obtain a presigned upload URL, then PUTs content over plain HTTPS.
+ *
+ * DD-6: No direct R2 backend. Local + Proxy only.
+ */
+
+import { mkdir, writeFile, readFile, access, unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { Config } from "../config.js";
+
+// ── Interface ────────────────────────────────────────────────────────
+
+export interface ArtifactStorage {
+  upload(key: string, content: Buffer, contentType?: string): Promise<string>;
+  getDownloadUrl(key: string): Promise<string>;
+  exists(key: string): Promise<boolean>;
+}
+
+export type ArtifactStorageType = "local" | "proxy";
+
+// ── Local Backend ────────────────────────────────────────────────────
+
+export class LocalArtifactStorage implements ArtifactStorage {
+  private readonly basePath: string;
+  private readonly serveUrlBase: string;
+
+  constructor(basePath: string, serveUrlBase: string) {
+    this.basePath = basePath;
+    this.serveUrlBase = serveUrlBase.replace(/\/+$/, "");
+  }
+
+  async upload(key: string, content: Buffer, _contentType?: string): Promise<string> {
+    const filePath = join(this.basePath, key);
+    await mkdir(dirname(filePath), { recursive: true });
+    await writeFile(filePath, content);
+    return key;
+  }
+
+  async getDownloadUrl(key: string): Promise<string> {
+    return `${this.serveUrlBase}/${key}`;
+  }
+
+  async exists(key: string): Promise<boolean> {
+    try {
+      await access(join(this.basePath, key));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+// ── Proxy Backend ────────────────────────────────────────────────────
+
+export class ProxyArtifactStorage implements ArtifactStorage {
+  private readonly baseUrl: string;
+  private readonly authToken: string;
+
+  constructor(proxyEndpoint: string, authToken: string) {
+    this.baseUrl = `${proxyEndpoint.replace(/\/+$/, "")}/v1/proxy/artifacts`;
+    this.authToken = authToken;
+  }
+
+  async upload(key: string, content: Buffer, contentType?: string): Promise<string> {
+    const ct = contentType ?? "application/octet-stream";
+
+    const presignResp = await fetch(`${this.baseUrl}/presigned-upload-url`, {
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${this.authToken}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ key, content_type: ct }),
+    });
+    if (!presignResp.ok) {
+      throw new Error(
+        `Failed to get presigned upload URL (HTTP ${presignResp.status}): ` +
+        await presignResp.text(),
+      );
+    }
+
+    const data = await presignResp.json() as { url: string; headers?: Record<string, string> };
+
+    // Send exactly the headers the proxy signed. The presigner is the single
+    // source of truth for what must be on the wire: a SigV4 presigned PUT signs
+    // `content-type` (and `host`), so re-adding or duplicating any signed header
+    // changes its value and the store rejects the upload with
+    // `SignatureDoesNotMatch`. We therefore replay the signed set verbatim —
+    // never appending our own `Content-Type` when the signer already covered it.
+    // `host` is set by fetch from the URL and cannot be overridden, so drop it.
+    const signedHeaders = data.headers ?? {};
+    const uploadHeaders: Record<string, string> = {};
+    let contentTypeSigned = false;
+    for (const [name, value] of Object.entries(signedHeaders)) {
+      if (name.toLowerCase() === "host") continue;
+      if (name.toLowerCase() === "content-type") contentTypeSigned = true;
+      uploadHeaders[name] = value;
+    }
+    // Only set Content-Type ourselves if the presigner did NOT sign it (so the
+    // stored object still records the right type); when it IS signed, adding it
+    // would corrupt the signed value.
+    if (!contentTypeSigned) {
+      uploadHeaders["Content-Type"] = ct;
+    }
+
+    const putResp = await fetch(data.url, {
+      method: "PUT",
+      headers: uploadHeaders,
+      body: content,
+    });
+    if (!putResp.ok) {
+      throw new Error(
+        `Presigned upload failed (HTTP ${putResp.status}): ` +
+        await putResp.text(),
+      );
+    }
+
+    return key;
+  }
+
+  async getDownloadUrl(key: string): Promise<string> {
+    const resp = await fetch(`${this.baseUrl}/presigned-download-url`, {
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${this.authToken}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ key }),
+    });
+    if (!resp.ok) {
+      throw new Error(
+        `Failed to get presigned download URL (HTTP ${resp.status}): ` +
+        await resp.text(),
+      );
+    }
+    const data = await resp.json() as { url: string };
+    return data.url;
+  }
+
+  async exists(key: string): Promise<boolean> {
+    try {
+      const resp = await fetch(`${this.baseUrl}/presigned-download-url`, {
+        method: "POST",
+        headers: {
+          "Authorization": `Bearer ${this.authToken}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ key }),
+      });
+      return resp.ok;
+    } catch {
+      return false;
+    }
+  }
+}
+
+// ── Factory ──────────────────────────────────────────────────────────
+
+export interface ArtifactStorageConfig {
+  readonly type: ArtifactStorageType;
+  readonly localPath: string;
+  readonly localServeUrl: string;
+  readonly proxyEndpoint: string | null;
+  readonly proxyAuthToken: string | null;
+}
+
+export function loadArtifactStorageConfig(config: Config): ArtifactStorageConfig {
+  // Storage follows transport, not execution location: if a proxy endpoint is
+  // configured, push artifacts through it (the proxy brokers R2). This holds for
+  // both cloud runners and the local desktop runner — the latter executes
+  // locally (mode === "local") yet still uploads via the proxy. An explicit
+  // ARTIFACT_STORAGE_TYPE always wins.
+  const envType = process.env.ARTIFACT_STORAGE_TYPE;
+  const type: ArtifactStorageType =
+    envType === "proxy" ? "proxy" :
+    envType === "local" ? "local" :
+    config.proxyEndpoint ? "proxy" : "local";
+
+  return {
+    type,
+    localPath: process.env.LOCAL_ARTIFACT_PATH ?? "/var/stigmer/artifacts",
+    localServeUrl: process.env.LOCAL_ARTIFACT_SERVE_URL ?? "http://localhost:7235",
+    proxyEndpoint: type === "proxy" ? (config.proxyEndpoint ?? null) : null,
+    proxyAuthToken: type === "proxy" ? (config.stigmerToken ?? null) : null,
+  };
+}
+
+export function createArtifactStorage(cfg: ArtifactStorageConfig): ArtifactStorage {
+  if (cfg.type === "proxy") {
+    if (!cfg.proxyEndpoint) {
+      throw new Error("Proxy artifact storage requires STIGMER_PROXY_ENDPOINT");
+    }
+    if (!cfg.proxyAuthToken) {
+      throw new Error("Proxy artifact storage requires STIGMER_TOKEN");
+    }
+    return new ProxyArtifactStorage(cfg.proxyEndpoint, cfg.proxyAuthToken);
+  }
+
+  return new LocalArtifactStorage(cfg.localPath, cfg.localServeUrl);
+}

package/src/shared/checkpointer/__tests__/factory.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from "vitest";
+import { MemorySaver } from "@langchain/langgraph-checkpoint";
+import { createCheckpointer, CheckpointerCreationError } from "../factory.js";
+import { HttpCheckpointSaver } from "../http-saver.js";
+
+describe("createCheckpointer", () => {
+  it("returns MemorySaver for type=memory", async () => {
+    const saver = await createCheckpointer({ type: "memory" });
+    expect(saver).toBeInstanceOf(MemorySaver);
+  });
+
+  it("returns HttpCheckpointSaver for type=http", async () => {
+    const saver = await createCheckpointer({
+      type: "http",
+      proxyEndpoint: "https://proxy.test",
+      authToken: "tok-123",
+    });
+    expect(saver).toBeInstanceOf(HttpCheckpointSaver);
+  });
+
+  it("throws CheckpointerCreationError when http is missing proxyEndpoint", async () => {
+    await expect(
+      createCheckpointer({ type: "http", authToken: "tok" }),
+    ).rejects.toThrow(CheckpointerCreationError);
+  });
+
+  it("throws CheckpointerCreationError when http is missing authToken", async () => {
+    await expect(
+      createCheckpointer({ type: "http", proxyEndpoint: "https://proxy.test" }),
+    ).rejects.toThrow(CheckpointerCreationError);
+  });
+
+  it("error includes the checkpointer type", async () => {
+    try {
+      await createCheckpointer({ type: "http" });
+      expect.unreachable("should have thrown");
+    } catch (err) {
+      expect(err).toBeInstanceOf(CheckpointerCreationError);
+      expect((err as CheckpointerCreationError).checkpointerType).toBe("http");
+    }
+  });
+});