@hassangameryt/freeflow 0.7.0 → 0.7.2

package/pi-extension/tests/cognitive-routing-v2/recovery.test.js

@@ -0,0 +1,236 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { fixture } from "../fixtures/routing-native.js";
+import { replay } from "../../dist/cognitive-routing-v2/state.js";
+
+test(
+  "resume after attention restores saved-return correction without reopening task work",
+  { timeout: 30000 },
+  async () => {
+    let reportId;
+    await fixture(
+      (n, body, manager) => {
+        if (n === 1)
+          return [{ name: "freeflow_delegate", args: { operation: "assign", contract: "Read and report." } }];
+        if (n === 2) return [{ name: "read", args: { path: "evidence.txt" } }];
+        if (n === 3)
+          return [
+            { name: "freeflow_project", args: { operation: "add", refs: ["ctx:missing"] } },
+            {
+              name: "freeflow_return",
+              args: { operation: "submit", report: "ORIGINAL_SAVED_REPORT", outcome: "partial" },
+            },
+          ];
+        if (n === 4) {
+          reportId = replay(manager.getBranch()).pendingId;
+          return [];
+        }
+        if (n === 5) {
+          assert.equal(body.model, "gpt-4o");
+          return [];
+        }
+        if (n === 6) {
+          assert.equal(body.model, "gpt-4.1-mini");
+          return [{ name: "read", args: { path: "unselected.txt" } }];
+        }
+        if (n === 7) {
+          assert.equal(
+            manager
+              .getBranch()
+              .filter((e) => e.message?.toolName === "read")
+              .at(-1).message.isError,
+            true,
+          );
+          return [
+            {
+              name: "freeflow_project",
+              args: {
+                operation: "remove",
+                refs: ["ctx:missing"],
+                reason: "Invalid reference; evidence gap remains disclosed.",
+              },
+            },
+            { name: "freeflow_return", args: { operation: "retry" } },
+          ];
+        }
+        assert.equal(body.model, "gpt-4o");
+        assert.match(JSON.stringify(body), /ORIGINAL_SAVED_REPORT/);
+        assert.match(JSON.stringify(body), /evidence gap remains disclosed/);
+        const state = replay(manager.getBranch());
+        assert.equal(state.assessment.handoffId, reportId);
+        assert.equal(state.handoffs.get(reportId).reportRevision, 1);
+        assert.equal(state.assessment.view, "active");
+        return [];
+      },
+      true,
+      async ({ session, requests }) => {
+        await session.prompt("Explain the saved return's problem.");
+        await session.waitForIdle();
+        await session.prompt("/freeflow resume");
+        await session.waitForIdle();
+        assert.equal(requests.length, 8);
+      },
+    );
+  },
+);
+
+const normal = (n) =>
+  n === 1
+    ? [{ name: "freeflow_delegate", args: { operation: "assign", contract: "Read evidence.txt and report." } }]
+    : n === 2
+      ? [{ name: "read", args: { path: "evidence.txt" } }]
+      : n === 3
+        ? [{ name: "freeflow_return", args: { operation: "submit", report: "Read completed.", outcome: "completed" } }]
+        : [];
+
+for (const cut of ["delegate-accepted", "executor-configured", "executor-call", "read-result", "return-accepted"]) {
+  test(`native navigation reconciles valid ${cut} without replaying work`, { timeout: 30000 }, async () => {
+    await fixture(normal, false, async ({ session, manager, requests }) => {
+      const chosen = manager
+        .getEntries()
+        .find((e) =>
+          cut === "executor-configured"
+            ? e.data?.data?.type === "handoff-state" && e.data.data.state === "configured"
+            : cut === "executor-call"
+              ? e.message?.role === "assistant" && e.message.content?.some((b) => b.name === "read")
+              : cut === "read-result"
+                ? e.message?.toolName === "read"
+                : e.data?.data?.type === cut,
+        );
+      const reads = manager.getEntries().filter((e) => e.message?.toolName === "read").length;
+      await session.navigateTree(chosen.id, { summarize: false });
+      const before = requests.length;
+      await session.prompt("Explain the saved state at this point.");
+      await session.waitForIdle();
+      assert.equal(requests.length, before + 1);
+      assert.equal(requests.at(-1).model, "gpt-4o");
+      assert.equal(manager.getEntries().filter((e) => e.message?.toolName === "read").length, reads);
+      assert.equal(replay(manager.getBranch()).profile, "coordinator");
+    });
+  });
+}
+
+test(
+  "explicit resume continues the same assignment after Coordinator handles new input",
+  { timeout: 30000 },
+  async () => {
+    let assignment, unit;
+    await fixture(
+      (n, body, manager) => {
+        if (n <= 2) return normal(n);
+        if (n === 3) {
+          const s = replay(manager.getBranch());
+          assignment = s.assignmentId;
+          unit = s.unitId;
+          return [];
+        }
+        if (n === 4) {
+          assert.equal(body.model, "gpt-4o");
+          return [];
+        }
+        if (n === 5) {
+          assert.equal(body.model, "gpt-4.1-mini");
+          const s = replay(manager.getBranch());
+          assert.equal(s.assignmentId, assignment);
+          assert.equal(s.unitId, unit);
+          assert.equal(s.assignments.size, 1);
+          assert.match(JSON.stringify(body), /Do not edit files/);
+          assert.doesNotMatch(JSON.stringify(body), /New delivered user input requires Coordinator attention/);
+          return [{ name: "read", args: { path: "unselected.txt" } }];
+        }
+        if (n === 6) {
+          const read = manager
+            .getBranch()
+            .filter((e) => e.message?.toolName === "read")
+            .at(-1);
+          assert.equal(read.message.isError, false);
+          return [
+            {
+              name: "freeflow_return",
+              args: { operation: "submit", report: "Resumed read completed; no edits.", outcome: "completed" },
+            },
+          ];
+        }
+        assert.equal(body.model, "gpt-4o");
+        return [];
+      },
+      false,
+      async ({ session, manager, requests }) => {
+        await session.prompt("Do not edit files. Explain the current partial result.");
+        await session.waitForIdle();
+        await session.prompt("/freeflow resume");
+        await session.waitForIdle();
+        assert.equal(requests.length, 7);
+        assert.equal(replay(manager.getBranch()).assignments.get(assignment).state, "returned");
+      },
+    );
+  },
+);
+
+test("current manual hold survives navigation and resume cannot release it", { timeout: 30000 }, async () => {
+  await fixture(normal, false, async ({ session, manager, requests }) => {
+    const old = manager.getEntries().find((e) => e.data?.data?.type === "delegate-accepted");
+    await session.prompt("/freeflow profile executor");
+    await session.navigateTree(old.id, { summarize: false });
+    const before = requests.length;
+    await session.prompt("/freeflow resume");
+    assert.equal(requests.length, before);
+    const s = replay(manager.getBranch());
+    assert.equal(s.control, "manual");
+    assert.equal(s.profile, "executor");
+    assert.equal(session.model.id, "gpt-4.1-mini");
+  });
+});
+
+test(
+  "late steering keeps the captured Executor request coherent and blocks dependent task tools",
+  { timeout: 30000 },
+  async () => {
+    let active;
+    await fixture(
+      async (n, body, manager) => {
+        if (n === 1) return normal(n);
+        if (n === 2) {
+          await active.steer("Stop further reads and explain the current result.");
+          return normal(n);
+        }
+        if (n === 3) {
+          assert.equal(body.model, "gpt-4.1-mini");
+          assert.match(JSON.stringify(body), /New delivered user input requires Coordinator attention/);
+          assert.ok(!body.tools.some((t) => t.name === "freeflow_delegate"));
+          assert.deepEqual(body.tools.find((t) => t.name === "freeflow_unit").parameters.properties.operation.enum, [
+            "inspect",
+          ]);
+          return [{ name: "read", args: { path: "unselected.txt" } }];
+        }
+        if (n === 4) {
+          assert.equal(
+            manager
+              .getBranch()
+              .filter((e) => e.message?.toolName === "read")
+              .at(-1).message.isError,
+            true,
+          );
+          return [
+            {
+              name: "freeflow_return",
+              args: { operation: "submit", report: "Stopped for the newer instruction.", outcome: "partial" },
+            },
+          ];
+        }
+        assert.equal(body.model, "gpt-4o");
+        assert.ok(!body.tools.some((t) => t.name === "freeflow_return" || t.name === "freeflow_project"));
+        assert.match(JSON.stringify(body), /Stop further reads/);
+        return [];
+      },
+      false,
+      undefined,
+      true,
+      {
+        onSession: (session) => {
+          active = session;
+        },
+      },
+    );
+  },
+);

