@stigmer/runner 3.0.1

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

@@ -0,0 +1,349 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import {
+  mergeSkillRefs,
+  fetchSkillsByRefs,
+  writeSkills,
+  computeSkillPaths,
+  checkSkillIntegrity,
+  generatePromptSection,
+  generateAlsoAvailableSection,
+  fetchSkillArtifacts,
+} from "../skill-writer.js";
+import type { Skill } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
+import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import type { WorkspaceBackend } from "../workspace/types.js";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────
+
+function makeSkill(overrides: {
+  id?: string;
+  name?: string;
+  slug?: string;
+  description?: string;
+  skillMd?: string;
+  artifactStorageKey?: string;
+} = {}): Skill {
+  return {
+    metadata: {
+      id: overrides.id ?? "skill-id-1",
+      name: overrides.name ?? overrides.slug ?? "test-skill",
+      slug: overrides.slug ?? "test-skill",
+      org: "test-org",
+    },
+    spec: {
+      name: overrides.name ?? "test-skill",
+      description: overrides.description ?? "A test skill",
+      skillMd: overrides.skillMd ?? "# Test Skill\n\nDoes testing.",
+      tag: "",
+    },
+    status: {
+      artifactStorageKey: overrides.artifactStorageKey ?? "",
+      versionHash: "abc123",
+      state: "active",
+    },
+  } as any;
+}
+
+function makeRef(slug: string, org = "test-org"): ApiResourceReference {
+  return { slug, org, kind: 43 } as any;
+}
+
+function makeMockClient(overrides: Record<string, unknown> = {}) {
+  return {
+    getSkillByReference: vi.fn().mockImplementation((ref: any) =>
+      Promise.resolve(makeSkill({ slug: ref.slug, name: ref.slug })),
+    ),
+    getSkillArtifact: vi.fn().mockResolvedValue({ artifact: new Uint8Array(0) }),
+    ...overrides,
+  } as any;
+}
+
+function makeMockBackend(): WorkspaceBackend & {
+  writtenFiles: Map<string, string>;
+  executedCommands: string[];
+  existingFiles: Set<string>;
+} {
+  const writtenFiles = new Map<string, string>();
+  const executedCommands: string[] = [];
+  const existingFiles = new Set<string>();
+  return {
+    rootDir: "/workspace",
+    writtenFiles,
+    executedCommands,
+    existingFiles,
+    async writeFile(path: string, content: string) {
+      writtenFiles.set(path, content);
+    },
+    async writeFileBuffer(path: string, content: Buffer) {
+      writtenFiles.set(path, content.toString("utf-8"));
+    },
+    async readFile(path: string) {
+      return writtenFiles.get(path) ?? "";
+    },
+    async exists(path: string) {
+      return writtenFiles.has(path) || existingFiles.has(path);
+    },
+    async execute(command: string) {
+      executedCommands.push(command);
+      return "";
+    },
+  };
+}
+
+// ─── mergeSkillRefs ──────────────────────────────────────────────────────
+
+describe("mergeSkillRefs", () => {
+  it("returns empty for no refs", () => {
+    expect(mergeSkillRefs([], [])).toEqual([]);
+  });
+
+  it("returns agent refs when no session refs", () => {
+    const refs = [makeRef("skill-a"), makeRef("skill-b")];
+    const result = mergeSkillRefs(refs, []);
+    expect(result).toHaveLength(2);
+    expect(result.map(r => r.slug)).toEqual(["skill-a", "skill-b"]);
+  });
+
+  it("deduplicates by slug with session winning", () => {
+    const agentRefs = [makeRef("skill-a", "org1")];
+    const sessionRefs = [makeRef("skill-a", "org2")];
+    const result = mergeSkillRefs(agentRefs, sessionRefs);
+    expect(result).toHaveLength(1);
+    expect(result[0].org).toBe("org2");
+  });
+
+  it("unions unique skills from both sources", () => {
+    const agentRefs = [makeRef("skill-a")];
+    const sessionRefs = [makeRef("skill-b")];
+    const result = mergeSkillRefs(agentRefs, sessionRefs);
+    expect(result).toHaveLength(2);
+  });
+});
+
+// ─── fetchSkillsByRefs ───────────────────────────────────────────────────
+
+describe("fetchSkillsByRefs", () => {
+  it("returns empty for no refs", async () => {
+    const client = makeMockClient();
+    const result = await fetchSkillsByRefs(client, []);
+    expect(result).toEqual([]);
+    expect(client.getSkillByReference).not.toHaveBeenCalled();
+  });
+
+  it("fetches all skills by reference", async () => {
+    const client = makeMockClient();
+    const refs = [makeRef("skill-a"), makeRef("skill-b")];
+    const result = await fetchSkillsByRefs(client, refs);
+    expect(result).toHaveLength(2);
+    expect(client.getSkillByReference).toHaveBeenCalledTimes(2);
+  });
+
+  it("skips failed fetches gracefully", async () => {
+    const client = makeMockClient({
+      getSkillByReference: vi.fn()
+        .mockResolvedValueOnce(makeSkill({ name: "good", slug: "good" }))
+        .mockRejectedValueOnce(new Error("Not found")),
+    });
+    const refs = [makeRef("good"), makeRef("bad")];
+    const result = await fetchSkillsByRefs(client, refs);
+    expect(result).toHaveLength(1);
+    expect(result[0].spec!.name).toBe("good");
+  });
+});
+
+// ─── writeSkills ─────────────────────────────────────────────────────────
+
+describe("writeSkills", () => {
+  it("writes SKILL.md from spec when no artifact", async () => {
+    const backend = makeMockBackend();
+    const skills = [makeSkill({ name: "calculator", skillMd: "# Calculator\n\nAdds numbers." })];
+    const result = await writeSkills(skills, backend, new Map());
+
+    expect(result.paths.get("skill-id-1")).toBe(".stigmer/skills/calculator");
+    expect(backend.writtenFiles.has(".stigmer/skills/calculator/SKILL.md")).toBe(true);
+    expect(backend.writtenFiles.get(".stigmer/skills/calculator/SKILL.md"))
+      .toBe("# Calculator\n\nAdds numbers.");
+  });
+
+  it("runs chmod on script extensions", async () => {
+    const backend = makeMockBackend();
+    const skills = [makeSkill({ name: "runner" })];
+    await writeSkills(skills, backend, new Map());
+    expect(backend.executedCommands.length).toBeGreaterThan(0);
+    expect(backend.executedCommands[0]).toContain("chmod");
+  });
+
+  it("handles multiple skills", async () => {
+    const backend = makeMockBackend();
+    const skills = [
+      makeSkill({ id: "id-1", name: "skill-a", skillMd: "# A" }),
+      makeSkill({ id: "id-2", name: "skill-b", skillMd: "# B" }),
+    ];
+    const result = await writeSkills(skills, backend, new Map());
+    expect(result.paths.size).toBe(2);
+    expect(result.paths.get("id-1")).toBe(".stigmer/skills/skill-a");
+    expect(result.paths.get("id-2")).toBe(".stigmer/skills/skill-b");
+  });
+
+  it("skips write when skill has no skillMd and no artifact", async () => {
+    const backend = makeMockBackend();
+    const skills = [makeSkill({ skillMd: "" })];
+    (skills[0] as any).spec.skillMd = "";
+    await writeSkills(skills, backend, new Map());
+    expect(backend.writtenFiles.size).toBe(0);
+  });
+});
+
+// ─── computeSkillPaths ───────────────────────────────────────────────────
+
+describe("computeSkillPaths", () => {
+  it("computes paths without side effects", () => {
+    const skills = [
+      makeSkill({ id: "id-1", name: "calculator" }),
+      makeSkill({ id: "id-2", name: "web-scraper" }),
+    ];
+    const paths = computeSkillPaths(skills);
+    expect(paths.get("id-1")).toBe(".stigmer/skills/calculator");
+    expect(paths.get("id-2")).toBe(".stigmer/skills/web-scraper");
+  });
+
+  it("returns empty map for empty skills", () => {
+    expect(computeSkillPaths([])).toEqual(new Map());
+  });
+});
+
+// ─── checkSkillIntegrity ─────────────────────────────────────────────────
+
+describe("checkSkillIntegrity", () => {
+  it("returns true when sentinel exists", async () => {
+    const backend = makeMockBackend();
+    backend.existingFiles.add(".stigmer/skills/calculator/SKILL.md");
+    const skills = [makeSkill({ id: "id-1", name: "calculator" })];
+    expect(await checkSkillIntegrity(skills, backend)).toBe(true);
+  });
+
+  it("returns false when sentinel is missing", async () => {
+    const backend = makeMockBackend();
+    const skills = [makeSkill({ id: "id-1", name: "calculator" })];
+    expect(await checkSkillIntegrity(skills, backend)).toBe(false);
+  });
+
+  it("returns true for empty skills list", async () => {
+    const backend = makeMockBackend();
+    expect(await checkSkillIntegrity([], backend)).toBe(true);
+  });
+});
+
+// ─── generatePromptSection ───────────────────────────────────────────────
+
+describe("generatePromptSection", () => {
+  it("returns empty string for no skills", () => {
+    expect(generatePromptSection([], new Map())).toBe("");
+  });
+
+  it("generates progressive disclosure format", () => {
+    const skills = [makeSkill({ name: "calculator", description: "Arithmetic operations" })];
+    const paths = new Map([["skill-id-1", ".stigmer/skills/calculator"]]);
+    const section = generatePromptSection(skills, paths);
+
+    expect(section).toContain("## Skills");
+    expect(section).toContain("### calculator");
+    expect(section).toContain("**Description**: Arithmetic operations");
+    expect(section).toContain("**Location**: `.stigmer/skills/calculator/`");
+    expect(section).toContain("**Activate**: `read .stigmer/skills/calculator/SKILL.md`");
+  });
+
+  it("includes activation protocol instructions", () => {
+    const skills = [makeSkill()];
+    const paths = new Map([["skill-id-1", ".stigmer/skills/test-skill"]]);
+    const section = generatePromptSection(skills, paths);
+
+    expect(section).toContain("Activation protocol");
+    expect(section).toContain("read its SKILL.md");
+  });
+
+  it("handles multiple skills", () => {
+    const skills = [
+      makeSkill({ id: "id-1", name: "skill-a", description: "Desc A" }),
+      makeSkill({ id: "id-2", name: "skill-b", description: "Desc B" }),
+    ];
+    const paths = new Map([
+      ["id-1", ".stigmer/skills/skill-a"],
+      ["id-2", ".stigmer/skills/skill-b"],
+    ]);
+    const section = generatePromptSection(skills, paths);
+
+    expect(section).toContain("### skill-a");
+    expect(section).toContain("### skill-b");
+    expect(section).toContain("Desc A");
+    expect(section).toContain("Desc B");
+  });
+
+  it("falls back to (no description) when empty", () => {
+    const skills = [makeSkill({ description: "" })];
+    (skills[0] as any).spec.description = "";
+    const paths = new Map([["skill-id-1", ".stigmer/skills/test-skill"]]);
+    const section = generatePromptSection(skills, paths);
+    expect(section).toContain("(no description)");
+  });
+});
+
+// ─── generateAlsoAvailableSection ────────────────────────────────────────
+
+describe("generateAlsoAvailableSection", () => {
+  it("returns empty for no excluded names", () => {
+    expect(generateAlsoAvailableSection([])).toBe("");
+  });
+
+  it("lists excluded skills with backtick formatting", () => {
+    const section = generateAlsoAvailableSection(["alpha", "beta", "gamma"]);
+    expect(section).toContain("### Also Available");
+    expect(section).toContain("`alpha`");
+    expect(section).toContain("`beta`");
+    expect(section).toContain("`gamma`");
+  });
+
+  it("includes activation instructions", () => {
+    const section = generateAlsoAvailableSection(["some-skill"]);
+    expect(section).toContain(".stigmer/skills/<name>/SKILL.md");
+    expect(section).toContain("relevant to your task");
+  });
+});
+
+// ─── fetchSkillArtifacts ─────────────────────────────────────────────────
+
+describe("fetchSkillArtifacts", () => {
+  it("returns empty map when no skills have artifacts", async () => {
+    const client = makeMockClient();
+    const skills = [makeSkill({ artifactStorageKey: "" })];
+    const result = await fetchSkillArtifacts(client, skills);
+    expect(result.size).toBe(0);
+    expect(client.getSkillArtifact).not.toHaveBeenCalled();
+  });
+
+  it("fetches artifacts for skills with storage keys", async () => {
+    const artifactData = new Uint8Array([80, 75, 3, 4]); // ZIP magic bytes
+    const client = makeMockClient({
+      getSkillArtifact: vi.fn().mockResolvedValue({ artifact: artifactData }),
+    });
+    const skills = [makeSkill({ id: "id-1", artifactStorageKey: "artifacts/key.zip" })];
+    const result = await fetchSkillArtifacts(client, skills);
+    expect(result.size).toBe(1);
+    expect(result.get("id-1")).toEqual(artifactData);
+  });
+
+  it("handles partial failures gracefully", async () => {
+    const client = makeMockClient({
+      getSkillArtifact: vi.fn()
+        .mockResolvedValueOnce({ artifact: new Uint8Array([1, 2, 3]) })
+        .mockRejectedValueOnce(new Error("Network error")),
+    });
+    const skills = [
+      makeSkill({ id: "id-1", name: "good", artifactStorageKey: "key1" }),
+      makeSkill({ id: "id-2", name: "bad", artifactStorageKey: "key2" }),
+    ];
+    const result = await fetchSkillArtifacts(client, skills);
+    expect(result.size).toBe(1);
+    expect(result.has("id-1")).toBe(true);
+  });
+});

