@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/src/harness/__tests__/terminal-table.test.ts

@@ -0,0 +1,81 @@
+/**
+ * Pins the stop cause of every way a turn ends (`../terminal-table.ts`):
+ * each arm that stops a turn names the one structured cause the session's
+ * status reads (`RunStatus.stop_cause`), the waiting arm names none (a
+ * turn waits only on an approval; file review never holds one),
+ * and applying an arm writes the cause and reports where its rows landed,
+ * so the session event emitter never writes them as harness notes.
+ *
+ * The walk is checked against the module's exports, so an arm added
+ * without a line here fails the coverage arm.
+ */
+
+import { create } from "@bufbuild/protobuf";
+import { describe, expect, it } from "vitest";
+import { RunStatusSchema } from "@stigmer/apis/ai/stigmer/agentic/run/v1/api_pb";
+import { RunPhase } from "@stigmer/apis/ai/stigmer/agentic/run/v1/enum_pb";
+
+import { StallTimeoutError } from "../../shared/stall-watchdog.js";
+import { WorkspaceLockTimeoutError } from "../../shared/workspace/workspace-lock.js";
+import * as table from "../terminal-table.js";
+import type { StopCause, TerminalArm } from "../terminal-table.js";
+import { MessageType } from "../../gen/turn/ai/stigmer/runner/turn/v1/enum_pb.js";
+import { TurnRowsSchema } from "../../gen/turn/ai/stigmer/runner/turn/v1/rows_pb.js";
+
+const ARMS: ReadonlyArray<{ readonly name: string; readonly arm: TerminalArm; readonly cause: StopCause | null }> = [
+  { name: "stallArm", arm: table.stallArm(new StallTimeoutError(1_000)), cause: "timeout" },
+  { name: "evalScaffoldFailedArm", arm: table.evalScaffoldFailedArm("scaffold failed"), cause: "eval_stopped" },
+  { name: "mockAbortArm", arm: table.mockAbortArm({ server: "s", tool: "t", reason: "r" }), cause: "eval_stopped" },
+  { name: "costCapArm", arm: table.costCapArm(1, 2), cause: "budget_reached" },
+  { name: "toolCallLimitArm", arm: table.toolCallLimitArm(), cause: "budget_reached" },
+  { name: "workerShutdownArm", arm: table.workerShutdownArm(), cause: "infrastructure" },
+  { name: "orchestratorStopArm", arm: table.orchestratorStopArm(), cause: "user" },
+  { name: "infrastructureCancelArm", arm: table.infrastructureCancelArm(), cause: "infrastructure" },
+  { name: "awaitingApprovalArm", arm: table.awaitingApprovalArm(), cause: null },
+  { name: "platformStopArm", arm: table.platformStopArm(), cause: "platform_stop" },
+  {
+    name: "workspaceLockTimeoutArm",
+    arm: table.workspaceLockTimeoutArm(new WorkspaceLockTimeoutError("/w", 1_000)),
+    cause: "timeout",
+  },
+  {
+    name: "fileReviewResolvedArm",
+    arm: table.fileReviewResolvedArm({ failed: false, failureDetail: "", discardedPaths: [] }),
+    cause: "review_resolved",
+  },
+  { name: "failedArm", arm: table.failedArm("the model refused", "engine"), cause: "model_error" },
+  { name: "unexpectedErrorArm", arm: table.unexpectedErrorArm("TypeError", "boom"), cause: "failed" },
+];
+
+describe("the stop cause of every terminal arm", () => {
+  it.each(ARMS)("$name names $cause", ({ arm, cause }) => {
+    expect(arm.stopCause).toBe(cause);
+  });
+
+  it("a failure the user can act on, or the runner's own, is failed; only the engine's is model_error", () => {
+    expect(table.failedArm("fix the hook", "actionable").stopCause).toBe("failed");
+    expect(table.failedArm("transport broke", "internal").stopCause).toBe("failed");
+  });
+
+  it("every exported arm is walked here", () => {
+    const exported = Object.keys(table).filter((key) => key.endsWith("Arm") && key !== "applyTerminalArm");
+    expect(new Set(exported)).toEqual(new Set(ARMS.map((a) => a.name)));
+  });
+});
+
+describe("applying an arm", () => {
+  it("writes the stop cause and reports the root positions of the rows it appended", () => {
+    const status = create(RunStatusSchema, { phase: RunPhase.RUN_IN_PROGRESS });
+    const turn = create(TurnRowsSchema, { messages: [{ type: MessageType.MESSAGE_AI, content: "working" }] });
+    const rows = table.applyTerminalArm(status, turn, table.failedArm("boom", "internal"));
+    expect(status.stopCause).toBe("failed");
+    expect(rows).toEqual([1, 2]);
+    expect(rows.map((index) => turn.messages[index]!.type)).toEqual([MessageType.MESSAGE_SYSTEM, MessageType.MESSAGE_SYSTEM]);
+  });
+
+  it("a waiting arm leaves the stop cause as it was and appends nothing of its own", () => {
+    const status = create(RunStatusSchema, { phase: RunPhase.RUN_IN_PROGRESS });
+    expect(table.applyTerminalArm(status, create(TurnRowsSchema), table.awaitingApprovalArm())).toEqual([]);
+    expect(status.stopCause).toBe("");
+  });
+});

