@stigmer/runner 3.15.3-dev.20260914121148 → 3.16.0

package/src/activities/execute-deep-agent/__tests__/v3-protocol-normalizer.test.ts

@@ -1,324 +0,0 @@
-import { describe, it, expect, beforeEach } from "vitest";
-import { normalize } from "../v3-protocol-normalizer.js";
-import {
-  resetSeq,
-  makeProtocolEvent,
-  makeMessageStart,
-  makeMessageFinish,
-  makeTextDelta,
-  makeReasoningDelta,
-  makeToolCallArgDelta,
-  makeToolStarted,
-  makeToolFinished,
-  makeToolError,
-  makeToolOutputDelta,
-  makeUsageEvent,
-  makeProviderEvent,
-  makeLifecycleRunning,
-  makeLifecycleCompleted,
-  makeContentBlockStartText,
-  makeContentBlockFinish,
-  makeCheckpointEvent,
-  makeTasksEvent,
-  makeValuesEvent,
-  makeUpdatesEvent,
-} from "../__test-utils__/v3-event-fixtures.js";
-
-beforeEach(() => resetSeq());
-
-describe("V3ProtocolNormalizer", () => {
-
-  // ── Message channel ──────────────────────────────────────────────
-
-  describe("messages channel", () => {
-    it("normalizes message-start", () => {
-      const result = normalize(makeMessageStart("run-1", { messageId: "msg_abc" }));
-      expect(result).toHaveLength(1);
-      expect(result[0]).toMatchObject({
-        kind: "message_start",
-        runId: "run-1",
-        messageId: "msg_abc",
-        namespace: "",
-      });
-    });
-
-    it("normalizes text-delta", () => {
-      const result = normalize(makeTextDelta("run-1", "Hello "));
-      expect(result).toHaveLength(1);
-      expect(result[0]).toMatchObject({
-        kind: "text_delta",
-        runId: "run-1",
-        text: "Hello ",
-      });
-    });
-
-    it("normalizes reasoning-delta", () => {
-      const result = normalize(makeReasoningDelta("run-1", "Let me think..."));
-      expect(result).toHaveLength(1);
-      expect(result[0]).toMatchObject({
-        kind: "reasoning_delta",
-        runId: "run-1",
-        text: "Let me think...",
-      });
-    });
-
-    it("normalizes tool_call_chunk via block-delta", () => {
-      const result = normalize(makeToolCallArgDelta("run-1", "toolu_123", '{"path":'));
-      expect(result).toHaveLength(1);
-      expect(result[0]).toMatchObject({
-        kind: "tool_call_arg_delta",
-        callId: "toolu_123",
-        argsChunk: '{"path":',
-      });
-    });
-
-    it("normalizes message-finish with usage", () => {
-      const result = normalize(makeMessageFinish("run-1", {
-        reason: "end_turn",
-        usage: { input_tokens: 100, output_tokens: 20, total_tokens: 120 },
-      }));
-      expect(result).toHaveLength(1);
-      expect(result[0]).toMatchObject({
-        kind: "message_finish",
-        runId: "run-1",
-        reason: "end_turn",
-        usage: {
-          input_tokens: 100,
-          output_tokens: 20,
-        },
-      });
-    });
-
-    it("normalizes message-finish without usage", () => {
-      const result = normalize(makeMessageFinish("run-1"));
-      expect(result).toHaveLength(1);
-      expect(result[0]).toMatchObject({
-        kind: "message_finish",
-        runId: "run-1",
-        usage: undefined,
-      });
-    });
-
-    it("normalizes usage event", () => {
-      const result = normalize(makeUsageEvent("run-1", {
-        input_tokens: 50, output_tokens: 10,
-        input_token_details: { cache_creation: 40, cache_read: 5 },
-      }));
-      expect(result).toHaveLength(1);
-      expect(result[0]).toMatchObject({
-        kind: "usage",
-        usage: {
-          input_tokens: 50,
-          output_tokens: 10,
-          input_token_details: { cache_creation: 40, cache_read: 5 },
-        },
-      });
-    });
-
-    it("normalizes provider event with model", () => {
-      const result = normalize(makeProviderEvent("run-1", "anthropic", "claude-sonnet-4-6"));
-      expect(result).toHaveLength(1);
-      expect(result[0]).toMatchObject({
-        kind: "provider",
-        provider: "anthropic",
-        model: "claude-sonnet-4-6",
-      });
-    });
-
-    it("returns empty for content-block-start", () => {
-      const result = normalize(makeContentBlockStartText("run-1"));
-      expect(result).toHaveLength(0);
-    });
-
-    it("returns empty for content-block-finish", () => {
-      const result = normalize(makeContentBlockFinish("run-1"));
-      expect(result).toHaveLength(0);
-    });
-
-    it("ignores empty text-delta", () => {
-      const result = normalize(makeTextDelta("run-1", ""));
-      expect(result).toHaveLength(0);
-    });
-
-    it("ignores empty reasoning-delta", () => {
-      const result = normalize(makeReasoningDelta("run-1", ""));
-      expect(result).toHaveLength(0);
-    });
-  });
-
-  // ── Tools channel ────────────────────────────────────────────────
-
-  describe("tools channel", () => {
-    it("normalizes tool-started with snake_case fields", () => {
-      const result = normalize(makeToolStarted("toolu_abc", "read_file", '{"path":"/src/main.ts"}'));
-      expect(result).toHaveLength(1);
-      expect(result[0]).toMatchObject({
-        kind: "tool_started",
-        callId: "toolu_abc",
-        name: "read_file",
-        input: { path: "/src/main.ts" },
-      });
-    });
-
-    it("normalizes tool-started with camelCase fields", () => {
-      const event = makeProtocolEvent("tools", {
-        event: "tool-started",
-        toolCallId: "toolu_abc",
-        toolName: "read_file",
-        input: { path: "/src/main.ts" },
-      }, { namespace: ["tools:toolu_abc"] });
-      const result = normalize(event);
-      expect(result).toHaveLength(1);
-      expect(result[0]).toMatchObject({
-        kind: "tool_started",
-        callId: "toolu_abc",
-        name: "read_file",
-      });
-    });
-
-    it("normalizes tool-finished", () => {
-      const result = normalize(makeToolFinished("toolu_abc", "file content here"));
-      expect(result).toHaveLength(1);
-      expect(result[0]).toMatchObject({
-        kind: "tool_finished",
-        callId: "toolu_abc",
-      });
-    });
-
-    it("normalizes tool-error", () => {
-      const result = normalize(makeToolError("toolu_abc", "permission denied"));
-      expect(result).toHaveLength(1);
-      expect(result[0]).toMatchObject({
-        kind: "tool_error",
-        callId: "toolu_abc",
-        message: "permission denied",
-      });
-    });
-
-    it("normalizes tool-output-delta", () => {
-      const result = normalize(makeToolOutputDelta("toolu_abc", "partial output"));
-      expect(result).toHaveLength(1);
-      expect(result[0]).toMatchObject({
-        kind: "tool_output_delta",
-        callId: "toolu_abc",
-        delta: "partial output",
-      });
-    });
-
-    it("parses string JSON input into object", () => {
-      const result = normalize(makeToolStarted("toolu_abc", "think", '{"thought":"test"}'));
-      expect(result[0]).toMatchObject({
-        kind: "tool_started",
-        input: { thought: "test" },
-      });
-    });
-
-    it("handles malformed JSON input gracefully", () => {
-      const result = normalize(makeToolStarted("toolu_abc", "think", "not json"));
-      expect(result[0]).toMatchObject({
-        kind: "tool_started",
-        input: {},
-      });
-    });
-  });
-
-  // ── Lifecycle channel ────────────────────────────────────────────
-
-  describe("lifecycle channel", () => {
-    it("normalizes running event", () => {
-      const result = normalize(makeLifecycleRunning("root"));
-      expect(result).toHaveLength(1);
-      expect(result[0]).toMatchObject({
-        kind: "lifecycle",
-        event: "running",
-        graphName: "root",
-      });
-    });
-
-    it("normalizes completed event", () => {
-      const result = normalize(makeLifecycleCompleted("model_request", ["model_request:abc"]));
-      expect(result).toHaveLength(1);
-      expect(result[0]).toMatchObject({
-        kind: "lifecycle",
-        event: "completed",
-        graphName: "model_request",
-        namespace: "model_request:abc",
-      });
-    });
-  });
-
-  // ── Ignored channels ─────────────────────────────────────────────
-
-  describe("ignored channels", () => {
-    it("returns empty for checkpoints", () => {
-      expect(normalize(makeCheckpointEvent())).toHaveLength(0);
-    });
-
-    it("returns empty for tasks", () => {
-      expect(normalize(makeTasksEvent())).toHaveLength(0);
-    });
-
-    it("returns empty for values", () => {
-      expect(normalize(makeValuesEvent())).toHaveLength(0);
-    });
-
-    it("returns empty for updates", () => {
-      expect(normalize(makeUpdatesEvent())).toHaveLength(0);
-    });
-  });
-
-  // ── Edge cases ───────────────────────────────────────────────────
-
-  describe("edge cases", () => {
-    it("returns empty for unknown method", () => {
-      const event = makeProtocolEvent("input", { event: "something" });
-      expect(normalize(event)).toHaveLength(0);
-    });
-
-    it("returns empty for missing data", () => {
-      const event = makeProtocolEvent("messages", undefined);
-      expect(normalize(event)).toHaveLength(0);
-    });
-
-    it("returns empty for unknown message event type", () => {
-      const event = makeProtocolEvent("messages", { event: "brand-new-thing", run_id: "r" });
-      expect(normalize(event)).toHaveLength(0);
-    });
-
-    it("preserves namespace from event params", () => {
-      const result = normalize(makeTextDelta("run-1", "hi", { namespace: ["subagent:worker-1"] }));
-      expect(result[0]).toMatchObject({ namespace: "subagent:worker-1" });
-    });
-
-    it("joins multi-segment namespace with pipe", () => {
-      const result = normalize(makeTextDelta("run-1", "hi", { namespace: ["a", "b"] }));
-      expect(result[0]).toMatchObject({ namespace: "a|b" });
-    });
-
-    it("preserves seq from original event", () => {
-      const event = makeTextDelta("run-1", "hi");
-      const result = normalize(event);
-      expect(result[0].seq).toBe(event.seq);
-    });
-
-    it("handles delta with no type gracefully", () => {
-      const event = makeProtocolEvent("messages", {
-        event: "content-block-delta",
-        index: 0,
-        delta: {},
-        run_id: "run-1",
-      });
-      expect(normalize(event)).toHaveLength(0);
-    });
-
-    it("handles missing tool_call_id in tool-started", () => {
-      const event = makeProtocolEvent("tools", {
-        event: "tool-started",
-        tool_name: "read_file",
-      }, { namespace: ["tools:abc"] });
-      const result = normalize(event);
-      expect(result).toHaveLength(1);
-      expect(result[0]).toMatchObject({ kind: "tool_started", callId: "" });
-    });
-  });
-});