package/pi-extension/tests/cognitive-routing-v2/render.test.js

@@ -0,0 +1,230 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { renderRoutingCall, renderRoutingResult } from "../../dist/cognitive-routing-v2/render.js";
+
+test("evidence inspection renders metadata and gaps without source previews", () => {
+  const receipt = {
+    count: 1,
+    returned: 1,
+    selected: ["ctx:old"],
+    candidates: [
+      {
+        ref: "ctx:old",
+        kind: "toolResult",
+        producer: "executor",
+        toolName: "read",
+        assignment: "a1",
+        selected: true,
+        active: false,
+        eligible: true,
+        targetReady: false,
+        preview: "SOURCE_BODY_MUST_NOT_APPEAR",
+        limitations: [{ code: "target_representation", detail: "Required image unsupported" }],
+      },
+    ],
+  };
+  const rendered = renderRoutingResult({ details: receipt }, { expanded: true }, "freeflow_project", {
+    args: { operation: "inspect" },
+  })
+    .render(100)
+    .join("\n");
+  assert.doesNotMatch(rendered, /SOURCE_BODY_MUST_NOT_APPEAR|undefined/);
+  for (const value of ["ctx:old", "executor", "read", "assignment a1", "Required image unsupported"])
+    assert.ok(rendered.includes(value));
+});
+
+test("expanded receipts retain complete captured reports at narrow and wide widths", () => {
+  const report = "Captured report " + "long evidence with Unicode 界 and words ".repeat(20) + " END_OF_REPORT";
+  const receipt = {
+    status: "accepted",
+    reportSaved: true,
+    transition: "blocked",
+    ready: false,
+    report,
+    evidence: { withdrawals: [{ ref: "ctx:a", reason: "Reason stays visible" }] },
+  };
+  for (const width of [24, 40, 100]) {
+    const lines = renderRoutingResult({ details: receipt }, { expanded: true }).render(width);
+    assert.ok(lines.every((line) => visibleWidth(line) <= width));
+    assert.match(lines.join("\n"), /END_OF_REPORT/);
+    assert.match(lines.join("\n").replace(/\s+/g, " "), /Reason stays visible/);
+    const compact = renderRoutingResult({ details: receipt }, {}).render(width).join("\n");
+    assert.match(compact, /Report saved/);
+    assert.match(compact, /needs correction/);
+    assert.doesNotMatch(compact, /END_OF_REPORT/);
+  }
+});
+
+test("streaming arguments follow the latest six wrapped lines; expansion retains the whole draft", () => {
+  const report = Array.from({ length: 12 }, (_, i) => `Report line ${i + 1}`).join("\n");
+  const live = { argsComplete: false, isPartial: true, expanded: false };
+  const lines = renderRoutingCall("freeflow_return", { operation: "submit", report }, live).render(40);
+  assert.match(lines.join("\n"), /Writing report/);
+  assert.match(lines.join("\n"), /Report line 12/);
+  assert.doesNotMatch(lines.join("\n"), /Report line 1\s/);
+  assert.equal(lines.filter((line) => line.includes("Report line")).length, 6);
+  const full = renderRoutingCall("freeflow_return", { operation: "submit", report }, { ...live, expanded: true })
+    .render(40)
+    .join("\n");
+  assert.match(full, /Report line 1\s/);
+  assert.match(full, /Report line 12/);
+  const done = renderRoutingCall(
+    "freeflow_return",
+    { operation: "submit", report },
+    { ...live, argsComplete: true, isPartial: false },
+  )
+    .render(40)
+    .join("\n");
+  assert.equal(done.trim(), "Return to Coordinator");
+});
+
+test("report streaming is not obscured by limitations sent before or after the report", () => {
+  const limitations = ["First limitation", "Second limitation", "Third limitation"];
+  const live = { isPartial: true, argsComplete: false };
+  for (const reportFirst of [true, false]) {
+    for (const length of [2, 12, 20]) {
+      const report = Array.from({ length }, (_, i) => `Report progress ${i + 1}`).join("\n");
+      const args = reportFirst
+        ? { operation: "submit", report, limitations }
+        : { operation: "submit", limitations, report };
+      const collapsed = renderRoutingCall("freeflow_return", args, live).render(60).join("\n");
+      assert.match(collapsed, new RegExp(`Report progress ${length}`));
+      assert.doesNotMatch(collapsed, /Limitation:/);
+      const expanded = renderRoutingCall("freeflow_return", args, { ...live, expanded: true })
+        .render(60)
+        .join("\n");
+      for (const limit of limitations) assert.ok(expanded.includes(limit));
+      assert.match(expanded, /Report progress 1/);
+    }
+  }
+  assert.doesNotMatch(
+    renderRoutingCall("freeflow_return", { operation: "submit", limitations }, live).render(60).join("\n"),
+    /Limitation:/,
+  );
+});
+
+test("replacement streaming follows the contract without a sticky reason", () => {
+  const reason = "Replacement reason " + "keeps its full explanation. ".repeat(30);
+  const live = { isPartial: true, argsComplete: false };
+  for (const length of [2, 12]) {
+    const contract = Array.from({ length }, (_, i) => `Replacement progress ${i + 1}`).join("\n");
+    for (const args of [
+      { operation: "replace", reason, contract },
+      { operation: "replace", contract, reason },
+    ]) {
+      const compact = renderRoutingCall("freeflow_delegate", args, live).render(60).join("\n");
+      assert.match(compact, new RegExp(`Replacement progress ${length}`));
+      assert.doesNotMatch(compact, /Reason:|Replacement reason/);
+      const expanded = renderRoutingCall("freeflow_delegate", args, { ...live, expanded: true })
+        .render(60)
+        .join("\n");
+      assert.match(expanded, /Reason: Replacement reason/);
+      assert.match(expanded, /Replacement progress 1/);
+    }
+  }
+});
+
+test("completed receipts describe outcomes without protocol state disclaimers", () => {
+  for (const [name, operation, receipt, expected] of [
+    ["freeflow_delegate", "assign", { status: "accepted", transition: "pending" }, "Assignment saved"],
+    ["freeflow_delegate", "replace", { status: "accepted", transition: "pending" }, "Replacement saved"],
+    [
+      "freeflow_return",
+      "submit",
+      { status: "accepted", reportSaved: true, ready: true, transition: "pending" },
+      "Report saved",
+    ],
+    [
+      "freeflow_return",
+      "retry",
+      { status: "accepted", reportSaved: true, reportUnchanged: true, ready: true },
+      "Saved report retained",
+    ],
+    ["freeflow_project", "add", { status: "saved", selected: ["ctx:a", "ctx:b"], ready: true }, "2 sources selected"],
+    ["freeflow_project", "list", { status: "listed", count: 12, selectableCount: 8 }, "12 sources · 8 selectable"],
+    ["freeflow_unit", "close", { status: "closed", outcome: "deferred" }, "Deferred"],
+    ["freeflow_unit", "history", { history: [{}, {}] }, "2 events"],
+    ["freeflow_project", "remove", { selected: ["ctx:b"], items: [{ status: "removed" }] }, "1 removed · 1 remaining"],
+    // Older receipts used withdrawn for selected and unresolved references alike.
+    [
+      "freeflow_project",
+      "remove",
+      { selected: [], items: [{ status: "withdrawn" }] },
+      "1 reference withdrawn · 0 remaining",
+    ],
+    [
+      "freeflow_project",
+      "inspect",
+      { selected: ["ctx:a"], ready: true },
+      "1 source selected · No unresolved references",
+    ],
+    [
+      "freeflow_project",
+      "add",
+      { selected: ["ctx:a"], items: [{ status: "already_selected" }], ready: true },
+      "No changes · 1 source selected",
+    ],
+    ["freeflow_unit", "assess", { status: "resumed", ready: true }, "Evidence prepared"],
+    ["freeflow_unit", "assess", { status: "suspended", ready: false }, "Assessment remains paused"],
+    [
+      "freeflow_unit",
+      "status",
+      { effective: true, activeProfile: "executor", controlMode: "automatic", assignment: { state: "outstanding" } },
+      "Executor · Assignment in progress",
+    ],
+  ]) {
+    const text = renderRoutingResult({ details: receipt }, {}, name, { args: { operation } }).render(100).join("\n");
+    assert.ok(text.includes(expected), text);
+    assert.doesNotMatch(text, /transfer pending|not acceptance|status:/);
+  }
+});
+
+test("preview limits apply after wrapping long text, and interrupted drafts remain inspectable", () => {
+  const args = {
+    operation: "assign",
+    contract: "Unicode 界 and \u001b[32mcoloured\u001b[0m text ".repeat(40) + " FINAL_WORD",
+  };
+  const component = renderRoutingCall("freeflow_delegate", args, { isPartial: true, argsComplete: false });
+  for (const width of [24, 50, 100]) {
+    const lines = component.render(width);
+    assert.ok(lines.every((line) => visibleWidth(line) <= width));
+    assert.ok(lines.length <= 12, "header, hint and six preview rows stay bounded");
+    assert.match(lines.join("\n"), /FINAL_WORD/);
+  }
+  const failed = renderRoutingResult(
+    { content: [{ type: "text", text: "Operation aborted" }] },
+    { expanded: true },
+    "freeflow_delegate",
+    { args },
+  )
+    .render(50)
+    .join("\n");
+  assert.match(failed, /Submitted contract/);
+  assert.match(failed, /FINAL_WORD/);
+});
+test("partial and absent arguments/results render without requiring live runtime state", () => {
+  assert.ok(renderRoutingCall("freeflow_delegate", undefined).render(30).length);
+  assert.match(renderRoutingResult({}, { isPartial: true }).render(30).join(""), /Working/);
+  const inspection = renderRoutingCall(
+    "freeflow_unit",
+    { operation: "inspect", view: "detail", ref: "assignment:existing" },
+    { isPartial: true, argsComplete: false },
+  )
+    .render(60)
+    .join("\n");
+  assert.match(inspection, /View: detail/);
+  assert.match(inspection, /Ref: assignment:existing/);
+});
+
+test("native error results with empty details never look like successful saved assignments", () => {
+  const result = { content: [{ type: "text", text: "Operation aborted" }], details: {} };
+  const rendered = renderRoutingResult(result, {}, "freeflow_delegate", {
+    args: { operation: "assign" },
+    isError: true,
+  })
+    .render(60)
+    .join("\n");
+  assert.match(rendered, /Operation aborted/);
+  assert.doesNotMatch(rendered, /Assignment saved/);
+});