package/src/harness/__tests__/transcript-is-engine-free.test.ts

@@ -0,0 +1,83 @@
+/**
+ * Pins that the transcript builder knows no engine: every file under
+ * `src/harness/transcript/`, tests included, names only the packages on a
+ * short allow-list — the proto runtime and the generated protos, Node's
+ * builtins, and `vitest` inside `__tests__/`.
+ *
+ * Why it matters (the canonical transcript's one disposition rule): the builder folds
+ * facts into the status proto; every fact about an engine — a LangGraph
+ * namespace, a Cursor `SDKMessage`, a LangChain `ToolMessage` envelope —
+ * reaches it as a translator's output, never as an import. A Claude or Codex
+ * adapter is then a translator and nothing else. `@temporalio/*` is refused
+ * for the same reason the adapters refuse it: the builder runs under the
+ * contract kit outside any activity, and it moved out from under the native
+ * adapter's Temporal-free fence when it moved into `harness/` (the runtime
+ * itself is not Temporal-free — `run-turn.ts` heartbeats).
+ *
+ * An ALLOW-list, not a deny-list: an SDK that does not exist yet is refused
+ * on the day this file was written, and admitting a new package is a visible
+ * edit here with a reason, not an absence someone forgot to extend. Tests are
+ * swept too, on the direction fence's precedent (`import-direction.test.ts`):
+ * a test that imported `@langchain/core` to build a fixture would be exactly
+ * the coupling that keeps the builder's own tests in the native adapter's
+ * folder until #1097 re-keyed them to the canonical union.
+ *
+ * Landed in #1097, the day the folder was created.
+ */
+
+import { describe, it, expect } from "vitest";
+import { join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { packageNames, readSource, typeScriptFilesUnder } from "../../__test-utils__/module-specifiers.js";
+
+const SRC_ROOT = fileURLToPath(new URL("../../", import.meta.url));
+const TRANSCRIPT_ROOT = join(SRC_ROOT, "harness", "transcript");
+
+/** What a production module under `harness/transcript/` may name. */
+const ALLOWED = new Set(["@bufbuild/protobuf", "@stigmer/apis"]);
+/** What a test under `harness/transcript/__tests__/` may name in addition. */
+const ALLOWED_IN_TESTS = new Set([...ALLOWED, "vitest"]);
+
+function isTestFile(file: string): boolean {
+  return file.includes(`${sep}__tests__${sep}`);
+}
+
+describe("packageNames (the checker itself)", () => {
+  const file = join(TRANSCRIPT_ROOT, "builder.ts");
+
+  it("reduces a specifier to its package and drops relatives and builtins", () => {
+    const source = [
+      'import { create } from "@bufbuild/protobuf";',
+      'import type { AgentMessage } from "@stigmer/apis/ai/stigmer/agentic/run/v1/message_pb";',
+      'import { join } from "node:path";',
+      'import { a } from "./events.js";',
+      'import { b } from "../../shared/status.js";',
+      'import ts from "typescript";',
+      'const m = await import("@langchain/core/messages");',
+    ].join("\n");
+    expect(packageNames(file, source)).toEqual(["@bufbuild/protobuf", "@stigmer/apis", "typescript", "@langchain/core"]);
+  });
+});
+
+describe("src/harness/transcript names no engine, no SDK, no Temporal", () => {
+  const files = typeScriptFilesUnder(TRANSCRIPT_ROOT, new Set());
+  const offences = files.flatMap((file) => {
+    const allowed = isTestFile(file) ? ALLOWED_IN_TESTS : ALLOWED;
+    return packageNames(file, readSource(file))
+      .filter((pkg) => !allowed.has(pkg))
+      .map((pkg) => `  ${relative(SRC_ROOT, file)} names "${pkg}"`);
+  });
+
+  it("inspected the builder's own files, tests included (the walk is rooted where it claims)", () => {
+    const walked = files.map((f) => relative(TRANSCRIPT_ROOT, f));
+    expect(walked).toEqual(expect.arrayContaining(["builder.ts", "events.ts", "state.ts", join("__tests__", "state.test.ts")]));
+  });
+
+  it("finds no package outside the allow-list", () => {
+    expect(
+      offences,
+      `src/harness/transcript/ may name only ${[...ALLOWED_IN_TESTS].join(", ")} (vitest in tests only):\n${offences.join("\n")}`,
+    ).toEqual([]);
+  });
+});

package/src/harness/__tests__/transcript-writers.test.ts

@@ -0,0 +1,193 @@
+/**
+ * Pins who may CREATE a transcript row: an `AgentMessage`, a `ToolCall` or a
+ * `SubAgentRun` on the turn's rows. Two writers, and no third:
+ *
+ *  - `src/harness/transcript/` — the one transcript builder, which every
+ *    harness folds its engine's events through (`TurnSink.transcript`), and
+ *    beside it the reinvocation's seed, which builds the asks it resumes
+ *    onto from the session's log and hands them to the builder;
+ *  - `src/harness/terminal-table.ts` — the runtime's terminal system rows
+ *    (the pause copy, the failure copy), which are not transcript facts of
+ *    any engine and never were.
+ *
+ * Why it matters (#1097's founding promise): the promise that a
+ * third harness is "a translator and nothing else" holds only while there
+ * is exactly one place a row comes from. A module that builds a row itself
+ * — an adapter pushing an AI message with a WAITING call, a settle
+ * synthesizing a SYSTEM line — is a second copy of the folding rule, and
+ * the two copies drift (the memo counted three such copies before this
+ * entry). The rule is about CREATION. Amending a row a builder created —
+ * flipping a WAITING row SKIPPED, stamping a change-set id, marking a
+ * sub-agent CANCELLED, the Cursor boundary's identity-based collapses — is
+ * legitimate, and the modules that do it are named in `TurnSink`'s header;
+ * a fence over them would be a list, not a rule.
+ *
+ * A reinvocation's asks are not an exception: the seed that builds them
+ * lives with the builder (`transcript/resume-seed.ts`) and they enter the
+ * rows THROUGH the builder (`TranscriptBuilder.seed`), so the seed indexes
+ * what it appends and this list stays at two. The generated row types
+ * (`src/gen`) name the schemas they define and are not swept.
+ *
+ * The rule is read off the TypeScript syntax tree, as the import fences are
+ * (`import-direction.test.ts`): a schema named in a header comment, or a
+ * `.messages.push(` in prose, cannot trip it; a row built through any of the
+ * three schemas, or an array push onto `messages` / `subAgentExecutions`
+ * wherever the array is reached from, cannot slip past it.
+ */
+
+import { describe, it, expect } from "vitest";
+import { join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+
+import { readSource, typeScriptFilesUnder } from "../../__test-utils__/module-specifiers.js";
+
+const SRC_ROOT = fileURLToPath(new URL("../../", import.meta.url));
+
+/** The proto schemas a transcript row is created through; naming one is creating one. */
+const ROW_SCHEMAS: ReadonlySet<string> = new Set(["AgentMessageSchema", "ToolCallSchema", "SubAgentExecutionSchema"]);
+
+/** The status arrays a created row is pushed onto. */
+const ROW_ARRAYS: ReadonlySet<string> = new Set(["messages", "subAgentExecutions"]);
+
+/** The modules allowed to create rows, relative to `src/`: a directory (every file under it) or a file. */
+const ALLOWED_CREATORS: readonly string[] = [
+  join("harness", "transcript") + sep,
+  join("harness", "terminal-table.ts"),
+];
+
+/** Every row-creating construct in `source`, in source order: `names <Schema>` or `pushes onto .<array>`. */
+export function transcriptRowWrites(fileName: string, source: string): string[] {
+  const sourceFile = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, /* setParentNodes */ false);
+  const writes: string[] = [];
+  const visit = (node: ts.Node): void => {
+    if (ts.isIdentifier(node) && ROW_SCHEMAS.has(node.text)) {
+      const write = `names ${node.text}`;
+      if (!writes.includes(write)) writes.push(write);
+    } else if (
+      ts.isCallExpression(node) &&
+      ts.isPropertyAccessExpression(node.expression) &&
+      node.expression.name.text === "push" &&
+      ts.isPropertyAccessExpression(node.expression.expression) &&
+      ROW_ARRAYS.has(node.expression.expression.name.text)
+    ) {
+      const write = `pushes onto .${node.expression.expression.name.text}`;
+      if (!writes.includes(write)) writes.push(write);
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return writes;
+}
+
+function isAllowedCreator(relativeFile: string): boolean {
+  return ALLOWED_CREATORS.some((allowed) => (allowed.endsWith(sep) ? relativeFile.startsWith(allowed) : relativeFile === allowed));
+}
+
+interface Offence {
+  readonly file: string;
+  readonly writes: readonly string[];
+}
+
+interface Sweep {
+  readonly visited: string[];
+  readonly creators: string[];
+  readonly offences: Offence[];
+}
+
+/** Production modules only: tests and test utilities build rows freely (fixtures, goldens' drivers). */
+function sweep(): Sweep {
+  const visited: string[] = [];
+  const creators: string[] = [];
+  const offences: Offence[] = [];
+  for (const file of typeScriptFilesUnder(SRC_ROOT, new Set(["__tests__", "__test-utils__", "gen"]))) {
+    const relativeFile = relative(SRC_ROOT, file);
+    visited.push(relativeFile);
+    const writes = transcriptRowWrites(file, readSource(file));
+    if (writes.length === 0) continue;
+    creators.push(relativeFile);
+    if (!isAllowedCreator(relativeFile)) offences.push({ file: relativeFile, writes });
+  }
+  return { visited, creators, offences };
+}
+
+function describeOffences(offences: readonly Offence[]): string {
+  return offences.map((o) => `  ${o.file}: ${o.writes.join(", ")}`).join("\n");
+}
+
+describe("transcriptRowWrites (the checker itself)", () => {
+  const file = join(SRC_ROOT, "activities", "some-harness", "settle.ts");
+
+  it.each([
+    ["a message built through its schema", 'const m = create(AgentMessageSchema, { content: "x" });', "names AgentMessageSchema"],
+    ["a tool call built through its schema", "const tc = create(ToolCallSchema, { id });", "names ToolCallSchema"],
+    ["a sub-agent row built through its schema", "const row = create(SubAgentExecutionSchema, { id });", "names SubAgentExecutionSchema"],
+    ["a schema merely imported", 'import { AgentMessageSchema } from "@stigmer/apis/x_pb";', "names AgentMessageSchema"],
+    ["a push onto the root transcript", "status.messages.push(msg);", "pushes onto .messages"],
+    ["a push onto a nested transcript", "scope.row.messages.push(msg);", "pushes onto .messages"],
+    ["a spread push", "sink.status.messages.push(...seed.messages);", "pushes onto .messages"],
+    ["a push onto the sub-agent rows", "this.proto.subAgentExecutions.push(row);", "pushes onto .subAgentExecutions"],
+  ])("flags %s", (_label, source, expected) => {
+    expect(transcriptRowWrites(file, source)).toEqual([expected]);
+  });
+
+  it.each([
+    ["a schema named in a comment", "// built through AgentMessageSchema elsewhere\nconst x = 1;"],
+    ["a push described in a comment", "// the builder does status.messages.push(msg)\nconst x = 1;"],
+    ["a schema named in a string", 'const hint = "AgentMessageSchema";'],
+    ["a read of the transcript", "const last = status.messages.at(-1);"],
+    ["a push onto an unrelated array", "status.artifacts.push(artifact);"],
+    ["a push onto a bare `messages` local", "messages.push(m);"],
+    ["the message TYPE, not its schema", 'import type { AgentMessage } from "@stigmer/apis/x_pb";'],
+    ["an in-place amendment of a row", "row.status = ToolCallStatus.TOOL_CALL_SKIPPED;"],
+  ])("does not flag %s", (_label, source) => {
+    expect(transcriptRowWrites(file, source)).toEqual([]);
+  });
+
+  it("names each construct once, in source order", () => {
+    const source = [
+      "const a = create(AgentMessageSchema, {});",
+      "const b = create(ToolCallSchema, {});",
+      "const c = create(AgentMessageSchema, {});",
+      "a.toolCalls.push(b); status.messages.push(a); status.messages.push(c);",
+    ].join("\n");
+    expect(transcriptRowWrites(file, source)).toEqual(["names AgentMessageSchema", "names ToolCallSchema", "pushes onto .messages"]);
+  });
+});
+
+describe("only the transcript builder and the terminal table create transcript rows", () => {
+  const result = sweep();
+
+  it("inspected production modules across src/ and skipped the test trees (the walk is rooted where it claims)", () => {
+    expect(result.visited).toEqual(
+      expect.arrayContaining([
+        join("harness", "run-turn.ts"),
+        join("harness", "transcript", "builder.ts"),
+        join("activities", "execute-cursor", "boundary-rows.ts"),
+        join("activities", "execute-deep-agent", "hitl.ts"),
+        join("shared", "exact-apply.ts"),
+      ]),
+    );
+    expect(
+      result.visited.some((f) => f.includes(`${sep}__tests__${sep}`) || f.includes(`${sep}__test-utils__${sep}`)),
+      "the production sweep must skip the test trees",
+    ).toBe(false);
+  });
+
+  it("found the allowed creators (the checker sees the rows it exists to see)", () => {
+    expect(result.creators).toEqual(
+      expect.arrayContaining([
+        join("harness", "transcript", "builder.ts"),
+        join("harness", "transcript", "state.ts"),
+        join("harness", "terminal-table.ts"),
+      ]),
+    );
+  });
+
+  it("finds no creator outside the allow-list", () => {
+    expect(
+      result.offences,
+      `a transcript row is created through TurnSink.transcript, never built in place:\n${describeOffences(result.offences)}`,
+    ).toEqual([]);
+  });
+});

package/src/harness/__tests__/turn-attachments-vision.test.ts

@@ -0,0 +1,105 @@
+/**
+ * Pins which model the attachment phase asks the registry about when it
+ * sizes the vision budget (`turn-context.ts` `resolveTurnAttachments`): the
+ * model the turn's resolved settings name (`status.run_config`), or the
+ * registry's default when they name none — the model the native harness
+ * will build in that case — and never the model the request asked for.
+ * Before #1096 the phase asked about the raw requested name, so an
+ * execution with no model named asked about `""` (always "unknown", read as
+ * sighted) while the native orchestrator asked about the resolved default
+ * (its `setup.ts`, retired with it).
+ *
+ * The registry module is doubled at its boundary: this test is about WHICH
+ * name is asked, not about the registry's answer. The phase is entered with
+ * no attachments so nothing touches the file system; the budget's decisions
+ * over real images are `shared/__tests__/attachment-vision.test.ts`'s.
+ */
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { RunStatusSchema } from "@stigmer/apis/ai/stigmer/agentic/run/v1/api_pb";
+import { RunSpecSchema } from "@stigmer/apis/ai/stigmer/agentic/run/v1/spec_pb";
+import { RunConfigSchema } from "@stigmer/apis/ai/stigmer/agentic/run/v1/invocation_pb";
+
+vi.mock("../../shared/model-registry.js", () => ({
+  getDefaultModel: vi.fn(async () => "registry-default-model"),
+  getModelVisionCapability: vi.fn(async () => true),
+}));
+
+import { getDefaultModel, getModelVisionCapability } from "../../shared/model-registry.js";
+import { DEEP_AGENT_VISION_PROFILE } from "../../shared/attachment-vision.js";
+import { TimingRecorder } from "../../shared/cold-start-timing.js";
+import { mockStigmerClient } from "../../__test-utils__/mock-client.js";
+import { testConfig } from "../../__test-utils__/config-fixture.js";
+import { TranscriptBuilder } from "../transcript/builder.js";
+import { resolveTurnAttachments, type ResolutionDeps } from "../turn-context.js";
+import { TurnRowsSchema } from "../../gen/turn/ai/stigmer/runner/turn/v1/rows_pb.js";
+
+function deps(): ResolutionDeps {
+  const status = create(RunStatusSchema, {});
+  const rows = create(TurnRowsSchema);
+  return {
+    input: { executionId: "aex_1", threadId: "", turnSeq: 0 },
+    client: mockStigmerClient(),
+    config: testConfig(),
+    status,
+    rows,
+    transcript: new TranscriptBuilder("aex_1", rows, status),
+    artifactStorage: undefined,
+    timing: new TimingRecorder(),
+    signal: new AbortController().signal,
+    heartbeat: () => {},
+    enterPhase: () => {},
+    reportProgress: async () => {},
+    identifyRun: () => {},
+    recordReconciled: async () => {},
+  };
+}
+
+async function resolveWithModel(modelName: string | undefined, requestedModelName?: string): Promise<void> {
+  await resolveTurnAttachments(deps(), {
+    spec: create(
+      RunSpecSchema,
+      requestedModelName === undefined ? {} : { runConfig: { modelName: requestedModelName } },
+    ),
+    runConfig: modelName === undefined ? undefined : create(RunConfigSchema, { modelName }),
+    sessionId: "ses_1",
+    primaryDir: "/nowhere",
+    visionProfile: DEEP_AGENT_VISION_PROFILE,
+  });
+}
+
+describe("resolveTurnAttachments: the model the vision budget asks about", () => {
+  beforeEach(() => {
+    vi.mocked(getDefaultModel).mockClear();
+    vi.mocked(getModelVisionCapability).mockClear();
+  });
+
+  it("asks about the model the turn's resolved settings name, without consulting the default", async () => {
+    await resolveWithModel("claude-haiku-4.5");
+    expect(vi.mocked(getModelVisionCapability)).toHaveBeenCalledWith("claude-haiku-4.5");
+    expect(vi.mocked(getDefaultModel)).not.toHaveBeenCalled();
+  });
+
+  it("asks about the registry's default when the resolved settings name none — the model the turn will run on, not the empty string", async () => {
+    await resolveWithModel(undefined);
+    expect(vi.mocked(getDefaultModel)).toHaveBeenCalledTimes(1);
+    expect(vi.mocked(getModelVisionCapability)).toHaveBeenCalledWith("registry-default-model");
+  });
+
+  it("treats an empty model name as none", async () => {
+    await resolveWithModel("");
+    expect(vi.mocked(getModelVisionCapability)).toHaveBeenCalledWith("registry-default-model");
+  });
+
+  it("asks about the resolved model, never the one the request asked for", async () => {
+    await resolveWithModel("resolved-model", "requested-model");
+    expect(vi.mocked(getModelVisionCapability)).toHaveBeenCalledWith("resolved-model");
+    expect(vi.mocked(getModelVisionCapability)).not.toHaveBeenCalledWith("requested-model");
+  });
+
+  it("falls to the registry's default when only the request names a model", async () => {
+    await resolveWithModel(undefined, "requested-model");
+    expect(vi.mocked(getModelVisionCapability)).toHaveBeenCalledWith("registry-default-model");
+  });
+});