Skip to content

armgit / Orkas

Public Imported from GitHub
0

Orkas is an open-source (MIT), local-first AI team for your desktop: a Commander turns your goal into to-dos and coordinates 16 built-in specialist agents plus Claude Code, Codex, OpenCode, OpenClaw and Hermes, with projects, scheduled automations and connectors. Free app for macOS & Windows; built-in models or your own keys.

82.3 KB
Raw Blame
import { describe, it, expect, vi } from "vitest";
import path from "node:path";
import fs from "node:fs/promises";
import os from "node:os";
import { createExecutionPlanTool, defineTool, toToolDefinition, getBuiltinTools } from "../src/tools/index.js";
import { Session } from "../src/agent/session.js";
import { DEFAULT_BASH_TIMEOUT_MS, normalizeBashTimeoutMs } from "../src/tools/builtin.js";
import { compactGitHubReadme } from "../src/tools/github-repository-fetch.js";
import { MAX_WEB_FETCH_RESPONSE_BYTES } from "../src/tools/web-fetch.js";
import type { AgentTool, ToolContext } from "../src/tools/index.js";

const TEST_NODE = process.env.ORKAS_TEST_NODE || process.execPath;

function shellQuote(value: string): string {
  return process.platform === "win32"
    ? `'${value.replace(/'/g, "''")}'`
    : `'${value.replace(/'/g, "'\\''")}'`;
}

function shellInvoke(executable: string, args: string[]): string {
  const command = [shellQuote(executable), ...args.map(shellQuote)].join(" ");
  return process.platform === "win32" ? `& ${command}` : command;
}