package/pi-extension/tests/cognitive-routing-v2/runtime.test.js

@@ -0,0 +1,153 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { RoutingRuntime } from "../../dist/cognitive-routing-v2/runtime.js";
+import { EventStore } from "../../dist/session-sources/events.js";
+import { replay } from "../../dist/cognitive-routing-v2/state.js";
+
+const models = Object.fromEntries(
+  ["coordinator", "executor"].map((id) => [
+    id,
+    { id, provider: "fixture", api: "fixture", input: ["text"], contextWindow: 100000, maxTokens: 1000 },
+  ]),
+);
+const cap = {
+  effective: true,
+  enabled: true,
+  projection: false,
+  profiles: Object.fromEntries(
+    Object.keys(models).map((id) => [id, { provider: "fixture", model: id, thinking: "off" }]),
+  ),
+  blockingReason: { code: "", message: "" },
+};
+async function environment(run) {
+  const root = await mkdtemp(join(tmpdir(), "routing-runtime-"));
+  let active;
+  const make = (label) => {
+    const manager = SessionManager.create(root, join(root, label));
+    manager.appendMessage({
+      role: "assistant",
+      content: [{ type: "text", text: "seed" }],
+      model: "coordinator",
+      provider: "fixture",
+      api: "fixture",
+      stopReason: "stop",
+      timestamp: 1,
+    });
+    return {
+      sessionManager: manager,
+      model: models.coordinator,
+      thinkingLevel: "off",
+      modelRegistry: { find: (_p, id) => models[id], getApiKeyAndHeaders: async () => ({ ok: true }) },
+      getSystemPrompt: () => "",
+      isIdle: () => true,
+      abort() {},
+    };
+  };
+  const pi = {
+    appendEntry: (type, data) => active.sessionManager.appendCustomEntry(type, data),
+    setModel: async (model) => {
+      active.model = model;
+      return true;
+    },
+    setThinkingLevel: (level) => {
+      active.thinkingLevel = level;
+    },
+    getAllTools: () => [],
+    sendMessage() {},
+  };
+  const runtime = new RoutingRuntime(pi);
+  try {
+    await run({
+      runtime,
+      make,
+      activate: (ctx) => {
+        active = ctx;
+      },
+      pi,
+    });
+  } finally {
+    runtime.unbind();
+    await rm(root, { recursive: true, force: true });
+  }
+}
+
+test("delayed old control cannot change or poison a newly bound session", async () =>
+  environment(async ({ runtime, make, activate }) => {
+    const a = make("a"),
+      b = make("b");
+    activate(a);
+    await runtime.bind(a, cap);
+    const original = EventStore.prototype.reconcile;
+    let release, entered;
+    const gate = new Promise((r) => {
+      release = r;
+    });
+    const entrance = new Promise((r) => {
+      entered = r;
+    });
+    EventStore.prototype.reconcile = async function () {
+      await original.call(this);
+      if (this.reader === a.sessionManager) {
+        entered();
+        await gate;
+      }
+    };
+    try {
+      const old = runtime.setManualProfile("executor");
+      await entrance;
+      activate(b);
+      await runtime.bind(b, cap);
+      const before = b.sessionManager.getEntries().length;
+      release();
+      assert.equal((await old).status, "blocked");
+      assert.equal(b.sessionManager.getEntries().length, before);
+      assert.equal(b.model.id, "coordinator");
+      assert.equal(runtime.state().runtimeStatus, "active");
+      assert.equal(replay(b.sessionManager.getBranch()).control, "automatic");
+    } finally {
+      release();
+      EventStore.prototype.reconcile = original;
+    }
+  }));
+
+test("settled unbound attempt is retired truthfully and next request has a new identity", async () =>
+  environment(async ({ runtime, make, activate }) => {
+    const ctx = make("interrupt");
+    activate(ctx);
+    await runtime.bind(ctx, cap);
+    const first = { role: "user", content: "one", timestamp: 2 };
+    ctx.sessionManager.appendMessage(first);
+    await runtime.context(ctx, [first]);
+    const assistant = {
+      role: "assistant",
+      content: [{ type: "toolCall", id: "call", name: "read", arguments: {} }],
+      timestamp: 3,
+    };
+    runtime.messageEnd(assistant);
+    ctx.sessionManager.appendMessage(assistant);
+    runtime.preflight({ toolName: "read", toolCallId: "call" }, ctx);
+    const old = [...replay(ctx.sessionManager.getBranch()).executions.values()][0];
+    await runtime.settled(ctx);
+    const retired = replay(ctx.sessionManager.getBranch()).executions.get(old.id);
+    assert.match(retired.interrupted, /unresolved/);
+    assert.equal(retired.assistantEntryId, undefined);
+    const second = { role: "user", content: "two", timestamp: 4 };
+    ctx.sessionManager.appendMessage(second);
+    await runtime.context(ctx, [first, assistant, second]);
+    const next = {
+      role: "assistant",
+      content: [{ type: "toolCall", id: "next", name: "read", arguments: {} }],
+      timestamp: 5,
+    };
+    runtime.messageEnd(next);
+    ctx.sessionManager.appendMessage(next);
+    runtime.preflight({ toolName: "read", toolCallId: "next" }, ctx);
+    const executions = [...replay(ctx.sessionManager.getBranch()).executions.values()];
+    assert.equal(executions.length, 2);
+    assert.notEqual(executions[1].id, old.id);
+    assert.notEqual(executions[1].basisUserEntryId, old.basisUserEntryId);
+  }));