@stigmer/sdk 2.0.0 → 3.0.0

package/src/__tests__/runner-adapter.test.ts

@@ -0,0 +1,122 @@
+import { describe, it, expect, vi } from "vitest";
+import {
+  createRunnerAdapter,
+  type RunnerWorkerHost,
+} from "../runner-adapter";
+
+function createMockHost(): RunnerWorkerHost & {
+  addSession: ReturnType<typeof vi.fn>;
+  removeSession: ReturnType<typeof vi.fn>;
+  addWorkflowExecution: ReturnType<typeof vi.fn>;
+  removeWorkflowExecution: ReturnType<typeof vi.fn>;
+} {
+  return {
+    addSession: vi.fn().mockResolvedValue(undefined),
+    removeSession: vi.fn().mockResolvedValue(undefined),
+    addWorkflowExecution: vi.fn().mockResolvedValue(undefined),
+    removeWorkflowExecution: vi.fn().mockResolvedValue(undefined),
+  };
+}
+
+describe("createRunnerAdapter", () => {
+  it("returns an adapter with all four lifecycle methods", () => {
+    const adapter = createRunnerAdapter(createMockHost());
+
+    expect(adapter.onSessionOpened).toBeInstanceOf(Function);
+    expect(adapter.onSessionClosed).toBeInstanceOf(Function);
+    expect(adapter.onWorkflowExecutionCreated).toBeInstanceOf(Function);
+    expect(adapter.onWorkflowExecutionTerminated).toBeInstanceOf(Function);
+  });
+
+  it("maps onSessionOpened to host.addSession with the session id", async () => {
+    const host = createMockHost();
+    const adapter = createRunnerAdapter(host);
+
+    await adapter.onSessionOpened("ses-123");
+
+    expect(host.addSession).toHaveBeenCalledTimes(1);
+    expect(host.addSession).toHaveBeenCalledWith("ses-123");
+    // The asymmetric mapping is the footgun this factory exists to prevent:
+    // closing/removing must not fire on open.
+    expect(host.removeSession).not.toHaveBeenCalled();
+  });
+
+  it("maps onSessionClosed to host.removeSession with the session id", async () => {
+    const host = createMockHost();
+    const adapter = createRunnerAdapter(host);
+
+    await adapter.onSessionClosed("ses-123");
+
+    expect(host.removeSession).toHaveBeenCalledTimes(1);
+    expect(host.removeSession).toHaveBeenCalledWith("ses-123");
+    expect(host.addSession).not.toHaveBeenCalled();
+  });
+
+  it("maps onWorkflowExecutionCreated to host.addWorkflowExecution with the execution id", async () => {
+    const host = createMockHost();
+    const adapter = createRunnerAdapter(host);
+
+    await adapter.onWorkflowExecutionCreated("wfexec-456");
+
+    expect(host.addWorkflowExecution).toHaveBeenCalledTimes(1);
+    expect(host.addWorkflowExecution).toHaveBeenCalledWith("wfexec-456");
+    expect(host.removeWorkflowExecution).not.toHaveBeenCalled();
+  });
+
+  it("maps onWorkflowExecutionTerminated to host.removeWorkflowExecution with the execution id", async () => {
+    const host = createMockHost();
+    const adapter = createRunnerAdapter(host);
+
+    await adapter.onWorkflowExecutionTerminated("wfexec-456");
+
+    expect(host.removeWorkflowExecution).toHaveBeenCalledTimes(1);
+    expect(host.removeWorkflowExecution).toHaveBeenCalledWith("wfexec-456");
+    expect(host.addWorkflowExecution).not.toHaveBeenCalled();
+  });
+
+  it("resolves to undefined regardless of the host's return value", async () => {
+    // The host's add methods return a task queue string; the adapter contract
+    // is Promise<void>, so the value must be swallowed.
+    const host = createMockHost();
+    host.addSession.mockResolvedValue("session:ses-123");
+    host.addWorkflowExecution.mockResolvedValue("wfexec:wfexec-456");
+    const adapter = createRunnerAdapter(host);
+
+    await expect(adapter.onSessionOpened("ses-123")).resolves.toBeUndefined();
+    await expect(
+      adapter.onWorkflowExecutionCreated("wfexec-456"),
+    ).resolves.toBeUndefined();
+  });
+
+  it("awaits the host: it does not resolve before the host settles", async () => {
+    let release!: () => void;
+    const gate = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const host = createMockHost();
+    host.addSession.mockReturnValue(gate);
+    const adapter = createRunnerAdapter(host);
+
+    let settled = false;
+    const pending = adapter.onSessionOpened("ses-123").then(() => {
+      settled = true;
+    });
+
+    await Promise.resolve();
+    expect(settled).toBe(false);
+
+    release();
+    await pending;
+    expect(settled).toBe(true);
+  });
+
+  it("propagates a host rejection", async () => {
+    const host = createMockHost();
+    host.removeSession.mockRejectedValue(new Error("worker teardown failed"));
+    const adapter = createRunnerAdapter(host);
+
+    await expect(adapter.onSessionClosed("ses-123")).rejects.toThrow(
+      "worker teardown failed",
+    );
+  });
+});

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

