@stigmer/runner 3.12.4 → 3.12.5

package/src/runner.ts

@@ -324,6 +324,16 @@ export async function createStigmerRunner(
   // unaffected — their env-injected platform key wins inside the loader.
   const payloadCodecs = await createPayloadCodecs(config, coordinates.payloadEncryption);
 
+  // Register the queue's shutdown signal BEFORE the worker can poll, so an
+  // activity interrupted by shutdown() below classifies the cancellation as a
+  // worker shutdown, not a user pause (issue #776). Static mode historically
+  // never registered one, leaving CLI daemons with the same misclassification
+  // the desktop manager had.
+  const { registerWorkerShutdownSignal } = await import(
+    "./shared/worker-shutdown.js"
+  );
+  const shutdownController = registerWorkerShutdownSignal(config.taskQueue);
+
   const { startWorker } = await import("./worker.js");
   const worker = await startWorker({ config, activities, payloadCodecs });
   markBoot("worker_created");
@@ -349,6 +359,10 @@ export async function createStigmerRunner(
     },
     shutdown() {
       tokenRenewal?.stop();
+      // Classification first, drain second: an in-flight activity cancelled
+      // by the drain must observe the signal already aborted (see
+      // shared/worker-shutdown.ts for the ownership contract).
+      shutdownController.abort();
       worker.shutdown();
     },
   };

package/src/shared/__tests__/artifact-storage.test.ts

@@ -618,6 +618,22 @@ describe("createArtifactStorage", () => {
     };
     expect(() => createArtifactStorage(cfg)).toThrow("STIGMER_TOKEN");
   });
