@stigmer/sdk 3.0.9-dev.20260615153829 → 3.1.0

package/src/execution/__tests__/tool-view.search.test.ts

@@ -0,0 +1,264 @@
+// Covers search normalization's envelope handling: the Cursor SDK returns search
+// results as a stringified JSON envelope (file-name search via {status,value} and
+// grep/codebase search via {workspaceResults}), which the original parser dumped
+// as a single fake "match". The cross-language fixture (result-views.json)
+// asserts the happy-path `type`/`count`; these cover the `kind`/`truncated`
+// presentation hints, the multi-workspace flatten, the content-match mapping, and
+// the unrecognized-JSON -> json degradation that is not a shared scalar fact.
+
+import { describe, it, expect } from "vitest";
+import { create, type JsonObject } from "@bufbuild/protobuf";
+import { ToolCallSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import {
+  ToolCallStatus,
+  ToolKind,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { normalizeToolResult } from "../tool-view";
+
+function searchCall(args: Record<string, unknown>, result: string) {
+  return create(ToolCallSchema, {
+    id: "tc-search",
+    name: "Grep",
+    toolKind: ToolKind.SEARCH,
+    status: ToolCallStatus.TOOL_CALL_COMPLETED,
+    args: args as JsonObject,
+    result,
+  });
+}
+
+describe("normalizeToolResult — Cursor file-name search envelope", () => {
+  it("unwraps an empty {status,value} file search (the reported bug: not '1 match')", () => {
+    const view = normalizeToolResult(
+      searchCall(
+        { pattern: "**/*.nope" },
+        JSON.stringify({
+          status: "success",
+          value: { files: [], totalFiles: 0, clientTruncated: false, ripgrepTruncated: false },
+        }),
+      ),
+    );
+    expect(view.type).toBe("search");
+    if (view.type !== "search") return;
+    expect(view.kind).toBe("files");
+    expect(view.count).toBe(0);
+    expect(view.matches).toHaveLength(0);
+    expect(view.truncated).toBe(false);
+  });
+
+  it("unwraps a non-empty file search into clickable file matches", () => {
+    const view = normalizeToolResult(
+      searchCall(
+        { pattern: "Dockerfile" },
+        JSON.stringify({
+          status: "success",
+          value: { files: ["Dockerfile"], totalFiles: 1, clientTruncated: false, ripgrepTruncated: false },
+        }),
+      ),
+    );
+    expect(view.type).toBe("search");
+    if (view.type !== "search") return;
+    expect(view.kind).toBe("files");
+    expect(view.count).toBe(1);
+    // Both file and text are set so a kind-unaware consumer still shows the path.
+    expect(view.matches[0]).toEqual({ file: "Dockerfile", text: "Dockerfile" });
+  });
+
+  it("carries the engine's truncation flags and authoritative totalFiles", () => {
+    const view = normalizeToolResult(
+      searchCall(
+        { pattern: "*.ts" },
+        JSON.stringify({
+          status: "success",
+          value: { files: ["a.ts", "b.ts"], totalFiles: 200, clientTruncated: true, ripgrepTruncated: false },
+        }),
+      ),
+    );
+    expect(view.type).toBe("search");
+    if (view.type !== "search") return;
+    // totalFiles is authoritative and can exceed the returned page.
+    expect(view.count).toBe(200);
+    expect(view.matches).toHaveLength(2);
+    expect(view.truncated).toBe(true);
+  });
+});
+
+describe("normalizeToolResult — Cursor grep workspaceResults envelope", () => {
+  it("unwraps the real {status,value:{workspaceResults}} grep shape (the reported bug)", () => {
+    // The grep payload nests workspaceResults INSIDE the {status,value} envelope —
+    // the shape the runner actually persists. The original parser only looked at
+    // the top level, so this fell through to a raw JSON dump.
+    const view = normalizeToolResult(
+      searchCall(
+        { pattern: "pipeline" },
+        JSON.stringify({
+          status: "success",
+          value: {
+            workspaceResults: {
+              "/work/demo": { type: "files", output: { files: [], count: 0 } },
+            },
+          },
+        }),
+      ),
+    );
+    expect(view.type).toBe("search");
+    if (view.type !== "search") return;
+    expect(view.kind).toBe("files");
+    expect(view.count).toBe(0);
+  });
+
+  it("still reads an un-enveloped top-level workspaceResults (defensive)", () => {
+    const view = normalizeToolResult(
+      searchCall(
+        { pattern: "pipeline" },
+        JSON.stringify({
+          workspaceResults: { "/work/demo": { type: "files", output: { files: [], count: 0 } } },
+        }),
+      ),
+    );
+    expect(view.type).toBe("search");
+    if (view.type !== "search") return;
+    expect(view.kind).toBe("files");
+    expect(view.count).toBe(0);
+  });
+
+  it("flattens file matches across multiple workspaces and sums reported counts", () => {
+    const view = normalizeToolResult(
+      searchCall(
+        { pattern: "TODO" },
+        JSON.stringify({
+          status: "success",
+          value: {
+            workspaceResults: {
+              "/work/a": { type: "files", output: { files: ["a/x.ts"], count: 1 } },
+              "/work/b": { type: "files", output: { files: ["b/y.ts"], count: 1 } },
+            },
+          },
+        }),
+      ),
+    );
+    expect(view.type).toBe("search");
+    if (view.type !== "search") return;
+    expect(view.kind).toBe("files");
+    expect(view.count).toBe(2);
+    expect(view.matches.map((m) => m.file)).toEqual(["a/x.ts", "b/y.ts"]);
+  });
+
+  it("renders a non-empty grep (type:files) as a file list, not 0 files", () => {
+    // The real wrapped shape with results present — proves a populated grep is
+    // shown (the user's concern that a non-empty response might render as empty).
+    const view = normalizeToolResult(
+      searchCall(
+        { pattern: "pipeline" },
+        JSON.stringify({
+          status: "success",
+          value: {
+            workspaceResults: {
+              "/work/demo": {
+                type: "files",
+                output: { files: [".tekton/pipeline.yaml", "README.md"], count: 2 },
+              },
+            },
+          },
+        }),
+      ),
+    );
+    expect(view.type).toBe("search");
+    if (view.type !== "search") return;
+    expect(view.kind).toBe("files");
+    expect(view.count).toBe(2);
+    expect(view.matches.map((m) => m.file)).toEqual([".tekton/pipeline.yaml", "README.md"]);
+  });
+
+  it("falls back to JSON (never hides data) when a count is reported but nothing extracts", () => {
+    // Shape drift: the engine says count:5 but the matches live under a key we
+    // don't recognise. Surfacing the raw JSON beats a misleading "No matches".
+    const view = normalizeToolResult(
+      searchCall(
+        { pattern: "x" },
+        JSON.stringify({
+          status: "success",
+          value: {
+            workspaceResults: {
+              "/work/demo": { type: "weird", output: { hits: ["a", "b"], count: 5 } },
+            },
+          },
+        }),
+      ),
+    );
+    expect(view.type).toBe("json");
+  });
+
+  it("falls back to JSON when a file search reports totalFiles but no extractable paths", () => {
+    // files are objects, not strings (a drift) — but totalFiles says 3.
+    const view = normalizeToolResult(
+      searchCall(
+        { pattern: "*.ts" },
+        JSON.stringify({
+          status: "success",
+          value: { files: [{ path: "a.ts" }], totalFiles: 3 },
+        }),
+      ),
+    );
+    expect(view.type).toBe("json");
+  });
+
+  it("maps line-bearing matches into grouped content matches", () => {
+    const view = normalizeToolResult(
+      searchCall(
+        { pattern: "TODO" },
+        JSON.stringify({
+          status: "success",
+          value: {
+            workspaceResults: {
+              "/work/a": {
+                type: "matches",
+                output: {
+                  matches: [
+                    { file: "a/x.ts", line: 12, text: "// TODO: fix" },
+                    { file: "a/x.ts", line: 30, text: "// TODO: later" },
+                  ],
+                  count: 2,
+                },
+              },
+            },
+          },
+        }),
+      ),
+    );
+    expect(view.type).toBe("search");
+    if (view.type !== "search") return;
+    expect(view.kind).toBe("content");
+    expect(view.count).toBe(2);
+    expect(view.matches[0]).toEqual({ file: "a/x.ts", line: 12, text: "// TODO: fix" });
+  });
+});
+
+describe("normalizeToolResult — search plain text and graceful degradation", () => {
+  it("keeps native grep line matches as content (unchanged behavior)", () => {
+    const view = normalizeToolResult(
+      searchCall(
+        { pattern: "TODO" },
+        "\n/workspace/a.go:\n  12: // TODO: fix\n/workspace/b.go:\n  7: // TODO: later",
+      ),
+    );
+    expect(view.type).toBe("search");
+    if (view.type !== "search") return;
+    expect(view.kind).toBe("content");
+    expect(view.count).toBe(2);
+  });
+
+  it("treats native path/name lines as file matches", () => {
+    const view = normalizeToolResult(searchCall({ pattern: "*.go" }, "src/a.go\nsrc/b.go"));
+    expect(view.type).toBe("search");
+    if (view.type !== "search") return;
+    expect(view.kind).toBe("files");
+    expect(view.count).toBe(2);
+  });
+
+  it("degrades an unrecognized JSON shape to a json view, not a fake match", () => {
+    const view = normalizeToolResult(
+      searchCall({ pattern: "x" }, JSON.stringify({ somethingElse: true })),
+    );
+    expect(view.type).toBe("json");
+  });
+});

package/src/execution/__tests__/tool-view.shell.test.ts

@@ -0,0 +1,127 @@
+// Covers shell normalization's `command` capture and result-shape handling: a
+// terminal view models the whole session (prompt + output), so the command is
+// echoed from args onto the view across every result shape — un-enveloped Cursor
+// JSON, the Cursor {status,value} envelope, the exit-marker form, and plain
+// text. The cross-language fixture (result-views.json) asserts the happy path;
+// these cover the branch matrix, the envelope unwrap (the reported bug), and the
+// missing-command edge.
+
+import { describe, it, expect } from "vitest";
+import { create, type JsonObject } from "@bufbuild/protobuf";
+import { ToolCallSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import {
+  ToolCallStatus,
+  ToolKind,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { normalizeToolResult } from "../tool-view";
+
+function shellCall(args: Record<string, unknown>, result: string) {
+  return create(ToolCallSchema, {
+    id: "tc-shell",
+    name: "shell",
+    toolKind: ToolKind.SHELL,
+    status: ToolCallStatus.TOOL_CALL_COMPLETED,
+    args: args as JsonObject,
+    result,
+  });
+}
+
+describe("normalizeToolResult — shell command capture", () => {
+  it("captures the command on the plain (no-marker) branch", () => {
+    const view = normalizeToolResult(shellCall({ command: "echo hi" }, "hi\n"));
+    expect(view.type).toBe("terminal");
+    if (view.type !== "terminal") return;
+    expect(view.command).toBe("echo hi");
+    expect(view.stdout).toBe("hi\n");
+  });
+
+  it("captures the command on the exit-marker branch (success and failure)", () => {
+    const ok = normalizeToolResult(
+      shellCall({ command: "ls -la" }, "total 8\n[Command succeeded]"),
+    );
+    expect(ok.type).toBe("terminal");
+    if (ok.type !== "terminal") return;
+    expect(ok.command).toBe("ls -la");
+    expect(ok.exitCode).toBe(0);
+
+    const bad = normalizeToolResult(
+      shellCall({ command: "false" }, "boom\n[Command failed with exit code 2]"),
+    );
+    expect(bad.type).toBe("terminal");
+    if (bad.type !== "terminal") return;
+    expect(bad.command).toBe("false");
+    expect(bad.exitCode).toBe(2);
+  });
+
+  it("captures the command on the structured Cursor JSON branch", () => {
+    const view = normalizeToolResult(
+      shellCall(
+        { command: "npm test" },
+        JSON.stringify({ stdout: "ok", stderr: "", exitCode: 0 }),
+      ),
+    );
+    expect(view.type).toBe("terminal");
+    if (view.type !== "terminal") return;
+    expect(view.command).toBe("npm test");
+    expect(view.stdout).toBe("ok");
+  });
+
+  it("unwraps the Cursor {status,value} envelope on success (the reported bug)", () => {
+    const view = normalizeToolResult(
+      shellCall(
+        { command: "ls -la" },
+        JSON.stringify({
+          status: "success",
+          value: {
+            exitCode: 0,
+            signal: "",
+            stdout: "total 8\ndrwxr-xr-x  2 user user 4096 .\n",
+            stderr: "",
+            executionTime: 1176,
+          },
+        }),
+      ),
+    );
+    expect(view.type).toBe("terminal");
+    if (view.type !== "terminal") return;
+    expect(view.command).toBe("ls -la");
+    // The real stdout surfaces — NOT the raw envelope JSON.
+    expect(view.stdout).toBe("total 8\ndrwxr-xr-x  2 user user 4096 .\n");
+    expect(view.exitCode).toBe(0);
+    // Regression guard: the envelope keys must never leak into the rendered output.
+    expect(view.stdout).not.toContain("status");
+    expect(view.stdout).not.toContain("value");
+    expect(view.stdout).not.toContain("executionTime");
+  });
+
+  it("unwraps the Cursor envelope on failure (surfaces stderr and exit code)", () => {
+    const view = normalizeToolResult(
+      shellCall(
+        { command: "ls /nope" },
+        JSON.stringify({
+          status: "success",
+          value: {
+            exitCode: 2,
+            signal: "",
+            stdout: "",
+            stderr: "ls: /nope: No such file or directory\n",
+            executionTime: 5,
+          },
+        }),
+      ),
+    );
+    expect(view.type).toBe("terminal");
+    if (view.type !== "terminal") return;
+    expect(view.command).toBe("ls /nope");
+    expect(view.stderr).toBe("ls: /nope: No such file or directory\n");
+    expect(view.exitCode).toBe(2);
+  });
+
+  it("leaves command undefined when args carry no command", () => {
+    const view = normalizeToolResult(shellCall({}, "orphan output\n"));
+    expect(view.type).toBe("terminal");
+    if (view.type !== "terminal") return;
+    expect(view.command).toBeUndefined();
+    expect(view.stdout).toBe("orphan output\n");
+  });
+});

package/src/execution/approval-provenance.ts

@@ -0,0 +1,80 @@
+// Framework-agnostic authorization-provenance labels for every Stigmer surface.
+//
+// describeApprovalPolicySource maps the wire ApprovalPolicySource — *which policy
+// layer decided a tool call's approval requirement* — to a short human phrase.
+// It is shared by @stigmer/react (the ApprovalCard "why-gated" line and the
+// tool-call detail view) and @stigmer/ink (the terminal approval prompt); the Go
+// CLI mirrors it. The phrasing is intrinsic to the source's semantics so the
+// same label reads correctly whether the call is still waiting (a gating source
+// → "required by …") or already cleared (a bypass source → "auto-approved …").
+
+import { ApprovalPolicySource } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+export { ApprovalPolicySource };
+
+/**
+ * Returns a short human phrase describing a tool call's authorization
+ * provenance, or `null` for {@link ApprovalPolicySource.UNSPECIFIED} — an
+ * execution that predates this field, or a tool the gate never evaluated (e.g. a
+ * read-only built-in) — so callers render nothing rather than a misleading
+ * default.
+ */
+export function describeApprovalPolicySource(
+  source: ApprovalPolicySource,
+): string | null {
+  switch (source) {
+    case ApprovalPolicySource.CLASSIFIER_DEFAULT:
+      return "required by the tool's default policy";
+    case ApprovalPolicySource.PINNED_OVERRIDE:
+      return "required by a pinned override";
+    case ApprovalPolicySource.AGENT_OVERRIDE:
+      return "required by agent override";
+    case ApprovalPolicySource.BUILTIN_CATEGORY:
+      return "required by built-in tool policy";
+    case ApprovalPolicySource.ANNOTATION_DESTRUCTIVE_TIGHTEN:
+      return "required: marked destructive by the server";
+    case ApprovalPolicySource.AUTO_APPROVE_ALL:
+      return "auto-approved by a run-wide bypass";
+    case ApprovalPolicySource.APPROVAL_LEASE:
+      return "auto-approved by a run lease";
+    case ApprovalPolicySource.UNSPECIFIED:
+    default:
+      return null;
+  }
+}
+
+/**
+ * Returns whether a policy source carries information worth surfacing inline at
+ * the approval gate, versus the everyday default ("this tool category just
+ * requires approval") that is noise next to the action it is already gating.
+ *
+ * The default gating reasons — {@link ApprovalPolicySource.CLASSIFIER_DEFAULT}
+ * and {@link ApprovalPolicySource.BUILTIN_CATEGORY} — explain nothing the user
+ * does not already infer from the tool itself, so they are suppressed from the
+ * card (the full phrase stays available on hover where a surface chooses to show
+ * a chip). The remaining sources each change the user's understanding of *why*
+ * this particular call is held — an explicit override, a server tightening a
+ * destructive tool, or (post-execution) a bypass/lease that cleared it — and so
+ * are worth showing. {@link ApprovalPolicySource.UNSPECIFIED} is never
+ * informative (legacy / ungated).
+ *
+ * This is the headless policy behind the gate's "smart-suppress" provenance
+ * chip; rendering lives in the consuming surface.
+ */
+export function isInformativePolicySource(
+  source: ApprovalPolicySource,
+): boolean {
+  switch (source) {
+    case ApprovalPolicySource.PINNED_OVERRIDE:
+    case ApprovalPolicySource.AGENT_OVERRIDE:
+    case ApprovalPolicySource.ANNOTATION_DESTRUCTIVE_TIGHTEN:
+    case ApprovalPolicySource.AUTO_APPROVE_ALL:
+    case ApprovalPolicySource.APPROVAL_LEASE:
+      return true;
+    case ApprovalPolicySource.CLASSIFIER_DEFAULT:
+    case ApprovalPolicySource.BUILTIN_CATEGORY:
+    case ApprovalPolicySource.UNSPECIFIED:
+    default:
+      return false;
+  }
+}

package/src/execution/execution-phases.ts

@@ -0,0 +1,23 @@
+// Framework-agnostic execution-phase predicates.
+//
+// Lives in @stigmer/sdk (the pure layer) so it is shared by @stigmer/react and
+// @stigmer/ink and usable by pure logic here (e.g. the file-review fold's corpus
+// parity test reproduces the server's terminal-phase gate). @stigmer/react
+// re-exports it so its public API is unchanged.
+
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+const TERMINAL_PHASES: ReadonlySet<ExecutionPhase> = new Set([
+  ExecutionPhase.EXECUTION_COMPLETED,
+  ExecutionPhase.EXECUTION_FAILED,
+  ExecutionPhase.EXECUTION_CANCELLED,
+  ExecutionPhase.EXECUTION_TERMINATED,
+]);
+
+/**
+ * Returns `true` when the given phase represents a final, immutable
+ * execution state — no further updates will arrive from the server.
+ */
+export function isTerminalPhase(phase: ExecutionPhase): boolean {
+  return TERMINAL_PHASES.has(phase);
+}