@@ -0,0 +1,144 @@
+// Validates the tool-view layer against the shared cross-language contract in
+// test/fixtures/tool-view/. The Go CLI runs the same fixtures, so the two
+// surfaces cannot drift in classification or result interpretation.
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+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 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { ToolKind, resolveToolKindByName, normalizeToolResult } from "../tool-view";
+
+const here = dirname(fileURLToPath(import.meta.url));
+// sdk/typescript/src/execution/__tests__ -> repo root is five levels up.
+const fixtureDir = resolve(here, "../../../../../test/fixtures/tool-view");
+
+function loadFixture<T>(name: string): T {
+  return JSON.parse(readFileSync(resolve(fixtureDir, name), "utf8")) as T;
+}
+
+describe("classification fixtures", () => {
+  const { cases } = loadFixture<{
+    cases: { name: string; mcpServerSlug: string; toolKind: string }[];
+  }>("classification.json");
+
+  it("loads the fixture", () => {
+    expect(cases.length).toBeGreaterThan(0);
+  });
+
+  for (const c of cases) {
+    const expected = ToolKind[c.toolKind.replace(/^TOOL_KIND_/, "") as keyof typeof ToolKind];
+    it(`classifies ${c.name || "(empty)"}${c.mcpServerSlug ? ` @${c.mcpServerSlug}` : ""}`, () => {
+      expect(resolveToolKindByName(c.name, c.mcpServerSlug)).toBe(expected);
+    });
+  }
+});
+
+describe("result-view fixtures", () => {
+  interface ResultCase {
+    name: string;
+    toolName: string;
+    mcpServerSlug: string;
+    args: Record<string, unknown>;
+    result: string;
+    error?: string;
+    status?: string;
+    expected: {
+      type: string;
+      path?: string;
+      exitCode?: number;
+      count?: number;
+      mcpServerSlug?: string;
+      linesAdded?: number;
+      linesRemoved?: number;
+    };
+  }
+
+  const { cases } = loadFixture<{ cases: ResultCase[] }>("result-views.json");
+
+  it("loads the fixture", () => {
+    expect(cases.length).toBeGreaterThan(0);
+  });
+
+  for (const c of cases) {
+    it(`normalizes ${c.name} -> ${c.expected.type}`, () => {
+      const status =
+        c.status === "TOOL_CALL_FAILED"
+          ? ToolCallStatus.TOOL_CALL_FAILED
+          : ToolCallStatus.TOOL_CALL_COMPLETED;
+
+      const toolCall = create(ToolCallSchema, {
+        id: c.name,
+        name: c.toolName,
+        mcpServerSlug: c.mcpServerSlug,
+        result: c.result,
+        error: c.error ?? "",
+        status,
+        args: c.args as JsonObject,
+      });
+
+      const view = normalizeToolResult(toolCall);
+      expect(view.type).toBe(c.expected.type);
+
+      // Only deterministic facts are part of the shared contract.
+      if (c.expected.path !== undefined && view.type === "diff") {
+        expect(view.path).toBe(c.expected.path);
+      }
+      if (c.expected.path !== undefined && view.type === "file") {
+        expect(view.path).toBe(c.expected.path);
+      }
+      if (c.expected.exitCode !== undefined && view.type === "terminal") {
+        expect(view.exitCode).toBe(c.expected.exitCode);
+      }
+      if (c.expected.count !== undefined && view.type === "search") {
+        expect(view.count).toBe(c.expected.count);
+      }
+      if (c.expected.count !== undefined && view.type === "list") {
+        expect(view.count).toBe(c.expected.count);
+      }
+      if (c.expected.mcpServerSlug !== undefined && view.type === "contentBlocks") {
+        expect(view.mcpServerSlug).toBe(c.expected.mcpServerSlug);
+      }
+      if (c.expected.linesAdded !== undefined && view.type === "diff") {
+        expect(view.linesAdded).toBe(c.expected.linesAdded);
+      }
+      if (c.expected.linesRemoved !== undefined && view.type === "diff") {
+        expect(view.linesRemoved).toBe(c.expected.linesRemoved);
+      }
+    });
+  }
+});
+
+describe("resolveToolKind wire field precedence", () => {
+  it("prefers the wire tool_kind over the name fallback", () => {
+    const toolCall = create(ToolCallSchema, {
+      name: "some_unknown_name",
+      toolKind: ToolKind.SHELL,
+    });
+    // resolveToolKind is exercised indirectly via normalizeToolResult routing.
+    const view = normalizeToolResult(
+      create(ToolCallSchema, {
+        name: "some_unknown_name",
+        toolKind: ToolKind.SHELL,
+        result: "done\n[Command succeeded]",
+        status: ToolCallStatus.TOOL_CALL_COMPLETED,
+      }),
+    );
+    expect(view.type).toBe("terminal");
+    expect(toolCall.toolKind).toBe(ToolKind.SHELL);
+  });
+
+  it("degrades unknown results to json or text", () => {
+    const jsonView = normalizeToolResult(
+      create(ToolCallSchema, { name: "mystery", result: '{"a":1}', status: ToolCallStatus.TOOL_CALL_COMPLETED }),
+    );
+    expect(jsonView.type).toBe("json");
+
+    const textView = normalizeToolResult(
+      create(ToolCallSchema, { name: "mystery", result: "plain", status: ToolCallStatus.TOOL_CALL_COMPLETED }),
+    );
+    expect(textView.type).toBe("text");
+  });
+});