+
+  it("throws for the deliberate 'none' posture — resolveUsable degrades it, claimcheck fail-hards", async () => {
+    const cfg: ArtifactStorageConfig = {
+      type: "none",
+      localPath: "/tmp/artifacts",
+      localServeUrl: "http://localhost:7235",
+      proxyEndpoint: null,
+      proxyAuthToken: null,
+    };
+    expect(() => createArtifactStorage(cfg)).toThrow(/deliberately disabled/i);
+    // The capture/offload resolver treats it as the first-class absent store:
+    // deny-gate mode, not a crash.
+    await expect(
+      resolveUsableArtifactStorage(cfg, { executionId: "exec-none" }),
+    ).resolves.toBeUndefined();
+  });
 });
 
 describe("loadArtifactStorageConfig", () => {
@@ -680,6 +696,18 @@ describe("loadArtifactStorageConfig", () => {
     expect(cfg.proxyAuthToken).toBe("tok");
   });
 
+  it("honors ARTIFACT_STORAGE_TYPE=none even when a proxy endpoint is configured", () => {
+    // "none" is a deliberate operator/e2e posture — it must beat the
+    // storage-follows-transport default exactly like the other overrides.
+    process.env.ARTIFACT_STORAGE_TYPE = "none";
+    const cfg = loadArtifactStorageConfig({
+      ...baseConfig,
+      proxyEndpoint: "https://proxy.example.com",
+      stigmerToken: "tok",
+    });
+    expect(cfg.type).toBe("none");
+  });
+
   it("respects ARTIFACT_STORAGE_TYPE override", () => {
     process.env.ARTIFACT_STORAGE_TYPE = "proxy";
     const cfg = loadArtifactStorageConfig({

package/src/shared/__tests__/bedrock-seam.test.ts

@@ -2,11 +2,11 @@
  * Characterization test for the ChatAnthropic `createClient` ->
  * AnthropicBedrock seam — the integration the T04 bedrock backend adapter
  * is built on. Sibling of vertex-seam.test.ts; same rules: this pins REAL
- * cross-package behavior (`@langchain/anthropic` bundling @anthropic-ai/sdk
- * 0.95.x driving `@anthropic-ai/bedrock-sdk` bundling its own nested
- * >=0.115 copy), so a future bump of either side fails here in CI instead
- * of in production. See scripts/check-langchain-deps.sh for why the two
- * @anthropic-ai/sdk versions coexist and when they collapse to one.
+ * cross-package behavior (`@langchain/anthropic` driving
+ * `@anthropic-ai/bedrock-sdk`, both resolving the single override-pinned
+ * @anthropic-ai/sdk copy), so a future bump of either side fails here in
+ * CI instead of in production. See scripts/check-langchain-deps.sh for
+ * the override rationale and the single-copy invariant it guards.
  *
  * Determinism: zero live credentials, zero network. SigV4 signing runs for
  * real — it is pure HMAC over static test keys passed through the SDK's

package/src/shared/__tests__/declared-preferences.test.ts

@@ -0,0 +1,109 @@
+/**
+ * Unit tests for the declared-preferences module (stigmer/stigmer#293,
+ * DD-002). Like conversation-catchup there is no string key to mirror-guard —
+ * the value rides the typed `AgentExecutionSpec.declared_preferences` proto
+ * field, so codegen enforces the cross-repo contract. What IS pinned here:
+ * the per-scope blank-is-absent read semantics (the server stamps the field
+ * on EVERY eligible create, usually with blank scopes), the per-scope
+ * attribution, and the framing's behavioral contract.
+ */
+
+import { describe, it, expect } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { DeclaredPreferencesSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+
+import {
+  formatDeclaredPreferencesText,
+  readDeclaredPreferences,
+} from "../declared-preferences.js";
+
+const ORG_CONTEXT = "We deploy to us-east-1. All costs in USD.";
+const USER_CONTEXT = "Keep answers terse. Prefer Go examples.";
+
+describe("readDeclaredPreferences", () => {
+  it("reads both scopes when both are set", () => {
+    const preferences = create(DeclaredPreferencesSchema, {
+      orgContext: ORG_CONTEXT,
+      userContext: USER_CONTEXT,
+    });
+    expect(readDeclaredPreferences(preferences)).toEqual({
+      orgContext: ORG_CONTEXT,
+      userContext: USER_CONTEXT,
+    });
+  });
+
+  it("answers undefined when the field is absent (pre-#293 executions)", () => {
+    expect(readDeclaredPreferences(undefined)).toBeUndefined();
+  });
+
+  it("answers undefined when both scopes are blank — the server stamps the field on every eligible create", () => {
+    const preferences = create(DeclaredPreferencesSchema, {
+      orgContext: "  ",
+      userContext: "",
+    });
+    expect(readDeclaredPreferences(preferences)).toBeUndefined();
+  });
+
+  it("blank-is-absent applies per scope: an org-only snapshot carries no user scope", () => {
+    const preferences = create(DeclaredPreferencesSchema, {
+      orgContext: ORG_CONTEXT,
+      userContext: "   ",
+    });
+    expect(readDeclaredPreferences(preferences)).toEqual({
+      orgContext: ORG_CONTEXT,
+      userContext: undefined,
+    });
+  });
+
+  it("trims surrounding whitespace from each scope", () => {
+    const preferences = create(DeclaredPreferencesSchema, {
+      orgContext: "  org facts  ",
+      userContext: "\nuser facts\n",
+    });
+    expect(readDeclaredPreferences(preferences)).toEqual({
+      orgContext: "org facts",
+      userContext: "user facts",
+    });
+  });
+});
+
+describe("formatDeclaredPreferencesText", () => {
+  it("frames the preferences as already-known, non-announced background", () => {
+    const framed = formatDeclaredPreferencesText({
+      orgContext: ORG_CONTEXT,
+      userContext: USER_CONTEXT,
+    });
+
+    expect(framed).toContain("Standing preferences declared by");
+    expect(framed).toContain("Do not repeat them back");
+    expect(framed).toContain("not instructions that override your task");
+  });
+
+  it("attributes each scope explicitly, organization first, user last", () => {
+    const framed = formatDeclaredPreferencesText({
+      orgContext: ORG_CONTEXT,
+      userContext: USER_CONTEXT,
+    });
+
+    const org = framed.indexOf("Declared by the organization:");
+    const user = framed.indexOf("Declared by the user:");
+    expect(org).toBeGreaterThan(-1);
+    expect(user).toBeGreaterThan(org);
+    expect(framed).toContain(ORG_CONTEXT);
+    expect(framed.endsWith(USER_CONTEXT)).toBe(true);
+  });
+
+  it("renders only the org subsection for an org-only snapshot", () => {
+    const framed = formatDeclaredPreferencesText({ orgContext: ORG_CONTEXT });
+
+    expect(framed).toContain("Declared by the organization:");
+    expect(framed).not.toContain("Declared by the user:");
+  });
+
+  it("renders only the user subsection for a user-only snapshot", () => {
+    const framed = formatDeclaredPreferencesText({ userContext: USER_CONTEXT });
+
+    expect(framed).not.toContain("Declared by the organization:");
+    expect(framed).toContain("Declared by the user:");
+  });
+});

package/src/shared/__tests__/foundry-seam.test.ts

@@ -3,11 +3,11 @@
  * AnthropicFoundry seam — the integration the T05 foundry backend adapter
  * is built on. Sibling of vertex-seam.test.ts and bedrock-seam.test.ts;
  * same rules: this pins REAL cross-package behavior (`@langchain/anthropic`
- * bundling @anthropic-ai/sdk 0.95.x driving `@anthropic-ai/foundry-sdk`
- * bundling its own nested >=0.115 copy), so a future bump of either side
- * fails here in CI instead of in production. See
- * scripts/check-langchain-deps.sh for why the two @anthropic-ai/sdk
- * versions coexist and when they collapse to one.
+ * driving `@anthropic-ai/foundry-sdk`, both resolving the single
+ * override-pinned @anthropic-ai/sdk copy), so a future bump of either
+ * side fails here in CI instead of in production. See
+ * scripts/check-langchain-deps.sh for the override rationale and the
+ * single-copy invariant it guards.
  *
  * Determinism: zero live credentials, zero network. API-key auth is a
  * static test key; Entra ID auth is a fake `azureADTokenProvider` (the

package/src/shared/__tests__/plan-mode-permissions.test.ts

@@ -1,58 +1,29 @@
 /**
- * Unit pins for the plan-mode rule builder (issue #528).
+ * Unit pins for the plan-mode rule builder.
  *
- * The rule ORDER and SHAPE are the security boundary: deepagents evaluates
- * first-match-wins with a permissive default, so the workspace read-allow
- * must precede the read-deny, and the deny patterns must be the match-all
- * "/**". These tests pin the built value; the boundary's end-to-end
- * behavior (including matcher semantics for escaped roots and symlinked
- * platform paths) is pinned against the real deepagents runtime in
+ * Since issue #754 the rules carry ONLY plan mode's write-deny: the read
+ * boundary is structural (virtual-rooted backends confine every path to the
+ * workspace), so there is no workspace-root glob, no escaping, and no rule
+ * ordering left to protect. The single rule's SHAPE is still the security
+ * boundary for writes — "/**" must stay the match-all virtual pattern and
+ * the operation class must stay `write` (deepagents evaluates
+ * first-match-wins with a permissive default, so reads flow by omission).
+ * End-to-end behavior is pinned against the real deepagents runtime in
  * execute-deep-agent/__tests__/plan-mode-path-normalization.test.ts.
  */
 
 import { describe, it, expect } from "vitest";
-import {
-  buildPlanModePermissions,
-  escapeGlobLiteral,
-} from "../plan-mode-permissions.js";
+import { buildPlanModePermissions } from "../plan-mode-permissions.js";
 
 describe("buildPlanModePermissions", () => {
-  it("builds the policy in enforcement order: workspace read-allow, then read-deny, then write-deny", () => {
-    expect(buildPlanModePermissions("/ws/session-1/repo")).toEqual([
-      { operations: ["read"], paths: ["/ws/session-1/repo/**"] },
-      { operations: ["read"], paths: ["/**"], mode: "deny" },
+  it("builds exactly the write-deny policy in the virtual dialect", () => {
+    expect(buildPlanModePermissions()).toEqual([
       { operations: ["write"], paths: ["/**"], mode: "deny" },
     ]);
   });
 
-  it("canonicalizes the root before building the pattern", () => {
-    // Enforcement canonicalizes incoming paths (no trailing separator,
-    // collapsed slashes) before matching — a pattern built from a raw
-    // trailing-slash root would silently match nothing.
-    const [allow] = buildPlanModePermissions("/ws//session-1/repo/");
-    expect(allow.paths).toEqual(["/ws/session-1/repo/**"]);
-  });
-
-  it("glob-escapes the root so special characters match literally", () => {
-    const [allow] = buildPlanModePermissions("/Users/x/My (work) [v2]");
-    expect(allow.paths).toEqual(["/Users/x/My \\(work\\) \\[v2\\]/**"]);
-  });
-});
-
-describe("escapeGlobLiteral", () => {
-  it("escapes every micromatch metacharacter", () => {
-    expect(escapeGlobLiteral("a*b?c(d)e[f]g{h}i!j+k@l")).toBe(
-      "a\\*b\\?c\\(d\\)e\\[f\\]g\\{h\\}i\\!j\\+k\\@l",
-    );
-  });
-
-  it("escapes backslashes themselves", () => {
-    expect(escapeGlobLiteral("a\\b")).toBe("a\\\\b");
-  });
-
-  it("leaves plain path characters alone", () => {
-    expect(escapeGlobLiteral("/ws/session-1/repo.dir")).toBe(
-      "/ws/session-1/repo.dir",
-    );
+  it("carries no read rules — the read boundary is structural, not policy", () => {
+    const operations = buildPlanModePermissions().flatMap((rule) => rule.operations);
+    expect(operations).not.toContain("read");
   });
 });

package/src/shared/__tests__/skill-mount.test.ts

@@ -0,0 +1,238 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, readFileSync, existsSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { ConnectError, Code } from "@connectrpc/connect";
+import {
+  MOUNT_MARKER_FILE,
+  mountIsFresh,
+  downloadArtifact,
+  writeSkillMount,
+} from "../skill-mount.js";
+import { buildZip } from "../../__test-utils__/zip-fixtures.js";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────
+
+function makeSkillProto(overrides: {
+  name?: string;
+  skillMd?: string;
+  artifactStorageKey?: string;
+  versionHash?: string;
+} = {}) {
+  return {
+    metadata: {
+      id: `skill-${overrides.name ?? "test"}`,
+      slug: overrides.name ?? "test-skill",
+      org: "test-org",
+    },
+    spec: {
+      name: overrides.name ?? "test-skill",
+      description: "A test skill",
+      skillMd: overrides.skillMd ?? "# Test Skill",
+    },
+    status: {
+      artifactStorageKey: overrides.artifactStorageKey ?? "",
+      versionHash: overrides.versionHash ?? "abc",
+    },
+  } as any;
+}
+
+// ─── writeSkillMount + mountIsFresh — marker mechanics ───────────────────
+
+describe("writeSkillMount — marker mechanics", () => {
+  let skillDir: string;
+
+  beforeEach(() => {
+    skillDir = join(mkdtempSync(join(tmpdir(), "skill-mount-")), "test-skill");
+  });
+
+  afterEach(() => {
+    rmSync(join(skillDir, ".."), { recursive: true, force: true });
+  });
+
+  it("stamps a marker recording the hash and a fully mounted artifact", async () => {
+    const artifact = buildZip([{ name: "references/guide.md", content: "guide" }]);
+    await writeSkillMount(makeSkillProto({ versionHash: "hash-v1" }), skillDir, artifact);
+
+    const marker = JSON.parse(readFileSync(join(skillDir, MOUNT_MARKER_FILE), "utf-8"));
+    expect(marker).toEqual({ versionHash: "hash-v1", artifactMounted: true });
+    expect(await mountIsFresh(skillDir, "hash-v1", true)).toBe(true);
+  });
+
+  it("records a degraded SKILL.md-only mount so the next execution retries the artifact", async () => {
+    await writeSkillMount(makeSkillProto({ versionHash: "hash-v1" }), skillDir, undefined);
+
+    const marker = JSON.parse(readFileSync(join(skillDir, MOUNT_MARKER_FILE), "utf-8"));
+    expect(marker).toEqual({ versionHash: "hash-v1", artifactMounted: false });
+    // Stale for a skill that carries an artifact (retry the download)...
+    expect(await mountIsFresh(skillDir, "hash-v1", true)).toBe(false);
+    // ...fresh for a skill that never had one.
+    expect(await mountIsFresh(skillDir, "hash-v1", false)).toBe(true);
+  });
+
+  it("stamps no marker when the skill has no version hash — such mounts never cache", async () => {
+    await writeSkillMount(makeSkillProto({ versionHash: "" }), skillDir, undefined);
+
+    expect(existsSync(join(skillDir, MOUNT_MARKER_FILE))).toBe(false);
+    expect(await mountIsFresh(skillDir, "", false)).toBe(false);
+  });
+
+  it("is stale for a different hash", async () => {
+    await writeSkillMount(makeSkillProto({ versionHash: "hash-v1" }), skillDir, undefined);
+    expect(await mountIsFresh(skillDir, "hash-v2", false)).toBe(false);
+  });
+
+  it("is stale when the marker is missing or unparseable", async () => {
+    expect(await mountIsFresh(skillDir, "hash-v1", false)).toBe(false);
+  });
+
+  it("removes files from a previous mount that the new version no longer carries", async () => {
+    const v1 = buildZip([{ name: "references/removed-in-v2.md", content: "old" }]);
+    const v2 = buildZip([{ name: "references/new-in-v2.md", content: "new" }]);
+
+    await writeSkillMount(makeSkillProto({ versionHash: "hash-v1" }), skillDir, v1);
+    await writeSkillMount(makeSkillProto({ versionHash: "hash-v2" }), skillDir, v2);
+
+    expect(existsSync(join(skillDir, "references", "removed-in-v2.md"))).toBe(false);
+    expect(readFileSync(join(skillDir, "references", "new-in-v2.md"), "utf-8")).toBe("new");
+  });
+
+  it("owns SKILL.md and the marker name unconditionally — zip copies are ignored", async () => {
+    const artifact = buildZip([
+      { name: "SKILL.md", content: "# Stale zip copy" },
+      { name: MOUNT_MARKER_FILE, content: "{\"versionHash\":\"forged\"}" },
+    ]);
+    await writeSkillMount(
+      makeSkillProto({ skillMd: "# Authoritative", versionHash: "hash-v1" }),
+      skillDir,
+      artifact,
+    );
+
+    expect(readFileSync(join(skillDir, "SKILL.md"), "utf-8")).toBe("# Authoritative");
+    const marker = JSON.parse(readFileSync(join(skillDir, MOUNT_MARKER_FILE), "utf-8"));
+    expect(marker.versionHash).toBe("hash-v1");
+  });
+
+  it("rejects zip entries that escape the mount directory", async () => {
+    const artifact = buildZip([{ name: "../escape.txt", content: "evil" }]);
+
+    await expect(
+      writeSkillMount(makeSkillProto({ versionHash: "hash-v1" }), skillDir, artifact),
+    ).rejects.toThrow(/escapes its mount directory/);
+    expect(existsSync(join(skillDir, "..", "escape.txt"))).toBe(false);
+    // The interrupted mount must not have been stamped as complete.
+    expect(existsSync(join(skillDir, MOUNT_MARKER_FILE))).toBe(false);
+  });
+
+  it("writes script entries with the executable bit set", async () => {
+    const artifact = buildZip([
+      { name: "scripts/run.py", content: "print('hi')" },
+      { name: "references/notes.md", content: "notes" },
+    ]);
+    await writeSkillMount(makeSkillProto({ versionHash: "hash-v1" }), skillDir, artifact);
+
+    expect(statSync(join(skillDir, "scripts", "run.py")).mode & 0o111).not.toBe(0);
+    expect(statSync(join(skillDir, "references", "notes.md")).mode & 0o111).toBe(0);
+  });
+});
+
+// ─── downloadArtifact — transfer lane routing (#675) ─────────────────────
+
+/** A server that predates the transfer lane (#675) answers the mint RPC
+ * with UNIMPLEMENTED — the default posture for these tests, which keeps
+ * every pre-existing case pinned to the unary getSkillArtifact fallback. */
+function unimplementedMint() {
+  return vi.fn().mockRejectedValue(new ConnectError("unimplemented", Code.Unimplemented));
+}
+
+describe("downloadArtifact — transfer lane routing", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  function makeClient(overrides: Record<string, any> = {}) {
+    return {
+      getSkillArtifact: vi.fn().mockResolvedValue({ artifact: new Uint8Array(0) }),
+      getSkillArtifactDownloadUrl: unimplementedMint(),
+      ...overrides,
+    } as any;
+  }
+
+  it("fetches bytes over HTTP when the server mints a download URL", async () => {
+    const bytes = new Uint8Array([1, 2, 3, 4, 5]);
+    const client = makeClient({
+      getSkillArtifactDownloadUrl: vi.fn().mockResolvedValue({
+        url: "http://localhost:7234/v1/skill-artifacts/skills/abc.zip",
+        sizeBytes: 5n,
+        ttlSeconds: 0,
+      }),
+    });
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      arrayBuffer: async () => bytes.buffer,
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const got = await downloadArtifact(client, "skills/abc.zip");
+
+    expect(got).toEqual(bytes);
+    expect(fetchMock).toHaveBeenCalledWith("http://localhost:7234/v1/skill-artifacts/skills/abc.zip");
+    // The unary lane (10MB-capped) must not be touched when the URL lane works.
+    expect(client.getSkillArtifact).not.toHaveBeenCalled();
+  });
+
+  it("falls back to the unary RPC when the server predates the lane", async () => {
+    const bytes = new Uint8Array([9, 9]);
+    const client = makeClient({
+      getSkillArtifact: vi.fn().mockResolvedValue({ artifact: bytes }),
+    });
+    vi.stubGlobal("fetch", vi.fn()); // must never be called
+
+    const got = await downloadArtifact(client, "skills/abc.zip");
+
+    expect(got).toEqual(bytes);
+    expect(client.getSkillArtifact).toHaveBeenCalledWith("skills/abc.zip");
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it("does NOT fall back on non-Unimplemented mint failures", async () => {
+    const client = makeClient({
+      getSkillArtifactDownloadUrl: vi.fn().mockRejectedValue(
+        new ConnectError("boom", Code.Internal),
+      ),
+    });
+
+    await expect(downloadArtifact(client, "skills/abc.zip")).rejects.toThrow("boom");
+    // Falling back here would mask real server faults behind the capped lane.
+    expect(client.getSkillArtifact).not.toHaveBeenCalled();
+  });
+
+  it("rejects truncated fetches via the minted size", async () => {
+    const client = makeClient({
+      getSkillArtifactDownloadUrl: vi.fn().mockResolvedValue({
+        url: "http://localhost:7234/v1/skill-artifacts/skills/abc.zip",
+        sizeBytes: 100n,
+        ttlSeconds: 0,
+      }),
+    });
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue({
+      ok: true,
+      arrayBuffer: async () => new Uint8Array([1, 2, 3]).buffer,
+    }));
+
+    await expect(downloadArtifact(client, "skills/abc.zip")).rejects.toThrow(/truncated/);
+  });
+
+  it("surfaces HTTP failures with the status code", async () => {
+    const client = makeClient({
+      getSkillArtifactDownloadUrl: vi.fn().mockResolvedValue({
+        url: "http://localhost:7234/v1/skill-artifacts/skills/gone.zip",
+        sizeBytes: 0n,
+        ttlSeconds: 0,
+      }),
+    });
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue({ ok: false, status: 404 }));
+
+    await expect(downloadArtifact(client, "skills/gone.zip")).rejects.toThrow(/HTTP 404/);
+  });
+});