package/src/shared/__tests__/status.test.ts

@@ -0,0 +1,142 @@
+import { describe, it, expect, vi } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionControlSignal, ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { utcTimestamp, persistStatus, reportSetupProgress, slimStatus } from "../status.js";
+
+describe("utcTimestamp", () => {
+  it("returns an ISO 8601 string ending in Z", () => {
+    const ts = utcTimestamp();
+    expect(ts).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z$/);
+  });
+
+  it("returns current time within 1 second tolerance", () => {
+    const before = Date.now();
+    const ts = utcTimestamp();
+    const after = Date.now();
+    const parsed = new Date(ts).getTime();
+    expect(parsed).toBeGreaterThanOrEqual(before);
+    expect(parsed).toBeLessThanOrEqual(after);
+  });
+});
+
+describe("slimStatus", () => {
+  it("preserves phase, error, timestamps, and pendingApprovals", () => {
+    const full = create(AgentExecutionStatusSchema, {
+      phase: ExecutionPhase.EXECUTION_COMPLETED,
+      error: "test error",
+      startedAt: "2026-01-01T00:00:00Z",
+      completedAt: "2026-01-01T00:01:00Z",
+    });
+    const result = slimStatus(full) as Record<string, unknown>;
+    expect(result).toHaveProperty("phase");
+    expect(result).toHaveProperty("error", "test error");
+    expect(result).toHaveProperty("startedAt", "2026-01-01T00:00:00Z");
+    expect(result).toHaveProperty("completedAt", "2026-01-01T00:01:00Z");
+  });
+
+  it("excludes heavy fields like messages", () => {
+    const full = create(AgentExecutionStatusSchema, {
+      phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+    });
+    const result = slimStatus(full) as Record<string, unknown>;
+    expect(result).not.toHaveProperty("messages");
+    expect(result).not.toHaveProperty("todos");
+  });
+
+  it("returns a plain JSON-serializable object (not a protobuf Message)", () => {
+    const full = create(AgentExecutionStatusSchema, {
+      phase: ExecutionPhase.EXECUTION_FAILED,
+    });
+    const result = slimStatus(full);
+    const json = JSON.stringify(result);
+    expect(json).toBeTruthy();
+    expect(JSON.parse(json)).toEqual(result);
+  });
+
+  it("preserves structuredOutput when present on the full status", () => {
+    const full = create(AgentExecutionStatusSchema, {
+      phase: ExecutionPhase.EXECUTION_COMPLETED,
+      structuredOutput: {
+        executive_summary: "DAU stable at 7175",
+        dau: 7175,
+        cohorts: [
+          { name: "D1 New Players", size: 10, action_needed: true },
+          { name: "D3 Drop-offs", size: 3589, action_needed: true },
+        ],
+      },
+    });
+    const result = slimStatus(full) as Record<string, unknown>;
+    expect(result).toHaveProperty("structuredOutput");
+    const output = (result as any).structuredOutput;
+    expect(output.executive_summary).toBe("DAU stable at 7175");
+    expect(output.dau).toBe(7175);
+    expect(output.cohorts).toHaveLength(2);
+  });
+
+  it("omits structuredOutput when not present on full status", () => {
+    const full = create(AgentExecutionStatusSchema, {
+      phase: ExecutionPhase.EXECUTION_COMPLETED,
+    });
+    const result = slimStatus(full) as Record<string, unknown>;
+    expect(result).not.toHaveProperty("structuredOutput");
+  });
+
+  it("activity return contains structuredOutput accessible by Go buildCallbackResult", () => {
+    const full = create(AgentExecutionStatusSchema, {
+      phase: ExecutionPhase.EXECUTION_COMPLETED,
+      structuredOutput: {
+        cohorts: [{ name: "D1", size: 500 }],
+      },
+    });
+    const slim = slimStatus(full) as Record<string, unknown>;
+    expect(slim["structuredOutput"]).toBeDefined();
+    expect((slim["structuredOutput"] as any).cohorts).toHaveLength(1);
+  });
+});
+
+describe("persistStatus", () => {
+  it("returns the control signal from the backend", async () => {
+    const mockClient = {
+      updateStatus: vi.fn().mockResolvedValue({
+        signal: ExecutionControlSignal.STOP,
+      }),
+    } as any;
+    const status = create(AgentExecutionStatusSchema, {
+      phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+    });
+    const signal = await persistStatus(mockClient, "exec-1", status);
+    expect(signal).toBe(ExecutionControlSignal.STOP);
+    expect(mockClient.updateStatus).toHaveBeenCalledWith("exec-1", status);
+  });
+
+  it("returns UNSPECIFIED and logs on error", async () => {
+    const mockClient = {
+      updateStatus: vi.fn().mockRejectedValue(new Error("network")),
+    } as any;
+    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const status = create(AgentExecutionStatusSchema, {
+      phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+    });
+    const signal = await persistStatus(mockClient, "exec-2", status);
+    expect(signal).toBe(ExecutionControlSignal.UNSPECIFIED);
+    expect(consoleSpy).toHaveBeenCalled();
+    consoleSpy.mockRestore();
+  });
+});
+
+describe("reportSetupProgress", () => {
+  it("persists a status with the given phase name", async () => {
+    const mockClient = {
+      updateStatus: vi.fn().mockResolvedValue({
+        signal: ExecutionControlSignal.UNSPECIFIED,
+      }),
+    } as any;
+    await reportSetupProgress(mockClient, "exec-3", "Resolving MCP servers");
+    expect(mockClient.updateStatus).toHaveBeenCalledOnce();
+    const [id, status] = mockClient.updateStatus.mock.calls[0];
+    expect(id).toBe("exec-3");
+    expect(status.phase).toBe(ExecutionPhase.EXECUTION_IN_PROGRESS);
+    expect(status.setupProgress?.currentPhase).toBe("Resolving MCP servers");
+  });
+});