package/src/activities/execute-deep-agent/execution-state.ts

@@ -1,78 +0,0 @@
-/**
- * Mutable execution state for `V3StatusBuilder`.
- *
- * Holds the AgentExecutionStatus proto being progressively built and
- * O(1) lookup indexes into its repeated fields. Mutations to indexed
- * references (ToolCall, AgentMessage) propagate directly to the proto
- * because they share the same object reference. Sub-agent transcripts are
- * `SubAgentTracker`'s, keyed by namespace beside this state.
- */
-
-import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
-import type { AgentMessage, ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
-
-export class ExecutionState {
-  /** The protobuf projection being built. */
-  readonly proto: AgentExecutionStatus;
-
-  /**
-   * tool_call_id -> live ToolCall reference inside a message's repeated
-   * field. Mutations propagate directly to the proto.
-   */
-  readonly toolCalls: Map<string, ToolCall> = new Map();
-
-  /**
-   * LLM run_id -> the AgentMessage that run is streaming into.
-   * Prevents token interleaving when the model produces multiple runs.
-   */
-  readonly messagesByRun: Map<string, AgentMessage> = new Map();
-
-  /**
-   * Namespace -> most recently created AI message in that execution
-   * context. Tool calls are appended to this message's toolCalls field.
-   * Empty string key represents the main agent.
-   */
-  readonly currentAiMessage: Map<string, AgentMessage> = new Map();
-
-  /**
-   * Namespace -> latest LLM run_id for turn-boundary detection.
-   * When a new run_id appears in the same namespace, a new AgentMessage
-   * is created rather than appending to the existing one.
-   */
-  readonly lastLlmRunId: Map<string, string> = new Map();
-
-  constructor(proto: AgentExecutionStatus) {
-    this.proto = proto;
-  }
-
-  /**
-   * Reset all ephemeral indexes. The proto itself is not cleared —
-   * this is used when resuming from a persisted status where the proto
-   * already has messages and tool calls, but runtime tracking state
-   * (run_id maps, timing) must start fresh.
-   */
-  resetEphemeralState(): void {
-    this.messagesByRun.clear();
-    this.currentAiMessage.clear();
-    this.lastLlmRunId.clear();
-  }
-
-  /**
-   * Rebuild the toolCalls index from the proto's messages.
-   *
-   * Used on the resume path where the V3StatusBuilder is initialized
-   * with a persisted AgentExecutionStatus that already contains
-   * messages and tool calls. Only proto-derivable indexes are rebuilt;
-   * ephemeral runtime state starts fresh.
-   */
-  rebuildToolCallIndex(): void {
-    this.toolCalls.clear();
-    for (const message of this.proto.messages) {
-      for (const tc of message.toolCalls) {
-        if (tc.id) {
-          this.toolCalls.set(tc.id, tc);
-        }
-      }
-    }
-  }
-}

package/src/activities/execute-deep-agent/status-builder-shared.ts

@@ -1,142 +0,0 @@
-/**
- * What the transcript builders share: the tool-result serialization and the
- * approval-provenance stamp that `V3StatusBuilder` (the root transcript) and
- * `SubAgentTracker` (the sub-agent transcripts) both perform at the moment
- * they classify a tool call, so the two never drift on either rule.
- *
- * Until S3 M2b this module also carried the v2 `StatusBuilder`'s share — the
- * `UsageAccumulator` that summed `streamingUsage` (the turn runtime's
- * accountant owns the field now, `harness/usage-accumulator.ts`) and the v2
- * `on_tool_end` result extractor — both retired with the v2 stream (Q-S3-1).
- */
-
-import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
-import {
-  POLICY_ENGINE_VERSION,
-  resolveApprovalProvenance,
-  toProtoPolicySource,
-  type MergedToolPolicy,
-} from "../../shared/approval-policy.js";
-import type { ToolApprovalCategory } from "../../shared/tool-kind.js";
-
-// ── Tool Result Extraction ─────────────────────────────────────────
-
-/**
- * Serialize a LangChain message `content` field into the canonical tool-result
- * string.
- *
- * Text-only content is a plain string and passes through unchanged. Multimodal
- * content (image, or mixed text+image — e.g. a computer-use screenshot) is an
- * array of content blocks; we serialize the blocks array ITSELF, not the
- * surrounding message envelope, so the result lands in the exact top-level-array
- * shape the persist-time offload (`detectImagePayload`/`contentBlocks` in
- * status-offload.ts) consumes to lift the image out into a renderable
- * `ToolCallOutputRef`. Serializing the envelope instead would bury the base64
- * one level deeper and defeat that detection.
- *
- * Returns undefined when `content` is neither a string nor an array, letting the
- * caller fall back to serializing whatever else it holds.
- */
-function serializeToolContent(content: unknown): string | undefined {
-  if (typeof content === "string") return content;
-  if (Array.isArray(content)) return JSON.stringify(content);
-  return undefined;
-}
-
-/**
- * Extract tool result from v3 tool-finished output.
- * v3 output wraps LangChain ToolMessage in a constructor envelope:
- * `{ lc, type, id, kwargs: { content, status, ... } }`
- */
-export function extractToolResultV3(output: unknown): string {
-  if (typeof output === "string") return output;
-  if (typeof output === "object" && output !== null) {
-    const obj = output as Record<string, unknown>;
-    const kwargs = obj.kwargs as Record<string, unknown> | undefined;
-    if (kwargs) {
-      const fromKwargs = serializeToolContent(kwargs.content);
-      if (fromKwargs !== undefined) return fromKwargs;
-    }
-    const fromContent = serializeToolContent(obj.content);
-    if (fromContent !== undefined) return fromContent;
-  }
-  try {
-    return JSON.stringify(output);
-  } catch {
-    return "[serialization error]";
-  }
-}
-
-// ── Authorization Provenance ───────────────────────────────────────
-
-/**
- * The policy inputs the builders need to decide whether a tool call waits for
- * approval and to attribute its authorization provenance.
- */
-export interface ApprovalProvenanceInputs {
-  readonly policies: ReadonlyMap<string, MergedToolPolicy>;
-  readonly toolServerMap: ReadonlyMap<string, string>;
-  /**
-   * Built-in categories with a run-lifetime lease, so a leased built-in is
-   * attributed to its lease (approval_lease) rather than the plain category gate.
-   * Optional (mirroring {@link ApprovalGateConfig.leasedCategories}); absent =
-   * no lease active.
-   */
-  readonly leasedCategories?: ReadonlySet<ToolApprovalCategory>;
-  /** Pre-armed spec.auto_approve_all — the one whole-run global bypass. */
-  readonly globalBypass: boolean;
-  /**
-   * Unattended approval mode (ExecutionConfig.approval_mode = UNATTENDED):
-   * the gate auto-skips gated calls instead of interrupting, so the builders
-   * must NOT seed WAITING_APPROVAL rows or flip the phase to
-   * WAITING_FOR_APPROVAL — the row streams as RUNNING and the post-stream
-   * `reconcileUnattendedSkips` stamps the terminal SKIPPED + provenance.
-   */
-  readonly unattended?: boolean;
-}
-
-/**
- * The name the builder's API uses for the same shape (`setApprovalProvider`):
- * the adapter hands the gate's policy state in under this name. One shape, two
- * names on purpose — the provider is what a caller SUPPLIES, the inputs are
- * what the stamper READS; until S3 M2b the v2 builder declared the provider as
- * an empty `interface extends`, a second type for one shape.
- */
-export type ApprovalPolicyProvider = ApprovalProvenanceInputs;
-
-/** Shared empty set so a provider without leases allocates nothing per call. */
-const NO_LEASED_CATEGORIES: ReadonlySet<ToolApprovalCategory> = new Set();
-
-/**
- * Stamp a tool call's authorization provenance — which policy layer governs it —
- * alongside `tool_kind`, in exactly the spot both builders classify the tool.
- *
- * This is the read-side companion to the gate: it records WHY a tool is gated or
- * auto-approved for every observed tool call, so the persisted record is
- * auditable and the UI can explain the gate. Built-ins that no layer governs (a
- * read-only built-in) and the no-provider path both leave the field at
- * UNSPECIFIED, like an unclassified tool_kind.
- */
-export function stampApprovalProvenance(
-  tc: ToolCall,
-  provider: ApprovalProvenanceInputs | null,
-): void {
-  if (!provider) return;
-  const serverSlug = tc.mcpServerSlug || provider.toolServerMap.get(tc.name) || "";
-  const source = resolveApprovalProvenance(
-    tc.name,
-    serverSlug,
-    provider.policies,
-    provider.leasedCategories ?? NO_LEASED_CATEGORIES,
-    provider.globalBypass,
-  );
-  tc.approvalPolicySource = toProtoPolicySource(source);
-  if (source) tc.policyEngineVersion = POLICY_ENGINE_VERSION;
-}
-
-// ── Approval Args Sanitization ─────────────────────────────────────
-
-// Relocated to src/shared/args-preview.ts so both harnesses share one home for
-// arg sanitization. Re-exported here so the native importers (v3-status-builder,
-// approval-file-change) keep their existing import path.
-export { sanitizeArgsPreview } from "../../shared/args-preview.js";