package/src/execution/tool-view.ts

@@ -0,0 +1,418 @@
+// Framework-agnostic tool-call view model for every Stigmer surface.
+//
+// Two pure functions normalize the two things clients keep re-deriving from
+// harness-specific data:
+//   - resolveToolKind: the harness-agnostic ToolKind (wire field, with a
+//     name-based fallback for legacy executions persisted before tool_kind).
+//   - normalizeToolResult: the opaque result string -> a typed ToolResultView
+//     that presentation layers (React, Ink, the Go CLI's equivalent) render
+//     without re-parsing third-party engine formats.
+//
+// This module has no React or framework dependency so it can be shared by
+// @stigmer/react and @stigmer/ink. The Go CLI mirrors it; the shared contract
+// is test/fixtures/tool-view/. Engine result formats are version-fragile, so
+// every assumption here is fixture-backed and degrades gracefully to json/text.
+
+import { ToolKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+
+export { ToolKind };
+
+/** A single match in a search/grep result. */
+export interface ToolSearchMatch {
+  /** File path the match was found in, when the result format provides it. */
+  readonly file?: string;
+  /** 1-based line number, when available. */
+  readonly line?: number;
+  /** The matched text. */
+  readonly text: string;
+}
+
+/** An MCP content block (the `content: [...]` array MCP servers return). */
+export interface ToolContentBlock {
+  /** Block type, e.g. "text". */
+  readonly type: string;
+  /** Text payload, when the block is textual. */
+  readonly text?: string;
+}
+
+/**
+ * A typed projection of a tool call's result, discriminated by `type`.
+ *
+ * Presentation layers switch on `type` and never re-parse the raw string. The
+ * `json` and `text` variants are the guaranteed graceful-degradation fallbacks:
+ * any unrecognized or truncated payload lands there, so this is never worse than
+ * showing the raw result.
+ */
+export type ToolResultView =
+  // File edit. Computed from args (old/new text) because the native engine's
+  // result carries no diff. linesAdded/linesRemoved/unifiedDiff are populated
+  // only when the source provides them (e.g. the Cursor SDK envelope); otherwise
+  // the presentation layer computes the visual diff from oldText/newText.
+  | {
+      readonly type: "diff";
+      readonly path: string;
+      readonly oldText?: string;
+      readonly newText?: string;
+      readonly linesAdded?: number;
+      readonly linesRemoved?: number;
+      readonly unifiedDiff?: string;
+    }
+  // File read or full-file write. `content` is the file body (from result for
+  // read, from args for write).
+  | {
+      readonly type: "file";
+      readonly path: string;
+      readonly content: string;
+      readonly language?: string;
+      readonly truncated: boolean;
+    }
+  // Shell command output. exitCode is parsed from the engine marker when present.
+  | {
+      readonly type: "terminal";
+      readonly stdout: string;
+      readonly stderr: string;
+      readonly exitCode?: number;
+    }
+  | { readonly type: "search"; readonly matches: readonly ToolSearchMatch[]; readonly count: number }
+  | { readonly type: "list"; readonly entries: readonly string[]; readonly count: number }
+  | {
+      readonly type: "contentBlocks";
+      readonly blocks: readonly ToolContentBlock[];
+      readonly mcpServerSlug: string;
+    }
+  | { readonly type: "text"; readonly text: string }
+  | { readonly type: "json"; readonly value: unknown }
+  | { readonly type: "error"; readonly message: string }
+  // Nothing to render (e.g. a delete confirmation, or a result not yet produced).
+  | { readonly type: "empty" };
+
+// ---------------------------------------------------------------------------
+// Identity: resolveToolKind
+// ---------------------------------------------------------------------------
+
+// Fallback name -> ToolKind map for legacy executions (tool_kind == UNSPECIFIED)
+// and any consumer that only has a name. Mirrors the runner classifier and the
+// Go CLI; kept honest by test/fixtures/tool-view/classification.json.
+const NAME_TO_KIND: ReadonlyMap<string, ToolKind> = 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],
+]);
+
+/**
+ * Resolves the harness-agnostic kind of a tool call.
+ *
+ * Prefers the wire `tool_kind` set by the runner; falls back to a name lookup
+ * for legacy executions where it is UNSPECIFIED. An unknown name with a
+ * non-empty mcpServerSlug is an MCP tool.
+ */
+export function resolveToolKind(toolCall: Pick<ToolCall, "name" | "mcpServerSlug" | "toolKind">): ToolKind {
+  if (toolCall.toolKind !== undefined && toolCall.toolKind !== ToolKind.UNSPECIFIED) {
+    return toolCall.toolKind;
+  }
+  return resolveToolKindByName(toolCall.name, toolCall.mcpServerSlug);
+}
+
+/** Name-based classification used as the legacy fallback for resolveToolKind. */
+export function resolveToolKindByName(name: string, mcpServerSlug?: string): ToolKind {
+  const builtin = NAME_TO_KIND.get(name);
+  if (builtin !== undefined) {
+    return builtin;
+  }
+  if (mcpServerSlug && mcpServerSlug.length > 0) {
+    return ToolKind.MCP;
+  }
+  return ToolKind.UNSPECIFIED;
+}
+
+// ---------------------------------------------------------------------------
+// Result: normalizeToolResult
+// ---------------------------------------------------------------------------
+
+type Args = Record<string, unknown> | undefined;
+
+const PATH_FIELDS = ["path", "file_path", "file", "filename"] as const;
+const OLD_TEXT_FIELDS = ["old_string", "old_text", "oldText"] as const;
+const NEW_TEXT_FIELDS = ["new_string", "new_text", "newText", "replacement"] as const;
+const WRITE_CONTENT_FIELDS = ["contents", "content", "file_content"] as const;
+
+/**
+ * Normalizes a tool call into a typed ToolResultView for rendering.
+ *
+ * A FAILED tool with an error always yields an `error` view. Otherwise the kind
+ * drives interpretation, and anything unrecognized degrades to `json`/`text`.
+ */
+export function normalizeToolResult(toolCall: ToolCall): ToolResultView {
+  const result = toolCall.result ?? "";
+  const args = toolCall.args as Args;
+
+  if (toolCall.status === ToolCallStatus.TOOL_CALL_FAILED && (toolCall.error || result)) {
+    return { type: "error", message: toolCall.error || result };
+  }
+
+  const kind = resolveToolKind(toolCall);
+
+  switch (kind) {
+    case ToolKind.FILE_EDIT:
+      return normalizeEdit(args, result);
+    case ToolKind.FILE_WRITE:
+      return normalizeWrite(args);
+    case ToolKind.FILE_READ:
+      return normalizeRead(args, result);
+    case ToolKind.FILE_DELETE:
+      return result ? { type: "text", text: result } : { type: "empty" };
+    case ToolKind.SHELL:
+      return normalizeShell(result);
+    case ToolKind.SEARCH:
+      return normalizeSearch(result);
+    case ToolKind.LIST:
+      return normalizeList(result);
+    case ToolKind.THINK:
+      return normalizeThink(args, result);
+    case ToolKind.MCP:
+      return normalizeMcp(result, toolCall.mcpServerSlug);
+    default:
+      return genericView(result);
+  }
+}
+
+function normalizeEdit(args: Args, result: string): ToolResultView {
+  const path = firstString(args, PATH_FIELDS) ?? "";
+  const oldText = firstString(args, OLD_TEXT_FIELDS);
+  const newText = firstString(args, NEW_TEXT_FIELDS);
+
+  // The Cursor SDK returns a stringified envelope with precomputed diff stats;
+  // prefer those when present. The native engine returns prose with no diff, so
+  // the presentation layer computes the visual diff from oldText/newText.
+  const envelope = tryParseJson(result);
+  const value = isRecord(envelope) && isRecord(envelope.value) ? envelope.value : undefined;
+  const linesAdded = value ? asNumber(value.linesAdded) : undefined;
+  const linesRemoved = value ? asNumber(value.linesRemoved) : undefined;
+  const unifiedDiff = value ? asString(value.diffString) : undefined;
+
+  return {
+    type: "diff",
+    path,
+    oldText,
+    newText,
+    linesAdded,
+    linesRemoved,
+    unifiedDiff,
+  };
+}
+
+function normalizeWrite(args: Args): ToolResultView {
+  const path = firstString(args, PATH_FIELDS) ?? "";
+  const content = firstString(args, WRITE_CONTENT_FIELDS) ?? "";
+  return { type: "file", path, content, language: languageFromPath(path), truncated: false };
+}
+
+function normalizeRead(args: Args, result: string): ToolResultView {
+  const path = firstString(args, PATH_FIELDS) ?? "";
+  return {
+    type: "file",
+    path,
+    content: result,
+    language: languageFromPath(path),
+    truncated: isTruncated(result),
+  };
+}
+
+// Matches the deepagents shell marker, e.g. "[Command failed with exit code 2]"
+// or "[Command succeeded]". Format owned by the engine — see DD-003; covered by
+// test/fixtures/tool-view/result-views.json so a format change fails one test.
+const SHELL_EXIT_MARKER = /\n?\[Command (?:succeeded|failed with exit code (\d+))\]\s*$/;
+
+function normalizeShell(result: string): ToolResultView {
+  // Cursor sub-agent steps can carry a structured {stdout,stderr,exitCode}.
+  const parsed = tryParseJson(result);
+  if (isRecord(parsed) && ("stdout" in parsed || "exitCode" in parsed)) {
+    return {
+      type: "terminal",
+      stdout: asString(parsed.stdout) ?? "",
+      stderr: asString(parsed.stderr) ?? "",
+      exitCode: asNumber(parsed.exitCode),
+    };
+  }
+
+  const marker = result.match(SHELL_EXIT_MARKER);
+  if (marker) {
+    const stdout = result.replace(SHELL_EXIT_MARKER, "");
+    // Group 1 is set only on failure; a matched marker without it is success (0).
+    const exitCode = marker[1] !== undefined ? Number(marker[1]) : 0;
+    return { type: "terminal", stdout, stderr: "", exitCode };
+  }
+
+  return { type: "terminal", stdout: result, stderr: "" };
+}
+
+// A grep-style match line, e.g. "  12: // TODO: fix".
+const GREP_MATCH_LINE = /^\s*\d+[:\t]/;
+
+function normalizeSearch(result: string): ToolResultView {
+  const lines = nonEmptyLines(result);
+  const matchLines = lines.filter((l) => GREP_MATCH_LINE.test(l));
+
+  if (matchLines.length > 0) {
+    const matches = matchLines.map((l) => ({ text: l.trim() }));
+    return { type: "search", matches, count: matches.length };
+  }
+
+  // Path/name results (glob, semantic search): each meaningful line is a match.
+  const entries = lines.filter((l) => !/^no (files|matches|results)/i.test(l));
+  const matches = entries.map((text) => ({ text }));
+  return { type: "search", matches, count: matches.length };
+}
+
+function normalizeList(result: string): ToolResultView {
+  const entries = nonEmptyLines(result);
+  return { type: "list", entries, count: entries.length };
+}
+
+function normalizeThink(args: Args, result: string): ToolResultView {
+  const thought = firstString(args, ["thought"]) ?? result;
+  return { type: "text", text: thought };
+}
+
+function normalizeMcp(result: string, mcpServerSlug: string): ToolResultView {
+  const parsed = tryParseJson(result);
+  const blocks = extractContentBlocks(parsed);
+  if (blocks) {
+    return { type: "contentBlocks", blocks, mcpServerSlug };
+  }
+  if (parsed !== undefined && (isRecord(parsed) || Array.isArray(parsed))) {
+    return { type: "json", value: parsed };
+  }
+  return result ? { type: "text", text: result } : { type: "empty" };
+}
+
+function genericView(result: string): ToolResultView {
+  if (!result) {
+    return { type: "empty" };
+  }
+  const parsed = tryParseJson(result);
+  if (parsed !== undefined && (isRecord(parsed) || Array.isArray(parsed))) {
+    return { type: "json", value: parsed };
+  }
+  return { type: "text", text: result };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function firstString(args: Args, fields: readonly string[]): string | undefined {
+  if (!args) return undefined;
+  for (const f of fields) {
+    const v = args[f];
+    if (typeof v === "string" && v.length > 0) return v;
+  }
+  return undefined;
+}
+
+function nonEmptyLines(s: string): string[] {
+  return s.split("\n").map((l) => l.replace(/\s+$/, "")).filter((l) => l.trim().length > 0);
+}
+
+function tryParseJson(s: string): unknown {
+  const trimmed = s.trim();
+  if (!trimmed || (trimmed[0] !== "{" && trimmed[0] !== "[")) return undefined;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return undefined;
+  }
+}
+
+function extractContentBlocks(parsed: unknown): ToolContentBlock[] | null {
+  const content = isRecord(parsed) ? parsed.content : Array.isArray(parsed) ? parsed : undefined;
+  if (!Array.isArray(content)) return null;
+  const blocks: ToolContentBlock[] = [];
+  for (const item of content) {
+    if (isRecord(item) && typeof item.type === "string") {
+      blocks.push({ type: item.type, text: asString(item.text) });
+    }
+  }
+  return blocks.length > 0 ? blocks : null;
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function asString(v: unknown): string | undefined {
+  return typeof v === "string" ? v : undefined;
+}
+
+function asNumber(v: unknown): number | undefined {
+  return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+
+function isTruncated(result: string): boolean {
+  return /\[truncated: \d+ chars total\]/.test(result);
+}
+
+const EXTENSION_TO_LANGUAGE: ReadonlyMap<string, string> = new Map([
+  ["ts", "typescript"], ["tsx", "tsx"], ["js", "javascript"], ["jsx", "jsx"],
+  ["py", "python"], ["go", "go"], ["rs", "rust"], ["java", "java"],
+  ["rb", "ruby"], ["sh", "bash"], ["md", "markdown"], ["json", "json"],
+  ["yaml", "yaml"], ["yml", "yaml"], ["proto", "protobuf"], ["sql", "sql"],
+  ["css", "css"], ["html", "html"], ["toml", "toml"],
+]);
+
+function languageFromPath(path: string): string | undefined {
+  const dot = path.lastIndexOf(".");
+  if (dot < 0) return undefined;
+  return EXTENSION_TO_LANGUAGE.get(path.slice(dot + 1).toLowerCase());
+}