package/src/shared/__tests__/subagent-gate.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect, vi } from "vitest";
+import { SubAgentGate } from "../subagent-gate.js";
+
+describe("SubAgentGate", () => {
+  it("allows invocations under the concurrency limit", async () => {
+    const gate = new SubAgentGate({ maxConcurrent: 2 });
+    const invoke = vi.fn().mockResolvedValue({ messages: [{ content: "done" }] });
+
+    const wrapped = gate.wrap(invoke, "test-agent");
+    const result = await wrapped({ task: "hello" });
+
+    expect(invoke).toHaveBeenCalledWith({ task: "hello" }, undefined);
+    expect(result).toEqual({ messages: [{ content: "done" }] });
+    expect(gate.activeCount).toBe(0);
+  });
+
+  it("rejects when at capacity with an error-shaped response", async () => {
+    const gate = new SubAgentGate({ maxConcurrent: 1 });
+
+    let resolveFirst!: () => void;
+    const blockingPromise = new Promise<void>(r => { resolveFirst = r; });
+    const invoke = vi.fn().mockImplementation(() => blockingPromise.then(() => ({ ok: true })));
+
+    const wrapped = gate.wrap(invoke, "blocker");
+
+    const first = wrapped({ task: "1" });
+    expect(gate.activeCount).toBe(1);
+
+    const second = await wrapped({ task: "2" });
+    expect(second).toEqual(
+      expect.objectContaining({
+        messages: expect.arrayContaining([
+          expect.objectContaining({
+            content: expect.stringContaining("was NOT started"),
+          }),
+        ]),
+      }),
+    );
+
+    expect(invoke).toHaveBeenCalledTimes(1);
+
+    resolveFirst();
+    await first;
+    expect(gate.activeCount).toBe(0);
+  });
+
+  it("releases slot on error", async () => {
+    const gate = new SubAgentGate({ maxConcurrent: 1 });
+    const invoke = vi.fn().mockRejectedValue(new Error("boom"));
+
+    const wrapped = gate.wrap(invoke, "failing-agent");
+
+    await expect(wrapped({ task: "crash" })).rejects.toThrow("boom");
+    expect(gate.activeCount).toBe(0);
+    expect(gate.hasCapacity).toBe(true);
+  });
+
+  it("tracks concurrent invocations correctly", async () => {
+    const gate = new SubAgentGate({ maxConcurrent: 3 });
+    const resolvers: Array<() => void> = [];
+    const invoke = vi.fn().mockImplementation(() =>
+      new Promise<{ ok: boolean }>(r => { resolvers.push(() => r({ ok: true })); }),
+    );
+
+    const wrapped = gate.wrap(invoke, "agent");
+
+    const p1 = wrapped({ n: 1 });
+    const p2 = wrapped({ n: 2 });
+    const p3 = wrapped({ n: 3 });
+
+    expect(gate.activeCount).toBe(3);
+    expect(gate.hasCapacity).toBe(false);
+
+    const rejected = await wrapped({ n: 4 });
+    expect((rejected as { messages: unknown[] }).messages).toBeDefined();
+
+    resolvers[0]();
+    await p1;
+    expect(gate.activeCount).toBe(2);
+    expect(gate.hasCapacity).toBe(true);
+
+    resolvers[1]();
+    resolvers[2]();
+    await Promise.all([p2, p3]);
+    expect(gate.activeCount).toBe(0);
+  });
+
+  it("throws on invalid maxConcurrent", () => {
+    expect(() => new SubAgentGate({ maxConcurrent: 0 })).toThrow("positive");
+    expect(() => new SubAgentGate({ maxConcurrent: -1 })).toThrow("positive");
+  });
+
+  it("defaults to 3 concurrent", () => {
+    const gate = new SubAgentGate();
+    expect(gate.maxConcurrent).toBe(3);
+  });
+
+  it("includes agent name in rejection message", async () => {
+    const gate = new SubAgentGate({ maxConcurrent: 1 });
+    const invoke = vi.fn().mockImplementation(
+      () => new Promise(() => {}),
+    );
+
+    const wrapped = gate.wrap(invoke, "research-agent");
+    wrapped({ task: "1" });
+
+    const rejection = await wrapped({ task: "2" });
+    const content = (rejection as { messages: Array<{ content: string }> }).messages[0].content;
+    expect(content).toContain("research-agent");
+    expect(content).toContain("1");
+  });
+});