describe("Tools", () => {
  describe("defineTool", () => {
    it("preserves trusted continuation inspection without exposing it to the model", () => {
      const inspectReadContinuation = vi.fn(() => ({ version: "private", waiting: true }));
      const tool = defineTool({
        name: "read_progress", description: "Read progress", inputSchema: { type: "object" },
        inspectReadContinuation,
        async execute() { return { content: "ok" }; },
      });
      expect(tool.inspectReadContinuation).toBe(inspectReadContinuation);
      expect(toToolDefinition(tool)).not.toHaveProperty("inspectReadContinuation");
      expect(JSON.stringify(toToolDefinition(tool))).not.toContain("private");
      expect(inspectReadContinuation).not.toHaveBeenCalled();
    });

    it("creates a tool with all required fields", () => {
      const tool = defineTool({
        name: "test_tool",
        description: "A test tool",
        inputSchema: { type: "object", properties: {} },
        async execute() {
          return { content: "ok" };
        },
      });

      expect(tool.name).toBe("test_tool");
      expect(tool.description).toBe("A test tool");
      expect(typeof tool.execute).toBe("function");
    });

    it("executes and returns result", async () => {
      const tool = defineTool({
        name: "echo",
        description: "Echo input",
        inputSchema: { type: "object", properties: { text: { type: "string" } } },
        async execute(input) {
          return { content: input.text as string };
        },
      });

      const ctx: ToolContext = { state: {} };
      const result = await tool.execute({ text: "hello" }, ctx);
      expect(result.content).toBe("hello");
      expect(result.isError).toBeUndefined();
    });
  });

  describe("manage_execution_plan tool", () => {
    it("exposes one complete-snapshot contract while keeping mutation mechanics host-owned", () => {
      const session = new Session();
      const tool = createExecutionPlanTool({
        get: () => session.getExecutionPlan(),
        update: (update) => session.updateExecutionPlan(update),
        clear: () => session.clearExecutionPlan(),
      });

      const properties = tool.inputSchema.properties as Record<string, Record<string, unknown>>;
      expect(tool.description.length).toBeLessThanOrEqual(480);
      expect(tool.description).toContain("optional current-task Plan");
      expect(tool.description).toContain("complete ordered snapshot");
      expect(tool.description).toContain("few durable outcome milestones");
      expect(tool.description).toContain("complex work");
      expect(tool.description).toContain("progress state across rounds");
      expect(tool.description).toContain("at most one in_progress");
      expect(tool.description).toContain("working memory, not task completion or termination");
      expect(tool.description).toContain("todo_tasks");
      expect(tool.description).not.toContain("when a key milestone");
      expect(tool.description).not.toContain("otherwise update separately");
      expect(tool.description).not.toContain("Co-emit");
      expect(Object.keys(properties).sort()).toEqual(["explanation", "plan"]);
      expect(properties.explanation.description).toContain("reason for this Plan update");
      expect(properties.plan.description).toContain("preserves existing step text exactly");
      expect(properties.plan.description).toContain("updates statuses in one batch");
      expect(properties.plan.minItems).toBe(1);
      expect(tool.inputSchema.required).toEqual(["plan"]);
      expect(properties).not.toHaveProperty("action");
      expect(properties).not.toHaveProperty("replace_objective");
      expect(properties).not.toHaveProperty("updates");
      expect(properties).not.toHaveProperty("finish");
      expect(properties).not.toHaveProperty("step_id");
      expect(properties).not.toHaveProperty("step");
      expect(properties).not.toHaveProperty("status");
    });

    it("creates a plan directly from the first complete snapshot", async () => {
      const session = new Session();
      session.beginUserTurn([{ type: "text", text: "Complete the task" }]);
      const tool = createExecutionPlanTool({
        get: () => session.getExecutionPlan(),
        update: (update) => session.updateExecutionPlan(update),
        clear: () => session.clearExecutionPlan(),
      });
      const context: ToolContext = { state: {} };

      const inferred = await tool.execute({
        plan: [{ step: "Complete the work", status: "working" }],
      }, context);

      expect(inferred.isError).toBeUndefined();
      expect(JSON.parse(inferred.content)).toMatchObject({
        action: "update",
        action_inferred: true,
        revision: 1,
        updated_step_ids: [1],
      });
      expect(session.getExecutionPlan()?.steps[0].status).toBe("in_progress");
    });

    it("repairs a complete guarded plan mislabeled as set_status", async () => {
      const session = new Session();
      session.beginUserTurn([{ type: "text", text: "Complete the staged task" }]);
      session.updateExecutionPlan({
        steps: [
          { step: "Inspect the project", status: "completed" },
          { step: "Summarize the structure", status: "in_progress" },
        ],
      });
      const tool = createExecutionPlanTool({
        get: () => session.getExecutionPlan(),
        update: (update) => session.updateExecutionPlan(update),
        clear: () => session.clearExecutionPlan(),
      });
      const context: ToolContext = { state: {} };

      const repaired = await tool.execute({
        action: "set_status",
        plan: [
          { step: "Inspect the project", status: "completed" },
          { step: "Summarize the structure", status: "completed" },
        ],
      }, context);

      expect(repaired.isError).toBeUndefined();
      expect(JSON.parse(repaired.content)).toMatchObject({
        action: "update",
        action_inferred: true,
      });
      expect(session.getExecutionPlan()?.steps.map((step) => step.status))
        .toEqual(["completed", "completed"]);
    });

    it("does not repair ambiguous set_status payloads with one narrow field present", async () => {
      const session = new Session();
      session.beginUserTurn([{ type: "text", text: "Complete the staged task" }]);
      session.updateExecutionPlan({
        steps: [{ step: "Complete the work", status: "in_progress" }],
      });
      const tool = createExecutionPlanTool({
        get: () => session.getExecutionPlan(),
        update: (update) => session.updateExecutionPlan(update),
        clear: () => session.clearExecutionPlan(),
      });
      const context: ToolContext = { state: {} };
      const plan = [{ step: "Complete the work", status: "completed" }];

      const missingStatus = await tool.execute({
        action: "set_status",
        step_id: 1,
        plan,
      }, context);
      const missingStepId = await tool.execute({
        action: "set_status",
        status: "completed",
        plan,
      }, context);

      expect(missingStatus).toMatchObject({ isError: true });
      expect(JSON.parse(missingStatus.content)).toMatchObject({
        ok: false,
        error_code: "PLAN_STATUS_INVALID",
        message: "manage_execution_plan set_status requires a valid status",
        current_revision: 1,
        current_steps: [{ id: 1, step: "Complete the work", status: "in_progress" }],
      });
      expect(missingStepId).toMatchObject({ isError: true });
      expect(JSON.parse(missingStepId.content)).toMatchObject({
        ok: false,
        error_code: "PLAN_STEP_ID_INVALID",
        message: "manage_execution_plan set_status requires a positive integer step_id",
        current_revision: 1,
      });
      expect(session.getExecutionPlan()?.steps[0].status).toBe("in_progress");
    });

    it("accepts replace as a legacy alias without bypassing plan guards", async () => {
      const session = new Session();
      session.beginUserTurn([{ type: "text", text: "Complete the task" }]);
      const tool = createExecutionPlanTool({
        get: () => session.getExecutionPlan(),
        update: (update) => session.updateExecutionPlan(update),
        clear: () => session.clearExecutionPlan(),
      });
      const context: ToolContext = { state: {} };

      const result = await tool.execute({
        action: "replace",
        plan: [{ step: "Complete the work", status: "in_progress" }],
      }, context);

      expect(result.isError).toBeUndefined();
      expect(JSON.parse(result.content)).toMatchObject({ action: "update", action_inferred: false });
      expect(session.getExecutionPlan()?.steps[0].step).toBe("Complete the work");
    });

    it("downgrades a redundant replace_objective replay to a guarded status update", async () => {
      const session = new Session();
      session.beginUserTurn([{ type: "text", text: "Complete the original task" }]);
      session.updateExecutionPlan({
        steps: [{ step: "Complete the work", status: "in_progress" }],
      });
      session.addMessage("user", [{ type: "text", text: "Also include the revised requirement" }]);
      const tool = createExecutionPlanTool({
        get: () => session.getExecutionPlan(),
        update: (update) => session.updateExecutionPlan(update),
        clear: () => session.clearExecutionPlan(),
      });
      const context: ToolContext = { state: {} };
      const revisedPlan = [
        { step: "Complete the work", status: "completed" },
        { step: "Include the revised requirement", status: "in_progress" },
      ];

      const first = await tool.execute({
        action: "update",
        replace_objective: true,
        plan: revisedPlan,
      }, context);
      const replay = await tool.execute({
        action: "update",
        replace_objective: true,
        plan: revisedPlan,
      }, context);

      expect(first.isError).toBeUndefined();
      expect(JSON.parse(first.content)).toMatchObject({ replace_objective_applied: true });
      expect(replay.isError).toBeUndefined();
      expect(JSON.parse(replay.content)).toMatchObject({ replace_objective_applied: false });
      expect(session.getExecutionPlan()?.objective).toBe("Also include the revised requirement");

      const unsafeReplay = await tool.execute({
        action: "update",
        replace_objective: true,
        plan: [{ step: "Do less work", status: "completed" }],
      }, context);
      expect(unsafeReplay.isError).toBe(true);
      expect(unsafeReplay.content).toContain("cannot remove or rename existing milestones");
    });

    it("advances statuses, appends work, and ignores a replay through complete snapshots", async () => {
      const session = new Session();
      session.beginUserTurn([{ type: "text", text: "Complete the staged task" }]);
      const tool = createExecutionPlanTool({
        get: () => session.getExecutionPlan(),
        update: (update) => session.updateExecutionPlan(update),
        clear: () => session.clearExecutionPlan(),
      });
      const context: ToolContext = { state: {} };

      const initial = await tool.execute({
        explanation: "Create the durable milestones",
        plan: [
          { step: "Inspect the inputs", status: "in_progress" },
          { step: "Verify the result", status: "pending" },
        ],
      }, context);
      expect(JSON.parse(initial.content)).toMatchObject({
        revision: 1,
        step_ids: [1, 2],
        updated_step_ids: [1, 2],
      });
      expect(initial.observations?.coordination).toEqual({ changed: true });
      expect(JSON.parse(initial.content)).not.toHaveProperty("steps");

      const nextSnapshot = [
        { step: "Inspect the inputs", status: "completed" },
        { step: "Verify the result", status: "in_progress" },
        { step: "Publish the result", status: "pending" },
      ] as const;
      const advanced = await tool.execute({
        explanation: "Inspection finished and publishing was discovered",
        plan: nextSnapshot,
      }, context);
      expect(advanced.isError).toBeUndefined();
      expect(JSON.parse(advanced.content)).toMatchObject({
        action: "update",
        action_inferred: true,
        revision: 2,
        step_count: 3,
        step_ids: [1, 2, 3],
        updated_step_ids: [1, 2, 3],
      });
      expect(session.getExecutionPlan()?.steps.map((item) => item.id)).toEqual([1, 2, 3]);
      expect(session.getExecutionPlan()?.steps.map((item) => item.status))
        .toEqual(["completed", "in_progress", "pending"]);

      const replay = await tool.execute({
        explanation: "A different explanation cannot manufacture progress",
        plan: nextSnapshot,
      }, context);
      expect(replay.isError).toBeUndefined();
      const replayReceipt = JSON.parse(replay.content);
      expect(replayReceipt).toMatchObject({
        revision: 2,
        updated_step_ids: [],
        unchanged: true,
      });
      expect(replay.observations?.coordination).toEqual({ changed: false });
      expect(replayReceipt).not.toHaveProperty("do_not_retry");
      expect(replayReceipt).not.toHaveProperty("next_action");
      expect(session.getExecutionPlanAudit()).toHaveLength(2);
    });

    it("atomically updates several known statuses while preserving stable step ids", async () => {
      const session = new Session();
      session.beginUserTurn([{ type: "text", text: "Complete the staged task" }]);
      session.updateExecutionPlan({
        steps: [
          { step: "Inspect the inputs", status: "in_progress" },
          { step: "Verify the evidence", status: "pending" },
          { step: "Publish the result", status: "pending" },
        ],
      });
      const tool = createExecutionPlanTool({
        get: () => session.getExecutionPlan(),
        update: (update) => session.updateExecutionPlan(update),
        clear: () => session.clearExecutionPlan(),
      });
      const context: ToolContext = { state: {} };

      const result = await tool.execute({
        action: "set_statuses",
        updates: [
          { step_id: 1, status: "completed" },
          { step_id: "step_2", status: "in_progress" },
          { step_id: 3, status: "completed" },
        ],
      }, context);

      expect(result.isError).toBeUndefined();
      expect(JSON.parse(result.content)).toMatchObject({
        action: "set_statuses",
        revision: 2,
        requested_step_ids: [1, 2, 3],
        updated_step_ids: [1, 2, 3],
        unchanged_step_ids: [],
      });
      expect(session.getExecutionPlan()?.steps).toEqual([
        { id: 1, step: "Inspect the inputs", status: "completed" },
        { id: 2, step: "Verify the evidence", status: "in_progress" },
        { id: 3, step: "Publish the result", status: "completed" },
      ]);
    });

    it("accepts a legacy completed finish marker without turning Plan into a terminal tool", async () => {
      const session = new Session();
      session.beginUserTurn([{ type: "text", text: "Complete and verify the staged task" }]);
      session.updateExecutionPlan({
        steps: [
          { step: "Complete the work", status: "completed" },
          { step: "Verify the result", status: "in_progress" },
        ],
      });
      const tool = createExecutionPlanTool({
        get: () => session.getExecutionPlan(),
        update: (update) => session.updateExecutionPlan(update),
        clear: () => session.clearExecutionPlan(),
      });

      const result = await tool.execute({
        action: "set_status",
        step_id: 2,
        status: "completed",
        finish: "completed",
      }, { state: {} });

      expect(result.endTurn).toBeUndefined();
      expect(result.synthesizeIfNoText).toBeUndefined();
      expect(JSON.parse(result.content)).toMatchObject({
        ok: true,
        finish: "completed",
        updated_step_ids: [2],
        step_ids: [1, 2],
      });
      expect(JSON.parse(result.content)).not.toHaveProperty("terminal");
      expect(JSON.parse(result.content)).not.toHaveProperty("steps");
      expect(session.getExecutionPlan()?.steps.map((step) => step.status))
        .toEqual(["completed", "completed"]);
    });

    it("rejects an invalid terminal state before changing any plan status", async () => {
      const session = new Session();
      session.beginUserTurn([{ type: "text", text: "Complete the staged task" }]);
      session.updateExecutionPlan({
        steps: [
          { step: "Complete the work", status: "in_progress" },
          { step: "Verify the result", status: "pending" },
        ],
      });
      const tool = createExecutionPlanTool({
        get: () => session.getExecutionPlan(),
        update: (update) => session.updateExecutionPlan(update),
        clear: () => session.clearExecutionPlan(),
      });

      const result = await tool.execute({
        action: "set_status",
        step_id: 1,
        status: "completed",
        finish: "completed",
      }, { state: {} });

      expect(result).toMatchObject({ isError: true });
      expect(JSON.parse(result.content)).toMatchObject({
        error_code: "PLAN_FINISH_REJECTED",
      });
      expect(session.getExecutionPlan()?.steps.map((step) => step.status))
        .toEqual(["in_progress", "pending"]);
    });

    it("accepts a legacy blocked finish marker only when no milestone remains in progress", async () => {
      const session = new Session();
      session.beginUserTurn([{ type: "text", text: "Run until an external approval is required" }]);
      session.updateExecutionPlan({
        steps: [
          { step: "Prepare the request", status: "completed" },
          { step: "Receive external approval", status: "in_progress" },
        ],
      });
      const tool = createExecutionPlanTool({
        get: () => session.getExecutionPlan(),
        update: (update) => session.updateExecutionPlan(update),
        clear: () => session.clearExecutionPlan(),
      });

      const result = await tool.execute({
        action: "set_status",
        step_id: 2,
        status: "blocked",
        finish: "blocked",
      }, { state: {} });

      expect(result.endTurn).toBeUndefined();
      expect(result.synthesizeIfNoText).toBeUndefined();
      expect(JSON.parse(result.content)).toMatchObject({ finish: "blocked" });
      expect(JSON.parse(result.content)).not.toHaveProperty("terminal");
      expect(session.getExecutionPlan()?.steps.map((step) => step.status))
        .toEqual(["completed", "blocked"]);
    });

    it("infers unambiguous narrow actions without weakening payload validation", async () => {
      const session = new Session();
      session.beginUserTurn([{ type: "text", text: "Complete the staged task" }]);
      session.updateExecutionPlan({
        steps: [
          { step: "Inspect the inputs", status: "in_progress" },
          { step: "Verify the result", status: "pending" },
        ],
      });
      const tool = createExecutionPlanTool({
        get: () => session.getExecutionPlan(),
        update: (update) => session.updateExecutionPlan(update),
        clear: () => session.clearExecutionPlan(),
      });
      const context: ToolContext = { state: {} };

      const batch = await tool.execute({
        updates: [
          { step_id: 1, status: "completed" },
          { step_id: 2, status: "in_progress" },
        ],
      }, context);
      expect(batch.isError).toBeUndefined();
      expect(JSON.parse(batch.content)).toMatchObject({
        action: "set_statuses",
        updated_step_ids: [1, 2],
      });

      const status = await tool.execute({ step_id: 2, status: "completed" }, context);
      expect(status.isError).toBeUndefined();
      expect(JSON.parse(status.content)).toMatchObject({
        action: "set_status",
        step_id: 2,
      });

      const appended = await tool.execute({ step: "Publish the result" }, context);
      expect(appended.isError).toBeUndefined();
      expect(JSON.parse(appended.content)).toMatchObject({
        action: "append_step",
        appended_step_id: 3,
      });

      const ambiguous = await tool.execute({
        updates: [{ step_id: 1, status: "blocked" }],
        step_id: 1,
        status: "blocked",
      }, context);
      expect(ambiguous.isError).toBe(true);
      expect(JSON.parse(ambiguous.content)).toMatchObject({
        error_code: "PLAN_ACTION_INVALID",
      });
      expect(session.getExecutionPlan()?.steps[0].status).toBe("completed");
    });

    it("rejects an invalid status batch without partially changing the plan", async () => {
      const session = new Session();
      session.beginUserTurn([{ type: "text", text: "Complete the staged task" }]);
      session.updateExecutionPlan({
        steps: [
          { step: "Inspect the inputs", status: "in_progress" },
          { step: "Verify the evidence", status: "pending" },
          { step: "Publish the result", status: "pending" },
        ],
      });
      const tool = createExecutionPlanTool({
        get: () => session.getExecutionPlan(),
        update: (update) => session.updateExecutionPlan(update),
        clear: () => session.clearExecutionPlan(),
      });
      const context: ToolContext = { state: {} };
      const original = session.getExecutionPlan();
      const invalidBatches = [
        {
          updates: [
            { step_id: 1, status: "completed" },
            { step_id: "step_1", status: "blocked" },
          ],
          errorCode: "PLAN_STEP_ID_DUPLICATE",
        },
        {
          updates: [
            { step_id: 2, status: "in_progress" },
            { step_id: 3, status: "in_progress" },
          ],
          errorCode: "PLAN_MULTIPLE_IN_PROGRESS",
        },
        {
          updates: [
            { step_id: 1, status: "completed" },
            { step_id: 99, status: "blocked" },
          ],
          errorCode: "PLAN_STEP_NOT_FOUND",
        },
        {
          updates: [
            { step_id: 1, status: "completed" },
            { step_id: 2, status: "later" },
          ],
          errorCode: "PLAN_STATUS_INVALID",
        },
      ];

      for (const invalid of invalidBatches) {
        const result = await tool.execute({
          action: "set_statuses",
          updates: invalid.updates,
        }, context);
        expect(result).toMatchObject({ isError: true });
        expect(JSON.parse(result.content)).toMatchObject({
          ok: false,
          error_code: invalid.errorCode,
          current_revision: original?.revision,
        });
        expect(session.getExecutionPlan()).toEqual(original);
      }
    });

    it("acknowledges capacity without failing or rewriting the durable plan", async () => {
      const session = new Session();
      session.beginUserTurn([{ type: "text", text: "Complete the long staged task" }]);
      const initialSteps = Array.from({ length: 12 }, (_, index) => ({
        step: `Milestone ${index + 1}`,
        status: index === 11 ? "in_progress" as const : "completed" as const,
      }));
      session.updateExecutionPlan({ steps: initialSteps });
      const tool = createExecutionPlanTool({
        get: () => session.getExecutionPlan(),
        update: (update) => session.updateExecutionPlan(update),
        clear: () => session.clearExecutionPlan(),
      });
      const context: ToolContext = { state: {} };

      const appended = await tool.execute({
        action: "append_step",
        step: "Thirteenth bookkeeping milestone",
        status: "pending",
      }, context);

      expect(appended.isError).toBeUndefined();
      const appendReceipt = JSON.parse(appended.content);
      expect(appendReceipt).toMatchObject({
        ok: true,
        action: "append_step",
        step_count: 12,
        appended: false,
        capacity_reached: true,
        max_steps: 12,
      });
      expect(appendReceipt).not.toHaveProperty("do_not_retry");
      expect(appendReceipt).not.toHaveProperty("next_action");
      expect(session.getExecutionPlan()?.steps.map((item) => item.step))
        .toEqual(initialSteps.map((item) => item.step));

      const replayedFullPlan = await tool.execute({
        action: "update",
        plan: [
          ...initialSteps,
          { step: "Thirteenth bookkeeping milestone", status: "pending" },
        ],
      }, context);

      expect(replayedFullPlan.isError).toBeUndefined();
      const replayedFullPlanReceipt = JSON.parse(replayedFullPlan.content);
      expect(replayedFullPlanReceipt).toMatchObject({
        ok: true,
        action: "update",
        step_count: 12,
        updated: false,
        capacity_reached: true,
        requested_step_count: 13,
      });
      expect(replayedFullPlanReceipt).not.toHaveProperty("do_not_retry");
      expect(replayedFullPlanReceipt).not.toHaveProperty("next_action");
      expect(session.getExecutionPlan()?.steps.map((item) => item.step))
        .toEqual(initialSteps.map((item) => item.step));

      session.addMessage("user", [{ type: "text", text: "Replace this with a new objective" }]);
      const oversizedNewObjective = await tool.execute({
        action: "update",
        replace_objective: true,
        plan: [
          ...initialSteps,
          { step: "Thirteenth bookkeeping milestone", status: "pending" },
        ],
      }, context);

      expect(oversizedNewObjective.isError).toBe(true);
      expect(JSON.parse(oversizedNewObjective.content)).toMatchObject({
        ok: false,
        error_code: "PLAN_UPDATE_REJECTED",
      });
      expect(oversizedNewObjective.content).toContain("accepts at most 12 steps");
      expect(session.getExecutionPlan()?.steps.map((item) => item.step))
        .toEqual(initialSteps.map((item) => item.step));
    });

    it("normalizes multiple in-progress milestones without spending a retry round", async () => {
      const session = new Session();
      session.beginUserTurn([{ type: "text", text: "Complete the staged task" }]);
      const tool = createExecutionPlanTool({
        get: () => session.getExecutionPlan(),
        update: (update) => session.updateExecutionPlan(update),
        clear: () => session.clearExecutionPlan(),
      });
      const context: ToolContext = { state: {} };

      const result = await tool.execute({
        action: "update",
        plan: [
          { step: "Inspect the inputs", status: "in_progress" },
          { step: "Verify the result", status: "in_progress" },
        ],
      }, context);

      expect(result.isError).toBeUndefined();
      expect(JSON.parse(result.content)).toMatchObject({
        normalized_statuses: [{ step_id: 2, from: "in_progress", to: "pending" }],
      });
      expect(session.getExecutionPlan()?.steps.map((step) => step.status))
        .toEqual(["in_progress", "pending"]);

      const switched = await tool.execute({
        action: "set_status",
        step_id: 2,
        status: "in_progress",
      }, context);

      expect(switched.isError).toBeUndefined();
      expect(JSON.parse(switched.content)).toMatchObject({
        normalized_statuses: [{ step_id: 1, from: "in_progress", to: "pending" }],
      });
      expect(session.getExecutionPlan()?.steps.map((step) => step.status))
        .toEqual(["pending", "in_progress"]);
    });

    it("rejects malformed milestone entries without changing the current plan", async () => {
      const session = new Session();
      session.beginUserTurn([{ type: "text", text: "Complete the staged task" }]);
      session.updateExecutionPlan({
        steps: [
          { step: "Inspect the inputs", status: "completed" },
          { step: "Verify the result", status: "in_progress" },
        ],
      });
      const tool = createExecutionPlanTool({
        get: () => session.getExecutionPlan(),
        update: (update) => session.updateExecutionPlan(update),
        clear: () => session.clearExecutionPlan(),
      });
      const before = session.getExecutionPlan();

      const result = await tool.execute({
        action: "update",
        plan: ["Inspect the inputs", { step: "Verify the result", status: "completed" }],
      }, { state: {} });

      expect(result).toMatchObject({ isError: true });
      expect(JSON.parse(result.content)).toMatchObject({
        ok: false,
        error_code: "PLAN_UPDATE_REJECTED",
        current_revision: before?.revision,
        current_steps: before?.steps,
      });
      expect(result.content).toMatch(/step.*object/i);
      expect(session.getExecutionPlan()).toEqual(before);
    });

    it("accepts detailed milestone labels beyond the model-facing anchor budget", async () => {
      const session = new Session();
      session.beginUserTurn([{ type: "text", text: "Complete the detailed task" }]);
      const tool = createExecutionPlanTool({
        get: () => session.getExecutionPlan(),
        update: (update) => session.updateExecutionPlan(update),
        clear: () => session.clearExecutionPlan(),
      });
      const context: ToolContext = { state: {} };
      const longStep = `Inspect the production evidence and preserve every accepted constraint ${"detail ".repeat(60)}`.trim();
      expect(longStep.length).toBeGreaterThan(180);

      const result = await tool.execute({
        action: "update",
        plan: [{ step: longStep, status: "in_progress" }],
      }, context);

      expect(result.isError).toBeUndefined();
      expect(session.getExecutionPlan()?.steps[0].step).toBe(longStep);
      session.applyActiveCheckpointSummary("Detailed milestone recorded.", session.length - 1);
      const modelView = JSON.stringify(session.getMessagesForModel());
      expect(modelView).toContain("chars omitted");
      expect(modelView.length).toBeLessThan(longStep.length + 2_000);
    });

    it("accepts canonical step_<id> aliases without accepting lookalike labels", async () => {
      const session = new Session();
      session.beginUserTurn([{ type: "text", text: "Complete the staged task" }]);
      session.updateExecutionPlan({
        steps: [{ step: "Complete the work", status: "in_progress" }],
      });
      const tool = createExecutionPlanTool({
        get: () => session.getExecutionPlan(),
        update: (update) => session.updateExecutionPlan(update),
        clear: () => session.clearExecutionPlan(),
      });
      const context: ToolContext = { state: {} };

      const accepted = await tool.execute({
        action: "set_status",
        step_id: "step_1",
        status: "completed",
      }, context);

      expect(accepted.isError).toBeUndefined();
      expect(JSON.parse(accepted.content)).toMatchObject({
        action: "set_status",
        step_id: 1,
      });
      expect(session.getExecutionPlan()?.steps[0].status).toBe("completed");

      for (const stepId of ["step_0", "step_1_extra", "phase_1"]) {
        const rejected = await tool.execute({
          action: "set_status",
          step_id: stepId,
          status: "in_progress",
        }, context);
        expect(rejected).toMatchObject({ isError: true });
        expect(rejected.content).toContain("requires a positive integer step_id");
      }
      expect(session.getExecutionPlan()?.steps[0].status).toBe("completed");
    });
  });

  describe("toToolDefinition", () => {
    it("converts AgentTool to ToolDefinition", () => {
      const tool = defineTool({
        name: "my_tool",
        description: "desc",
        inputSchema: { type: "object" },
        async execute() {
          return { content: "" };
        },
      });

      const def = toToolDefinition(tool);
      expect(def).toEqual({
        name: "my_tool",
        description: "desc",
        inputSchema: { type: "object" },
      });
    });

    it("reuses the normalized definition for an unchanged tool identity", () => {
      let schemaReads = 0;
      const tool = defineTool({
        name: "cached_tool",
        description: "cached description",
        get inputSchema() {
          schemaReads += 1;
          return { type: "object", properties: { value: { type: "string" } } };
        },
        async execute() {
          return { content: "" };
        },
      });

      const first = toToolDefinition(tool);
      const second = toToolDefinition(tool);

      expect(second).toBe(first);
      expect(schemaReads).toBe(1);
    });

    it("refreshes dynamic descriptions while reusing unchanged definitions", () => {
      let description = "Read the current state.";
      let schemaReads = 0;
      const tool: AgentTool = {
        name: "dynamic_token_budget_probe",
        dynamicDescription: true,
        get description() { return description; },
        get inputSchema() { schemaReads++; return { type: "object" }; },
        async execute() { return { content: "" }; },
      };
      const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
      try {
        const first = toToolDefinition(tool);
        expect(toToolDefinition(tool)).toBe(first);
        expect(schemaReads).toBe(1);
        description = "界".repeat(101); // 152 estimated tokens; only 101 characters
        const second = toToolDefinition(tool);
        expect(second).not.toBe(first);
        expect(second.description).toBe(description);
        expect(toToolDefinition(tool)).toBe(second);
        expect(schemaReads).toBe(2);
        expect(warn).toHaveBeenCalledTimes(1);
        expect(warn).toHaveBeenCalledWith("[tool-definitions]",
          "tool definition description exceeds soft budget; sent untruncated",
          expect.objectContaining({ estimatedTokens: 152, softBudgetTokens: 150 }));
      } finally { warn.mockRestore(); }
    });

    it("keeps descriptions intact while warning on soft-budget overruns", () => {
      const longDescription = "Use this tool carefully. " + "detail ".repeat(120);
      const modeDescription = "Choose execution mode. " + "extra ".repeat(80);
      const tool = defineTool({
        name: "schema_tool",
        description: longDescription,
        inputSchema: {
          $schema: "https://json-schema.org/draft/2020-12/schema",
          type: "object",
          required: ["mode"],
          properties: {
            mode: {
              type: "string",
              enum: ["fast", "safe"],
              description: modeDescription,
              examples: ["fast"],
            },
            count: { type: "number", minimum: 1, maximum: 10 },
          },
          examples: [{ mode: "fast" }],
        },
        async execute() {
          return { content: "" };
        },
      });

      const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
      try {
        const def = toToolDefinition(tool);
        expect(def.description).toBe(longDescription.trim());
        expect(def.inputSchema).toMatchObject({
          type: "object",
          required: ["mode"],
          properties: {
            mode: { type: "string", enum: ["fast", "safe"] },
            count: { type: "number", minimum: 1, maximum: 10 },
          },
        });
        expect(def.inputSchema).not.toHaveProperty("$schema");
        expect(def.inputSchema).not.toHaveProperty("examples");
        const modeSchema = (def.inputSchema.properties as Record<string, Record<string, unknown>>).mode;
        expect(modeSchema.description).toBe(modeDescription.trim());
        expect(modeSchema).not.toHaveProperty("examples");
        expect(warn).toHaveBeenCalledWith(
          "[tool-definitions]",
          "tool definition description exceeds soft budget; sent untruncated",
          expect.objectContaining({
            tool: "schema_tool",
            field: "tool description",
            softBudgetTokens: 150,
          }),
        );
        expect(warn).toHaveBeenCalledWith(
          "[tool-definitions]",
          "tool definition description exceeds soft budget; sent untruncated",
          expect.objectContaining({
            tool: "schema_tool",
            field: "schema description at /inputSchema/properties/mode",
            softBudgetTokens: 80,
          }),
        );
      } finally {
        warn.mockRestore();
      }
    });
  });

  describe("getBuiltinTools", () => {
    it("returns an array of tools", () => {
      const tools = getBuiltinTools();
      expect(tools.length).toBeGreaterThan(0);

      const names = tools.map((t) => t.name);
      expect(names).toContain("read_file");
      expect(names).toContain("read_files");
      expect(names).toContain("write_file");
      expect(names).toContain("apply_patch");
      expect(names).toContain("bash");
      expect(names).toContain("process_session");
      expect(names).not.toContain("process_start");
      expect(names).not.toContain("process_read");
      expect(names).not.toContain("process_write");
      expect(names).not.toContain("process_stop");
      expect(names).toContain("list_files");
    });
  });

  describe("write_file tool", () => {
    it("creates parent directories and writes UTF-8 content", async () => {
      const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "core-write-file-test-"));
      try {
        const writeFile = getBuiltinTools().find((tool) => tool.name === "write_file")!;
        const result = await writeFile.execute(
          { path: "nested/output.txt", content: "Windows + macOS: 你好" },
          { workingDir: tmpDir, state: {} },
        );

        const output = path.join(tmpDir, "nested", "output.txt");
        expect(result.isError).toBeUndefined();
        expect(result.content).toContain(path.resolve(output));
        await expect(fs.readFile(output, "utf8")).resolves.toBe("Windows + macOS: 你好");
      } finally {
        await fs.rm(tmpDir, { recursive: true, force: true });
      }
    });

    it("returns a tool error when the target cannot be written", async () => {
      const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "core-write-file-error-test-"));
      try {
        const parentFile = path.join(tmpDir, "not-a-directory");
        await fs.writeFile(parentFile, "occupied");
        const writeFile = getBuiltinTools().find((tool) => tool.name === "write_file")!;
        const result = await writeFile.execute(
          { path: path.join(parentFile, "output.txt"), content: "nope" },
          { workingDir: tmpDir, state: {} },
        );

        expect(result.isError).toBe(true);
        expect(result.content).toContain("Error writing file:");
      } finally {
        await fs.rm(tmpDir, { recursive: true, force: true });
      }
    });
  });

  describe("list_files tool", () => {
    it("lists files and directories using a platform-neutral result format", async () => {
      const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "core-list-files-test-"));
      try {
        await fs.mkdir(path.join(tmpDir, "folder"));
        await fs.writeFile(path.join(tmpDir, "file.txt"), "content");
        const listFiles = getBuiltinTools().find((tool) => tool.name === "list_files")!;
        const result = await listFiles.execute({}, { workingDir: tmpDir, state: {} });

        expect(result.isError).toBeUndefined();
        expect(result.content.split("\n").sort()).toEqual(["d folder", "f file.txt"]);
      } finally {
        await fs.rm(tmpDir, { recursive: true, force: true });
      }
    });

    it("returns a tool error for a missing directory", async () => {
      const listFiles = getBuiltinTools().find((tool) => tool.name === "list_files")!;
      const result = await listFiles.execute(
        { path: path.join(os.tmpdir(), `missing-list-dir-${Date.now()}`) },
        { state: {} },
      );

      expect(result.isError).toBe(true);
      expect(result.content).toContain("Error listing files:");
    });
  });

  describe("web_fetch tool", () => {
    it("preserves decision-relevant README sections beyond a long prefix", () => {
      const readme = [
        "# Example",
        "Local-first desktop assistant.",
        "",
        "## Community",
        "x".repeat(12_000),
        "",
        "## Installation",
        "Install with the signed desktop package.",
        "",
        "## License",
        "Licensed under Apache-2.0.",
      ].join("\n");
      const compacted = compactGitHubReadme(readme);
      expect(compacted.length).toBeLessThanOrEqual(4_500);
      expect(compacted).toContain("Local-first desktop assistant.");
      expect(compacted).toContain("Install with the signed desktop package.");
      expect(compacted).toContain("Licensed under Apache-2.0.");
      // The receipt says the long section was shortened rather than implying
      // the README was shown whole.
      expect(compacted).toContain("[README snapshot kept 3 of 3 sections after the opening (1 shortened)");
    });

    it("keeps a long list README in reading order and ignores look-alike priority titles", () => {
      const filler = Array.from({ length: 30 }, (_, index) => (
        `## Topic ${index + 1}\n${`Topic ${index + 1} background text. `.repeat(8)}`
      ));
      const readme = [
        "# Toolkit",
        "Opening paragraph.",
        "",
        ...filler,
        "## Memory-guided manipulation\nMEMORY_FEATURE_TEXT describes an agent feature.",
        "## Programming guide\nPROGRAMMING_GUIDE_TEXT explains the API.",
        "## RAM requirements\nRAM_REQUIREMENT_TEXT: 16 GB.",
        "## License\nLICENSE_TEXT: MIT.",
      ].join("\n");
      const compacted = compactGitHubReadme(readme);
      expect(compacted.length).toBeLessThanOrEqual(4_500);
      expect(compacted).toContain("Topic 1 background text.");
      expect(compacted).not.toContain("Topic 30 background text.");
      // Hardware and license facts are still pulled forward from the end...
      expect(compacted).toContain("RAM_REQUIREMENT_TEXT");
      expect(compacted).toContain("LICENSE_TEXT");
      // ...but a feature title containing "Memory" and a word containing "ram"
      // are ordinary sections, not requirements.
      expect(compacted).not.toContain("MEMORY_FEATURE_TEXT");
      expect(compacted).not.toContain("PROGRAMMING_GUIDE_TEXT");
      // Omitted sections are named up to a bound, then counted.
      expect(compacted).toMatch(/Omitted sections: Topic \d+ \|[^\]]*\(\+\d+ more\)\.\]$/);
    });

    it("does not apply the former 50K default truncation before Result Store handling", async () => {
      const body = "x".repeat(60_000);
      vi.stubGlobal("fetch", vi.fn(async () => new Response(body, {
        status: 200,
        headers: { "content-type": "text/plain; charset=utf-8" },
      })));
      try {
        const webFetch = getBuiltinTools().find((tool) => tool.name === "web_fetch")!;
        const result = await webFetch.execute({ url: "https://example.test/large.txt" }, { state: {} });
        expect(result.content).toBe(body);
      } finally {
        vi.unstubAllGlobals();
      }
    });

    it("still honors an explicit maxChars request", async () => {
      vi.stubGlobal("fetch", vi.fn(async () => new Response("abcdef", {
        status: 200,
        headers: { "content-type": "text/plain; charset=utf-8" },
      })));
      try {
        const webFetch = getBuiltinTools().find((tool) => tool.name === "web_fetch")!;
        const result = await webFetch.execute(
          { url: "https://example.test/limited.txt", maxChars: 3 },
          { state: {} },
        );
        expect(result.content).toContain("abc");
        expect(result.content).toContain("explicitly requested maxChars");
      } finally {
        vi.unstubAllGlobals();
      }
    });

    it("adds access and embedded document dates to HTML without another request", async () => {
      const fetchMock = vi.fn(async () => new Response(
        '<html><head><title>Project</title></head><body>'
        + '<relative-time datetime="2026-07-27T10:30:00Z">yesterday</relative-time>'
        + '<time datetime="2026-07-20T09:00:00Z">last week</time>'
        + "</body></html>",
        {
          status: 200,
          headers: {
            "content-type": "text/html; charset=utf-8",
            "last-modified": "Mon, 27 Jul 2026 10:30:00 GMT",
          },
        },
      ));
      vi.stubGlobal("fetch", fetchMock);
      try {
        const webFetch = getBuiltinTools().find((tool) => tool.name === "web_fetch")!;
        const result = await webFetch.execute({ url: "https://example.test/project" }, { state: {} });
        expect(result.content).toContain("Title: Project");
        expect(result.content).toMatch(/Accessed at: \d{4}-\d{2}-\d{2}T/);
        expect(result.content).toContain("HTTP Last-Modified: Mon, 27 Jul 2026 10:30:00 GMT");
        expect(result.content).toContain(
          "Embedded document dates (newest first): "
          + "2026-07-27T10:30:00.000Z, 2026-07-20T09:00:00.000Z",
        );
        expect(fetchMock).toHaveBeenCalledTimes(1);
      } finally {
        vi.unstubAllGlobals();
      }
    });

    it("reuses a successful identical fetch within one run state", async () => {
      const fetchMock = vi.fn(async () => new Response("stable body", {
        status: 200,
        headers: { "content-type": "text/plain; charset=utf-8" },
      }));
      vi.stubGlobal("fetch", fetchMock);
      try {
        const webFetch = getBuiltinTools().find((tool) => tool.name === "web_fetch")!;
        const ctx: ToolContext = { state: {} };
        const [first, second] = await Promise.all([
          webFetch.execute({ url: "https://example.test/cached", maxChars: 8_000 }, ctx),
          webFetch.execute({ url: "https://example.test/cached", maxChars: 8_000 }, ctx),
        ]);
        expect(first.content).toBe("stable body");
        expect(second.content).toBe("stable body");
        expect(fetchMock).toHaveBeenCalledTimes(1);
      } finally {
        vi.unstubAllGlobals();
      }
    });

    it("reuses the complete response when only maxChars changes", async () => {
      const fetchMock = vi.fn(async () => new Response("abcdefghij", {
        status: 200,
        headers: { "content-type": "text/plain; charset=utf-8" },
      }));
      vi.stubGlobal("fetch", fetchMock);
      try {
        const webFetch = getBuiltinTools().find((tool) => tool.name === "web_fetch")!;
        const ctx: ToolContext = { state: {} };
        const short = await webFetch.execute(
          { url: "https://example.test/variable-limit", maxChars: 3 },
          ctx,
        );
        const longer = await webFetch.execute(
          { url: "https://example.test/variable-limit", maxChars: 8 },
          ctx,
        );
        expect(short.content).toContain("abc");
        expect(short.content).not.toContain("defgh");
        expect(longer.content).toContain("abcdefgh");
        expect(fetchMock).toHaveBeenCalledTimes(1);
      } finally {
        vi.unstubAllGlobals();
      }
    });

    it("returns a structured GitHub repository snapshot and caches its default API aliases", async () => {
      const metadata = {
        full_name: "example/project",
        description: "Example local-first project",
        homepage: "https://example.test",
        default_branch: "main",
        created_at: "2024-01-01T00:00:00Z",
        updated_at: "2026-07-27T10:00:00Z",
        pushed_at: "2026-07-27T09:30:00Z",
        archived: false,
        fork: false,
        stargazers_count: 123,
        forks_count: 7,
        open_issues_count: 4,
        topics: ["local-first", "desktop"],
        license: {
          name: "Apache License 2.0",
          spdx_id: "Apache-2.0",
          url: "https://api.github.com/licenses/apache-2.0",
        },
      };
      const fetchMock = vi.fn(async (input: string | URL | Request) => {
        const requestUrl = typeof input === "string"
          ? input
          : input instanceof URL
            ? input.toString()
            : input.url;
        if (requestUrl.endsWith("/readme")) {
          return new Response("# Project\nRuns locally on Windows, macOS, and Linux.", {
            status: 200,
            headers: { "content-type": "text/plain; charset=utf-8" },
          });
        }
        if (requestUrl === "https://api.github.com/repos/example/project") {
          return new Response(JSON.stringify(metadata), {
            status: 200,
            headers: { "content-type": "application/json; charset=utf-8" },
          });
        }
        throw new Error(`unexpected request: ${requestUrl}`);
      });
      vi.stubGlobal("fetch", fetchMock);
      try {
        const webFetch = getBuiltinTools().find((tool) => tool.name === "web_fetch")!;
        const runScopedLedger = new Map<string, unknown>();
        const ctx: ToolContext = { state: { runScopedLedger } };
        const snapshot = await webFetch.execute(
          { url: "https://github.com/example/project", maxChars: 20_000 },
          ctx,
        );
        const readmeAlias = await webFetch.execute(
          { url: "https://api.github.com/repos/example/project/readme" },
          ctx,
        );
        const metadataAlias = await webFetch.execute(
          { url: "https://api.github.com/repos/example/project" },
          ctx,
        );

        expect(snapshot.isError).toBeUndefined();
        expect(snapshot.content).toContain("Source type: structured GitHub repository snapshot");
        expect(snapshot.content).toContain("- License SPDX ID: Apache-2.0");
        expect(snapshot.content).toContain("- Pushed at: 2026-07-27T09:30:00Z");
        expect(snapshot.content).not.toContain("Decision evidence candidates");
        expect(snapshot.content).not.toContain("field=os");
        expect(snapshot.content).toContain("Runs locally on Windows, macOS, and Linux.");
        expect(readmeAlias.content).toContain("GITHUB_REPOSITORY_SNAPSHOT_CACHE_HIT");
        expect(metadataAlias.content).toContain("GITHUB_REPOSITORY_SNAPSHOT_CACHE_HIT");
        expect(fetchMock).toHaveBeenCalledTimes(2);
        expect(fetchMock).not.toHaveBeenCalledWith(
          "https://github.com/example/project",
          expect.anything(),
        );
      } finally {
        vi.unstubAllGlobals();
      }
    });

    it("reuses a successful fetch after ToolContext state is rebuilt", async () => {
      const fetchMock = vi.fn(async () => new Response("stable across compaction", {
        status: 200,
        headers: { "content-type": "text/plain; charset=utf-8" },
      }));
      vi.stubGlobal("fetch", fetchMock);
      try {
        const webFetch = getBuiltinTools().find((tool) => tool.name === "web_fetch")!;
        const runScopedLedger = new Map<string, unknown>();
        const first = await webFetch.execute(
          { url: "https://example.test/compacted", maxChars: 8_000 },
          { state: { runScopedLedger } },
        );
        const second = await webFetch.execute(
          { url: "https://example.test/compacted", maxChars: 8_000 },
          { state: { runScopedLedger } },
        );
        expect(first.content).toBe("stable across compaction");
        expect(second.content).toBe("stable across compaction");
        expect(fetchMock).toHaveBeenCalledTimes(1);
      } finally {
        vi.unstubAllGlobals();
      }
    });

    it("does not re-inject the full cached page after context compaction", async () => {
      const body = `Title-sized recovery text\n${"page body ".repeat(1_000)}`;
      const fetchMock = vi.fn(async () => new Response(body, {
        status: 200,
        headers: { "content-type": "text/plain; charset=utf-8" },
      }));
      vi.stubGlobal("fetch", fetchMock);
      try {
        const webFetch = getBuiltinTools().find((tool) => tool.name === "web_fetch")!;
        const runScopedLedger = new Map<string, unknown>();
        const first = await webFetch.execute(
          { url: "https://example.test/compacted-replay", maxChars: 20_000 },
          { state: { runScopedLedger, toolResultReadLedger: { epoch: 0 } } },
        );
        const second = await webFetch.execute(
          { url: "https://example.test/compacted-replay#after-checkpoint", maxChars: 12_000 },
          { state: { runScopedLedger, toolResultReadLedger: { epoch: 1 } } },
        );
        expect(first.content).toBe(body);
        expect(second.content).toContain("WEB_FETCH_RUN_CACHE_HIT");
        expect(second.content).toContain("normalized URL already succeeded");
        expect(second.content).toContain("full page is intentionally not re-injected");
        expect(second.content).not.toContain("page body page body");
        expect(fetchMock).toHaveBeenCalledTimes(1);
      } finally {
        vi.unstubAllGlobals();
      }
    });

    it("allows one retry for a transient failure, then suppresses the same URL", async () => {
      const fetchMock = vi.fn(async () => new Response("unavailable", { status: 503 }));
      vi.stubGlobal("fetch", fetchMock);
      try {
        const webFetch = getBuiltinTools().find((tool) => tool.name === "web_fetch")!;
        const ctx: ToolContext = { state: {} };
        const first = await webFetch.execute({ url: "https://example.test/retryable" }, ctx);
        const second = await webFetch.execute({ url: "https://example.test/retryable" }, ctx);
        const third = await webFetch.execute({ url: "https://example.test/retryable" }, ctx);
        expect(fetchMock).toHaveBeenCalledTimes(2);
        expect(first.content).not.toContain("E_WEB_FETCH_RETRY_LIMIT");
        expect(second.content).toContain("E_WEB_FETCH_RETRY_LIMIT");
        expect(third.content).toContain("E_WEB_FETCH_NONRETRYABLE_CACHE_HIT");
      } finally {
        vi.unstubAllGlobals();
      }
    });

    it("does not retry a permanently missing URL but allows another URL", async () => {
      const fetchMock = vi.fn(async (input: string | URL | Request) => {
        const requestUrl = typeof input === "string"
          ? input
          : input instanceof URL
            ? input.toString()
            : input.url;
        return requestUrl.endsWith("/missing")
          ? new Response("missing", { status: 404, statusText: "Not Found" })
          : new Response("useful evidence", {
              status: 200,
              headers: { "content-type": "text/plain; charset=utf-8" },
            });
      });
      vi.stubGlobal("fetch", fetchMock);
      try {
        const webFetch = getBuiltinTools().find((tool) => tool.name === "web_fetch")!;
        const ctx: ToolContext = { state: {} };
        const missing = await webFetch.execute({ url: "https://example.test/missing" }, ctx);
        const repeated = await webFetch.execute({ url: "https://example.test/missing" }, ctx);
        const useful = await webFetch.execute({ url: "https://example.test/useful" }, ctx);
        expect(missing.isError).toBe(true);
        expect(repeated.content).toContain("E_WEB_FETCH_NONRETRYABLE_CACHE_HIT");
        expect(useful.content).toBe("useful evidence");
        expect(fetchMock).toHaveBeenCalledTimes(2);
      } finally {
        vi.unstubAllGlobals();
      }
    });

    it("opens a run-scoped origin circuit after repeated access failures", async () => {
      const fetchMock = vi.fn(async () => new Response("forbidden", {
        status: 403,
        statusText: "Forbidden",
      }));
      vi.stubGlobal("fetch", fetchMock);
      try {
        const webFetch = getBuiltinTools().find((tool) => tool.name === "web_fetch")!;
        const runScopedLedger = new Map<string, unknown>();
        const first = await webFetch.execute(
          { url: "https://blocked.example.test/one" },
          { state: { runScopedLedger } },
        );
        const second = await webFetch.execute(
          { url: "https://blocked.example.test/two" },
          { state: { runScopedLedger } },
        );
        const third = await webFetch.execute(
          { url: "https://blocked.example.test/three" },
          { state: { runScopedLedger } },
        );
        expect(first.isError).toBe(true);
        expect(first.content).not.toContain("E_WEB_FETCH_ORIGIN_AUTH_CIRCUIT_OPENED");
        expect(second.content).toContain("E_WEB_FETCH_ORIGIN_AUTH_CIRCUIT_OPENED");
        expect(third.content).toContain("E_WEB_FETCH_ORIGIN_AUTH_BLOCKED");
        expect(fetchMock).toHaveBeenCalledTimes(2);
      } finally {
        vi.unstubAllGlobals();
      }
    });

    it("does not impose a total-call ceiling on distinct successful sources", async () => {
      const fetchMock = vi.fn(async (input: string | URL | Request) => {
        const requestUrl = typeof input === "string"
          ? input
          : input instanceof URL
            ? input.toString()
            : input.url;
        return new Response(`evidence for ${requestUrl}`, {
          status: 200,
          headers: { "content-type": "text/plain; charset=utf-8" },
        });
      });
      vi.stubGlobal("fetch", fetchMock);
      try {
        const webFetch = getBuiltinTools().find((tool) => tool.name === "web_fetch")!;
        const runScopedLedger = new Map<string, unknown>();
        const results = [];
        for (let index = 0; index < 20; index++) {
          results.push(await webFetch.execute(
            { url: `https://valuable.example.test/source-${index}` },
            { state: { runScopedLedger } },
          ));
        }
        expect(results.every((result) => !result.isError)).toBe(true);
        expect(fetchMock).toHaveBeenCalledTimes(20);
      } finally {
        vi.unstubAllGlobals();
      }
    });

    it("returns a complete body beyond the former 2MB transport cap", async () => {
      const body = "x".repeat(2_100_000);
      vi.stubGlobal("fetch", vi.fn(async () => new Response(body, {
        status: 200,
        headers: { "content-type": "text/plain; charset=utf-8" },
      })));
      try {
        const webFetch = getBuiltinTools().find((tool) => tool.name === "web_fetch")!;
        const result = await webFetch.execute({ url: "https://example.test/large-body.txt" }, { state: {} });
        expect(result.isError).toBeUndefined();
        expect(result.content).toBe(body);
      } finally {
        vi.unstubAllGlobals();
      }
    });

    it("rejects a declared body above the hard response limit without a partial page", async () => {
      vi.stubGlobal("fetch", vi.fn(async () => new Response("UNIQUE_RESPONSE_FRAGMENT", {
        status: 200,
        headers: {
          "content-type": "text/plain; charset=utf-8",
          "content-length": String(MAX_WEB_FETCH_RESPONSE_BYTES + 1),
        },
      })));
      try {
        const webFetch = getBuiltinTools().find((tool) => tool.name === "web_fetch")!;
        const result = await webFetch.execute({ url: "https://example.test/too-large.txt" }, { state: {} });
        expect(result.isError).toBe(true);
        expect(result.content).toContain("E_FETCH_RESPONSE_TOO_LARGE");
        expect(result.content).toContain("No partial page was returned");
        expect(result.content).not.toContain("UNIQUE_RESPONSE_FRAGMENT");
      } finally {
        vi.unstubAllGlobals();
      }
    });

    it("rejects an undeclared streaming body that crosses the hard response limit", async () => {
      const stream = new ReadableStream<Uint8Array>({
        start(controller) {
          for (let i = 0; i < 17; i++) controller.enqueue(new Uint8Array(1024 * 1024));
          controller.close();
        },
      });
      vi.stubGlobal("fetch", vi.fn(async () => new Response(stream, {
        status: 200,
        headers: { "content-type": "text/plain; charset=utf-8" },
      })));
      try {
        const webFetch = getBuiltinTools().find((tool) => tool.name === "web_fetch")!;
        const result = await webFetch.execute({ url: "https://example.test/stream-too-large.txt" }, { state: {} });
        expect(result.isError).toBe(true);
        expect(result.content).toContain("E_FETCH_RESPONSE_TOO_LARGE");
        expect(result.content).toContain("while streaming");
        expect(result.content).toContain("No partial page was returned");
      } finally {
        vi.unstubAllGlobals();
      }
    });

    describe("long sources", () => {
      // A release page whose decisive results sit far below a long opening, the
      // shape that a 12,000-character first read used to cut off unannounced.
      const paragraphs = Array.from(
        { length: 40 },
        (_, index) => `<p>Paragraph ${index}: ${"background evidence ".repeat(30)}end.</p>`,
      ).join("");
      const releaseHtml = "<html><head><title>Model release</title></head><body>"
        + `<h2>Overview</h2>${paragraphs}`
        + "<h2>Benchmark results</h2><p>BENCHMARK_TABLE_ROW 95.9 versus 83.3.</p>"
        + "<h2>Limitations</h2><p>Known gaps remain.</p></body></html>";

      function stubRelease() {
        const fetchMock = vi.fn(async () => new Response(releaseHtml, {
          status: 200,
          headers: { "content-type": "text/html; charset=utf-8" },
        }));
        vi.stubGlobal("fetch", fetchMock);
        return fetchMock;
      }

      function windowBody(content: string): { start: number; end: number; total: number; body: string } {
        const match = /^Window: characters (\d+)-(\d+) of (\d+) /m.exec(content);
        if (!match) throw new Error(`no window line in: ${content.slice(0, 200)}`);
        const [start, end, total] = match.slice(1).map(Number);
        const bodyStart = content.indexOf("\n\n", match.index) + 2;
        return { start, end, total, body: content.slice(bodyStart, bodyStart + end - start) };
      }

      it("reports the unread remainder of a truncated page and continues it from the run cache", async () => {
        const fetchMock = stubRelease();
        try {
          const webFetch = getBuiltinTools().find((tool) => tool.name === "web_fetch")!;
          const ctx: ToolContext = { state: { runScopedLedger: new Map<string, unknown>() } };
          const first = await webFetch.execute({ url: "https://example.test/release", maxChars: 4_000 }, ctx);
          const full = (await webFetch.execute({ url: "https://example.test/release" }, ctx)).content;
          expect(full).toContain("BENCHMARK_TABLE_ROW");
          expect(first.isError).toBeUndefined();
          expect(first.content.startsWith(full.slice(0, 4_000))).toBe(true);
          expect(first.content).not.toContain("BENCHMARK_TABLE_ROW");
          expect(first.content).toContain("explicitly requested maxChars");
          expect(first.content).toContain(`characters 0-4000 of ${full.length} shown; ${full.length - 4_000} more characters remain`);
          expect(first.content).toContain('"offset": 4000');
          expect(first.content).toContain("Headings after this point (detected): Benchmark results | Limitations.");
          expect(first.content).not.toMatch(/detected\):[^\n]*Overview/);

          // Following the reported offsets reconstructs the page exactly, and
          // the last window carries the results the first read could not show.
          let reconstructed = first.content.slice(0, 4_000);
          let next = 4_000;
          let last = first;
          while (next < full.length) {
            last = await webFetch.execute({ url: "https://example.test/release", maxChars: 4_000, offset: next }, ctx);
            const window = windowBody(last.content);
            expect(window.start).toBe(next);
            expect(window.total).toBe(full.length);
            expect(last.content).toContain("URL: https://example.test/release");
            expect(last.content).toContain("Title: Model release");
            reconstructed += window.body;
            next = window.end;
          }
          expect(reconstructed).toBe(full);
          expect(last.content).toContain("BENCHMARK_TABLE_ROW");
          expect(last.content).toContain(`end of the extracted content at character ${full.length}`);
          expect(fetchMock).toHaveBeenCalledTimes(1);
        } finally {
          vi.unstubAllGlobals();
        }
      });

      it("continues past what was read after compaction without re-injecting earlier text", async () => {
        const fetchMock = stubRelease();
        try {
          const webFetch = getBuiltinTools().find((tool) => tool.name === "web_fetch")!;
          const runScopedLedger = new Map<string, unknown>();
          const before = { state: { runScopedLedger, toolResultReadLedger: { epoch: 0 } } };
          const after = { state: { runScopedLedger, toolResultReadLedger: { epoch: 1 } } };
          await webFetch.execute({ url: "https://example.test/release", maxChars: 4_000 }, before);

          const replay = await webFetch.execute({ url: "https://example.test/release", maxChars: 4_000 }, after);
          const reread = await webFetch.execute({ url: "https://example.test/release", maxChars: 4_000, offset: 1_000 }, after);
          const onward = await webFetch.execute({ url: "https://example.test/release", maxChars: 4_000, offset: 4_000 }, after);

          for (const result of [replay, reread]) {
            expect(result.content).toContain("WEB_FETCH_RUN_CACHE_HIT");
            expect(result.content).not.toContain("Paragraph 3:");
            expect(result.content).toMatch(/have not been read in order yet; to continue, call web_fetch with "offset": 4000/);
          }
          expect(onward.isError).toBeUndefined();
          expect(windowBody(onward.content).start).toBe(4_000);
          expect(onward.content).not.toContain("WEB_FETCH_RUN_CACHE_HIT");
          expect(fetchMock).toHaveBeenCalledTimes(1);
        } finally {
          vi.unstubAllGlobals();
        }
      });

      it("starts a cold fetch at the requested window", async () => {
        const fetchMock = stubRelease();
        try {
          const webFetch = getBuiltinTools().find((tool) => tool.name === "web_fetch")!;
          const ctx: ToolContext = { state: {} };
          const window = await webFetch.execute({ url: "https://example.test/release", maxChars: 50, offset: 100 }, ctx);
          const full = (await webFetch.execute({ url: "https://example.test/release" }, ctx)).content;
          const parsed = windowBody(window.content);
          expect(parsed).toMatchObject({ start: 100, end: 150, total: full.length });
          expect(parsed.body).toBe(full.slice(100, 150));
          expect(fetchMock).toHaveBeenCalledTimes(1);
        } finally {
          vi.unstubAllGlobals();
        }
      });

      it.each([-1, 1.5, "later"])("rejects offset %p before any request", async (offset) => {
        const fetchMock = stubRelease();
        try {
          const webFetch = getBuiltinTools().find((tool) => tool.name === "web_fetch")!;
          const result = await webFetch.execute({ url: "https://example.test/release", offset }, { state: {} });
          expect(result.isError).toBe(true);
          expect(result.content).toContain("offset must be a non-negative integer");
          expect(fetchMock).not.toHaveBeenCalled();
        } finally {
          vi.unstubAllGlobals();
        }
      });

      it("names the content length when an offset is past the end", async () => {
        const fetchMock = stubRelease();
        try {
          const webFetch = getBuiltinTools().find((tool) => tool.name === "web_fetch")!;
          const ctx: ToolContext = { state: {} };
          const full = (await webFetch.execute({ url: "https://example.test/release" }, ctx)).content;
          const result = await webFetch.execute(
            { url: "https://example.test/release", maxChars: 4_000, offset: full.length + 10 },
            ctx,
          );
          expect(result.isError).toBe(true);
          expect(result.content).toContain("E_WEB_FETCH_OFFSET_OUT_OF_RANGE");
          expect(result.content).toContain(`(${full.length} characters)`);
          expect(fetchMock).toHaveBeenCalledTimes(1);
        } finally {
          vi.unstubAllGlobals();
        }
      });
    });

    describe("binary responses", () => {
      const pdfBytes = new Uint8Array([
        ...Buffer.from("%PDF-1.7\n%"), 0xe2, 0xe3, 0xcf, 0xd3,
        ...Buffer.from("\n5 0 obj\n<< /Filter /FlateDecode >>\nstream\n"), 0x78, 0x9c, 0x00, 0xff, 0x10,
      ]);

      it.each([
        ["application/pdf", "a PDF document"],
        ["application/octet-stream", "a PDF document"],
      ])("fails a PDF served as %s instead of returning decoded bytes", async (contentType, kind) => {
        const fetchMock = vi.fn(async () => new Response(pdfBytes, {
          status: 200,
          headers: { "content-type": contentType },
        }));
        vi.stubGlobal("fetch", fetchMock);
        try {
          const webFetch = getBuiltinTools().find((tool) => tool.name === "web_fetch")!;
          const ctx: ToolContext = { state: {} };
          const first = await webFetch.execute({ url: "https://example.test/card.pdf", maxChars: 12_000 }, ctx);
          const repeated = await webFetch.execute({ url: "https://example.test/card.pdf", maxChars: 12_000 }, ctx);
          expect(first.isError).toBe(true);
          expect(first.content).toContain("E_WEB_FETCH_BINARY_CONTENT");
          expect(first.content).toContain(`returned ${kind}`);
          expect(first.content).not.toContain("FlateDecode");
          expect(repeated.content).toContain("E_WEB_FETCH_NONRETRYABLE_CACHE_HIT");
          expect(fetchMock).toHaveBeenCalledTimes(1);
        } finally {
          vi.unstubAllGlobals();
        }
      });

      it("fails an image response", async () => {
        vi.stubGlobal("fetch", vi.fn(async () => new Response(new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a]), {
          status: 200,
          headers: { "content-type": "image/png" },
        })));
        try {
          const webFetch = getBuiltinTools().find((tool) => tool.name === "web_fetch")!;
          const result = await webFetch.execute({ url: "https://example.test/chart.png" }, { state: {} });
          expect(result.isError).toBe(true);
          expect(result.content).toContain("a binary file (image/png)");
        } finally {
          vi.unstubAllGlobals();
        }
      });

      it.each([
        ["an HTML page that mentions PDFs", "text/html; charset=utf-8", "<html><body><p>Download the %PDF-1.7 spec as application/pdf.</p></body></html>", "Download the %PDF-1.7 spec"],
        ["text served as an octet stream", "application/octet-stream", "# Notes\nPlain markdown served without a text type.", "Plain markdown served"],
        ["a text page whose charset was guessed wrong", "text/html", `<html><body><p>${"\uFFFD".repeat(400)} readable tail</p></body></html>`, "readable tail"],
      ])("keeps %s as readable text", async (_label, contentType, body, expected) => {
        vi.stubGlobal("fetch", vi.fn(async () => new Response(body, {
          status: 200,
          headers: { "content-type": contentType },
        })));
        try {
          const webFetch = getBuiltinTools().find((tool) => tool.name === "web_fetch")!;
          const result = await webFetch.execute({ url: "https://example.test/text" }, { state: {} });
          expect(result.isError).toBeUndefined();
          expect(result.content).toContain(expected);
        } finally {
          vi.unstubAllGlobals();
        }
      });
    });

    describe("GitHub list README", () => {
      const listReadme = [
        "# Awesome Robot Demos",
        "Curated robot workflows.",
        "",
        "## Contents",
        "- Zero-shot control",
        "",
        "## Zero-shot Control",
        "",
        "### Deploy in Simulation",
        "",
        ...Array.from({ length: 37 }, (_, index) => {
          const number = index + 1;
          const title = number === 23 ? "Memory-guided agentic manipulation" : `Robot demo number ${number}`;
          return `#### Case ${number}: ${title}\n\n**Source:** Lab ${number}\n\n${`Case ${number} describes its demonstration. `.repeat(14)}`;
        }),
      ].join("\n");

      function stubRepository() {
        const fetchMock = vi.fn(async (input: string | URL | Request) => {
          const requestUrl = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
          if (requestUrl.endsWith("/readme")) {
            return new Response(listReadme, { status: 200, headers: { "content-type": "text/plain; charset=utf-8" } });
          }
          return new Response(JSON.stringify({ full_name: "example/awesome", description: "Robot demos" }), {
            status: 200,
            headers: { "content-type": "application/json; charset=utf-8" },
          });
        });
        vi.stubGlobal("fetch", fetchMock);
        return fetchMock;
      }

      it("keeps the first entries, names the omitted ones, and continues the README by offset", async () => {
        const fetchMock = stubRepository();
        try {
          const webFetch = getBuiltinTools().find((tool) => tool.name === "web_fetch")!;
          const ctx: ToolContext = { state: { runScopedLedger: new Map<string, unknown>() } };
          const view = await webFetch.execute({ url: "https://github.com/example/awesome", maxChars: 12_000 }, ctx);
          expect(view.isError).toBeUndefined();
          expect(view.content.length).toBeLessThanOrEqual(12_000);
          expect(view.content).toContain("Case 1 describes its demonstration.");
          // A list entry is not promoted just because its title says "Memory".
          expect(view.content).not.toContain("Case 23 describes");
          const receipt = /README snapshot kept (\d+) of 40 sections after the opening/.exec(view.content);
          expect(receipt).not.toBeNull();
          const omitted = /Omitted sections: Case (\d+): Robot demo number \1 \|/.exec(view.content);
          expect(omitted).not.toBeNull();
          const firstOmitted = Number(omitted![1]);
          expect(view.content).toContain(`Case ${firstOmitted - 1} describes its demonstration.`);
          const offset = Number(/Continue the README in order with "offset": (\d+)/.exec(view.content)?.[1]);

          const next = await webFetch.execute(
            { url: "https://github.com/example/awesome", maxChars: 4_000, offset },
            ctx,
          );
          const body = next.content.slice(next.content.indexOf("\n\n") + 2);
          expect(next.content).toContain("URL: https://github.com/example/awesome");
          expect(body.startsWith(`#### Case ${firstOmitted}: Robot demo number ${firstOmitted}`)).toBe(true);
          // Metadata and README requests only; windows reuse the cached snapshot.
          expect(fetchMock).toHaveBeenCalledTimes(2);
        } finally {
          vi.unstubAllGlobals();
        }
      });

      it("keeps the default README budget when maxChars is omitted", async () => {
        stubRepository();
        try {
          const webFetch = getBuiltinTools().find((tool) => tool.name === "web_fetch")!;
          const view = await webFetch.execute({ url: "https://github.com/example/awesome" }, { state: {} });
          const readme = view.content.slice(view.content.indexOf("Official repository README:\n") + "Official repository README:\n".length);
          expect(readme.length).toBeLessThanOrEqual(4_500);
          expect(readme).toContain("Case 1 describes its demonstration.");
          expect(readme).toContain("README snapshot kept");
        } finally {
          vi.unstubAllGlobals();
        }
      });
    });
  });

  describe("read_file tool", () => {
    it("reads an existing file", async () => {
      const tools = getBuiltinTools();
      const readFile = tools.find((t) => t.name === "read_file")!;

      const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "core-agent-test-"));
      const testFile = path.join(tmpDir, "test.txt");
      await fs.writeFile(testFile, "line1\nline2\nline3\n");

      const ctx: ToolContext = { workingDir: tmpDir, state: {} };
      const result = await readFile.execute({ path: testFile }, ctx);
      expect(result.content).toContain("line1");
      expect(result.isError).toBeUndefined();

      await fs.rm(tmpDir, { recursive: true });
    });

    it("returns error for non-existent file", async () => {
      const tools = getBuiltinTools();
      const readFile = tools.find((t) => t.name === "read_file")!;

      const ctx: ToolContext = { state: {} };
      const result = await readFile.execute({ path: "/tmp/nonexistent-file-xyz.txt" }, ctx);
      expect(result.isError).toBe(true);
    });

    it("supports maxLines parameter", async () => {
      const tools = getBuiltinTools();
      const readFile = tools.find((t) => t.name === "read_file")!;

      const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "core-agent-test-"));
      const testFile = path.join(tmpDir, "test.txt");
      await fs.writeFile(testFile, "line1\nline2\nline3\nline4\nline5\n");

      const ctx: ToolContext = { workingDir: tmpDir, state: {} };
      const result = await readFile.execute({ path: testFile, maxLines: 2 }, ctx);
      expect(result.content).toContain("line1");
      expect(result.content).toContain("line2");
      expect(result.content).not.toContain("line3");

      await fs.rm(tmpDir, { recursive: true });
    });
  });

  describe("bash tool", () => {
    it("uses the long default only for missing or legacy-synthetic timeout values", () => {
      expect(normalizeBashTimeoutMs(undefined)).toBe(DEFAULT_BASH_TIMEOUT_MS);
      expect(normalizeBashTimeoutMs(-1)).toBe(DEFAULT_BASH_TIMEOUT_MS);
      expect(normalizeBashTimeoutMs(30_000)).toBe(30_000);
      expect(normalizeBashTimeoutMs(300_000)).toBe(300_000);
      expect(normalizeBashTimeoutMs(30_000, { legacyDefault: true })).toBe(DEFAULT_BASH_TIMEOUT_MS);
      expect(normalizeBashTimeoutMs(300_000, { legacyDefault: true })).toBe(DEFAULT_BASH_TIMEOUT_MS);
      expect(normalizeBashTimeoutMs(5_000)).toBe(5_000);
    });

    it("executes a shell command", async () => {
      const tools = getBuiltinTools();
      const bash = tools.find((t) => t.name === "bash")!;

      const ctx: ToolContext = { state: {} };
      const result = await bash.execute({ command: "echo hello" }, ctx);
      expect(result.content).toContain('<command-result status="succeeded" exit_code="0"');
      expect(result.content).toContain("<stdout>\nhello");
      expect(result.observations?.execution).toMatchObject({
        status: "succeeded",
        exitCode: 0,
        timedOut: false,
      });
    });

    it.each([1, 2])("preserves both output streams on exit %i and can execute a corrected command", async (exitCode) => {
      const tools = getBuiltinTools();
      const bash = tools.find((t) => t.name === "bash")!;
      const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "core-bash-failure-"));
      const ctx: ToolContext = { workingDir: tmpDir, state: {} };
      const stdout = "progress ".repeat(40) + "stdout-tail";
      const stderr = "diagnostic ".repeat(40) + "stderr-tail";
      try {
        const script = path.join(tmpDir, "failure.cjs");
        await fs.writeFile(script, `process.stdout.write(${JSON.stringify(stdout)}); process.stderr.write(${JSON.stringify(stderr)}); process.exitCode = ${exitCode};`);
        const result = await bash.execute({ command: shellInvoke(TEST_NODE, [script]) }, ctx);
        expect(result.isError).toBe(true);
        expect(result.content).toContain(`<stdout>\n${stdout}\n</stdout>`);
        expect(result.content).toContain(`<stderr>\n${stderr}\n</stderr>`);
        expect(result.observations?.execution).toMatchObject({
          status: "failed", exitCode, timedOut: false, outputLimitExceeded: false,
          stdout: { bytes: Buffer.byteLength(stdout), truncated: false },
          stderr: { bytes: Buffer.byteLength(stderr), truncated: false },
        });
        await fs.writeFile(script, "process.stdout.write('recovered')");
        const recovered = await bash.execute({ command: shellInvoke(TEST_NODE, [script]) }, ctx);
        expect(recovered.isError).toBeUndefined();
        expect(recovered.content).toContain("<stdout>\nrecovered\n</stdout>");
      } finally {
        await fs.rm(tmpDir, { recursive: true, force: true });
      }
    });

    it("reports a shell start failure without escalating to a tool exception", async () => {
      const tools = getBuiltinTools();
      const bash = tools.find((t) => t.name === "bash")!;
      const invalidWorkingDir = `invalid\0working-dir`;

      const result = await bash.execute(
        { command: "echo must-not-run" },
        { workingDir: invalidWorkingDir, state: {} },
      );

      expect(result.isError).toBe(true);
      expect(result.content).toContain('<command-result status="start_failed" exit_code="null"');
      expect(result.content).toContain("The command was not executed");
      expect(result.content).not.toContain(invalidWorkingDir);
      expect(result.observations?.execution).toMatchObject({
        status: "start_failed",
        exitCode: null,
        timedOut: false,
        outputLimitExceeded: false,
        stdout: { bytes: 0, truncated: false },
      });
    });

    it("forwards ctx.state.sandboxEnv to the child process", async () => {
      // Locks in the contract that skill scripts rely on:
      // `ctx.state.sandboxEnv` must reach the spawned shell as real env vars.
      // Without this, `$ORKAS_NODE` / `$ORKAS_PC_DIR` in SKILL.md commands
      // expand to empty and skills silently no-op.
      const tools = getBuiltinTools();
      const bash = tools.find((t) => t.name === "bash")!;

      const ctx: ToolContext = {
        state: { sandboxEnv: { ORKAS_TEST_TOKEN: "propagated-abc123" } },
      };
      const result = await bash.execute(
        {
          command: shellInvoke(TEST_NODE, [
            "-e",
            "process.stdout.write(process.env.ORKAS_TEST_TOKEN || '')",
          ]),
        },
        ctx,
      );
      expect(result.content).toContain("<stdout>\npropagated-abc123\n</stdout>");
      expect(result.observations?.execution?.stdout.bytes).toBe(17);
      expect(result.isError).toBeUndefined();
    });

    it("hands large stdout to the host through a complete spool file", async () => {
      const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "core-bash-spool-test-"));
      const outputBytes = 1024 * 1024 + 257;
      try {
        const bash = getBuiltinTools().find((tool) => tool.name === "bash")!;
        const result = await bash.execute({
          command: shellInvoke(TEST_NODE, [
            "-e",
            `process.stdout.write('x'.repeat(${outputBytes}))`,
          ]),
        }, {
          workingDir: tmpDir,
          state: { toolResultSpoolDir: path.join(tmpDir, "results") },
        });

        expect(result.isError).toBeUndefined();
        expect(result.content).toContain("full output streamed to Result Store");
        expect(result.streamedOutput!.size).toBeGreaterThan(outputBytes);
        const persisted = await fs.readFile(result.streamedOutput!.path, "utf8");
        expect(persisted).toContain("--- stdout ---");
        expect(persisted).toContain("x".repeat(1024));
        expect(result.observations?.execution).toMatchObject({
          status: "succeeded",
          exitCode: 0,
          stdout: { bytes: outputBytes },
        });
      } finally {
        await fs.rm(tmpDir, { recursive: true, force: true });
      }
    });
  });
});