package/src/shared/__tests__/tool-kind.test.ts

@@ -0,0 +1,58 @@
+/**
+ * Tool classification tests.
+ *
+ * Validates classifyTool against the shared cross-language contract in
+ * test/fixtures/tool-view/classification.json, so the runner, the SDK fallback
+ * resolver, and the Go CLI cannot drift apart.
+ */
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { describe, it, expect } from "vitest";
+import { ToolKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { classifyTool } from "../tool-kind.js";
+
+const here = dirname(fileURLToPath(import.meta.url));
+// runner/src/shared/__tests__ -> repo root is five levels up.
+const fixturePath = resolve(
+  here,
+  "../../../../../../test/fixtures/tool-view/classification.json",
+);
+
+interface ClassificationCase {
+  name: string;
+  mcpServerSlug: string;
+  toolKind: keyof typeof ToolKind;
+}
+
+const fixture = JSON.parse(readFileSync(fixturePath, "utf8")) as {
+  cases: ClassificationCase[];
+};
+
+describe("classifyTool", () => {
+  it("loads the shared classification fixture", () => {
+    expect(fixture.cases.length).toBeGreaterThan(0);
+  });
+
+  for (const c of fixture.cases) {
+    it(`classifies ${c.name || "(empty)"}${c.mcpServerSlug ? ` @${c.mcpServerSlug}` : ""} as ${c.toolKind}`, () => {
+      // Fixture uses the proto enum value name (TOOL_KIND_FILE_EDIT); the
+      // generated TS enum strips the prefix (FILE_EDIT), so map across.
+      const expected = ToolKind[c.toolKind.replace(/^TOOL_KIND_/, "") as keyof typeof ToolKind];
+      expect(classifyTool(c.name, c.mcpServerSlug)).toBe(expected);
+    });
+  }
+
+  it("returns UNSPECIFIED for an unknown built-in with no slug", () => {
+    expect(classifyTool("totally_unknown")).toBe(ToolKind.UNSPECIFIED);
+  });
+
+  it("returns MCP for an unknown tool with a slug", () => {
+    expect(classifyTool("totally_unknown", "planton")).toBe(ToolKind.MCP);
+  });
+
+  it("prefers a built-in name over a slug", () => {
+    expect(classifyTool("read", "planton")).toBe(ToolKind.FILE_READ);
+  });
+});