@hassangameryt/freeflow 0.7.2 → 0.7.3

package/pi-extension/tests/provider-support/cli.test.js

@@ -0,0 +1,92 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { mkdtemp, mkdir, writeFile, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+import { response } from "../fixtures/routing-native.js";
+
+test(
+  "bundled Pi CLI loads Freeflow adapter and changes effort inside a native tool loop",
+  { timeout: 30000 },
+  async () => {
+    const root = await mkdtemp(join(tmpdir(), "astra-cli-")),
+      agentDir = join(root, "agent");
+    try {
+      await mkdir(agentDir);
+      await writeFile(
+        join(agentDir, "auth.json"),
+        JSON.stringify({ openai: { type: "api_key", key: "fixture-not-real" } }),
+      );
+      await writeFile(
+        join(agentDir, "settings.json"),
+        JSON.stringify({
+          defaultProvider: "openai",
+          defaultModel: "gpt-6-astra",
+          defaultThinkingLevel: "low",
+          transport: "sse",
+          compaction: { enabled: false },
+          retry: { enabled: false, maxRetries: 0, provider: { maxRetries: 0 } },
+        }),
+      );
+      const capture = join(root, "requests.json"),
+        extension = join(root, "fixture.mjs");
+      await writeFile(
+        extension,
+        `import {writeFileSync} from 'node:fs';\n${response.toString()}\nexport default function(pi){pi.registerTool({name:'probe_raise_effort',label:'Probe effort',description:'Fixture only',parameters:{type:'object',properties:{}},execute:async()=>{pi.setThinkingLevel('high');return {content:[{type:'text',text:'Changed desired effort.'}]};}});const bodies=[];globalThis.fetch=async(url,init)=>{if(String(url)!=='https://api.openai.com/v1/responses')throw Error('Unexpected network');const body=JSON.parse(String(init.body));bodies.push(body);writeFileSync(${JSON.stringify(capture)},JSON.stringify(bodies));if(bodies.length>2)throw Error('Unexpected extra request');return response(bodies.length,bodies.length===1?[{name:'probe_raise_effort',args:{}}]:[],'OK');};}`,
+      );
+      const cli = fileURLToPath(new URL("./bundle/cli.js", import.meta.resolve("@earendil-works/pi-coding-agent")));
+      const entry = fileURLToPath(new URL("../../freeflow/index.js", import.meta.url));
+      const child = spawn(
+        process.execPath,
+        [
+          cli,
+          "-p",
+          "--mode",
+          "json",
+          "--no-extensions",
+          "--no-skills",
+          "--no-context-files",
+          "--no-prompt-templates",
+          "--no-themes",
+          "-e",
+          extension,
+          "-e",
+          entry,
+          "Run the effort fixture.",
+        ],
+        {
+          cwd: root,
+          env: {
+            PATH: process.env.PATH,
+            PI_CODING_AGENT_DIR: agentDir,
+            PI_OFFLINE: "1",
+            PI_TELEMETRY: "0",
+            PI_SKIP_VERSION_CHECK: "1",
+          },
+          stdio: ["ignore", "pipe", "pipe"],
+        },
+      );
+      let output = "";
+      child.stdout.on("data", (d) => (output += d));
+      child.stderr.on("data", (d) => (output += d));
+      const timer = setTimeout(() => child.kill("SIGKILL"), 20000);
+      const code = await new Promise((resolve, reject) => {
+        child.on("error", reject);
+        child.on("close", resolve);
+      });
+      clearTimeout(timer);
+      assert.equal(code, 0, output.slice(-4000));
+      const bodies = JSON.parse(await readFile(capture, "utf8"));
+      assert.equal(bodies.length, 2);
+      assert.equal(bodies[1].reasoning.effort, "low");
+      const updates = bodies[1].input.filter((i) => i.type === "configuration_update");
+      assert.deepEqual(updates, [{ type: "configuration_update", reasoning: { effort: "high" } }]);
+      assert.ok(bodies[1].input.some((i) => i.type === "function_call_output"));
+      assert.match(output, /OK/);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  },
+);

package/pi-extension/tests/provider-support/native.test.js

@@ -0,0 +1,183 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { mkdtemp, mkdir, rm, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  createAgentSession,
+  DefaultResourceLoader,
+  ModelRuntime,
+  SessionManager,
+  SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+import freeflow from "../../dist/index.js";
+import { registerProviderSupport } from "../../dist/provider-support/index.js";
+import { ENTRY_TYPE } from "../../dist/provider-support/astra/history.js";
+import { response } from "../fixtures/routing-native.js";
+
+async function native(extension, run) {
+  const root = await mkdtemp(join(tmpdir(), "astra-native-")),
+    agentDir = join(root, "agent");
+  await mkdir(agentDir);
+  const previousFetch = globalThis.fetch,
+    requests = [],
+    errors = [];
+  let session;
+  globalThis.fetch = async (url, init) => {
+    assert.match(String(url), /^https:\/\/api\.openai\.com\/v1\/responses$/);
+    requests.push(JSON.parse(String(init.body)));
+    assert.ok(requests.length <= 12);
+    return response(requests.length, [], "OK");
+  };
+  try {
+    const runtime = await ModelRuntime.create({
+      authPath: join(agentDir, "auth.json"),
+      modelsPath: null,
+      modelsStorePath: join(agentDir, "models.json"),
+      allowModelNetwork: false,
+    });
+    await runtime.setRuntimeApiKey("openai", "fixture-only-key");
+    const settings = SettingsManager.inMemory({
+      transport: "sse",
+      compaction: { enabled: false, keepRecentTokens: 1, reserveTokens: 1 },
+      retry: { enabled: false, maxRetries: 0, provider: { maxRetries: 0 } },
+    });
+    const manager = SessionManager.create(root, join(root, "sessions"));
+    let cancelCompaction = false;
+    const loader = new DefaultResourceLoader({
+      cwd: root,
+      agentDir,
+      settingsManager: settings,
+      noExtensions: true,
+      noSkills: true,
+      noPromptTemplates: true,
+      noThemes: true,
+      noContextFiles: true,
+      systemPrompt: "Reply OK.",
+      extensionFactories: [
+        extension,
+        (pi) =>
+          pi.on("session_before_compact", () =>
+            cancelCompaction
+              ? { cancel: true }
+              : {
+                  compaction: {
+                    summary: "Older material summarized.",
+                    firstKeptEntryId: manager.getLeafId(),
+                    tokensBefore: 100,
+                  },
+                },
+          ),
+      ],
+    });
+    await loader.reload();
+    assert.deepEqual(loader.getExtensions().errors, []);
+    ({ session } = await createAgentSession({
+      cwd: root,
+      agentDir,
+      modelRuntime: runtime,
+      model: runtime.getModel("openai", "gpt-6-astra"),
+      thinkingLevel: "low",
+      settingsManager: settings,
+      sessionManager: manager,
+      resourceLoader: loader,
+      tools: [],
+    }));
+    await session.bindExtensions({ mode: "print", onError: (e) => errors.push(e) });
+    const prompt = async (text, effort) => {
+      if (effort) session.setThinkingLevel(effort);
+      await session.prompt(text);
+      await session.waitForIdle();
+      assert.equal(session.messages.at(-1)?.stopReason, "stop");
+      assert.deepEqual(errors, []);
+      return requests.at(-1);
+    };
+    await run({
+      session,
+      manager,
+      requests,
+      prompt,
+      root,
+      cancelCompaction: () => {
+        cancelCompaction = true;
+      },
+    });
+    assert.deepEqual(errors, []);
+  } finally {
+    session?.dispose();
+    globalThis.fetch = previousFetch;
+    await rm(root, { recursive: true, force: true });
+  }
+}
+const updates = (p) =>
+  p.input.flatMap((x, i) => (x.type === "configuration_update" ? [{ index: i, effort: x.reasoning.effort }] : []));
+
+test("real Pi request dispatch, reload, native tree navigation and compaction", { timeout: 30000 }, async () => {
+  await native(registerProviderSupport, async ({ session, manager, requests, prompt }) => {
+    await prompt("first", "low");
+    const high = await prompt("second", "high");
+    assert.equal(high.reasoning.effort, "low");
+    assert.equal(session.thinkingLevel, "high");
+    assert.deepEqual(updates(high), [{ index: 3, effort: "high" }]);
+    await session.reload();
+    const low = await prompt("third", "low");
+    assert.deepEqual(low.input.slice(0, high.input.length), high.input);
+    assert.deepEqual(updates(low), [
+      { index: 3, effort: "high" },
+      { index: 6, effort: "low" },
+    ]);
+    const branchPoint = manager
+      .getBranch()
+      .find((e) => e.message?.role === "user" && e.message.content?.some?.((b) => b.text === "second"));
+    assert.ok(branchPoint);
+    // Native tree navigation selects real ancestry; the discarded later Low update must not survive.
+    await session.navigateTree(branchPoint.id, { summarize: false });
+    const sibling = await prompt("sibling", "medium");
+    assert.ok(updates(sibling).every((x) => x.effort !== "low"));
+    await session.compact();
+    const compacted = await prompt("after summary", "high");
+    assert.equal(compacted.reasoning.effort, "high");
+    assert.deepEqual(updates(compacted), []);
+    const persisted = await readFile(manager.getSessionFile(), "utf8");
+    assert.ok(persisted.includes(ENTRY_TYPE));
+    assert.ok(!manager.getBranch().some((e) => e.customType === "freeflow-routing-v2"));
+    assert.equal(requests.length, 5);
+  });
+});
+
+test(
+  "the Freeflow extension adapts Astra without repository activation or Cognitive Routing",
+  { timeout: 30000 },
+  async () => {
+    await native(freeflow, async ({ session, manager, prompt }) => {
+      await prompt("one", "low");
+      const p = await prompt("two", "high");
+      assert.equal(p.reasoning.effort, "low");
+      assert.equal(session.thinkingLevel, "high");
+      assert.ok(updates(p).some((x) => x.effort === "high"));
+      assert.ok(manager.getBranch().some((e) => e.customType === ENTRY_TYPE));
+      assert.ok(!manager.getBranch().some((e) => e.customType === "freeflow-routing-v2"));
+      assert.ok(!(p.tools ?? []).some((t) => t.name.startsWith("freeflow_")));
+    });
+  },
+);
+
+test(
+  "rapid native effort changes coalesce and cancelled compaction releases adaptation",
+  { timeout: 30000 },
+  async () => {
+    await native(registerProviderSupport, async ({ session, prompt, cancelCompaction }) => {
+      await prompt("first", "low");
+      session.setThinkingLevel("high");
+      session.setThinkingLevel("max");
+      session.setThinkingLevel("medium");
+      const medium = await prompt("second");
+      assert.deepEqual(updates(medium), [{ index: 3, effort: "medium" }]);
+      cancelCompaction();
+      await assert.rejects(session.compact(), /cancelled/);
+      const high = await prompt("third", "high");
+      assert.equal(high.reasoning.effort, "low");
+      assert.equal(updates(high).at(-1).effort, "high");
+    });
+  },
+);

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "freeflow",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "Feedback-based control system for coding agents.",
   "author": {
     "name": "Hassan Mohiddin"

package/runtime/prompts/cognitive-routing.md

@@ -1,9 +1,9 @@
 ## Cognitive Routing Cue
 
-Cognitive Routing uses Coordinator and Executor in one agent/session to improve quality, continuity, responsiveness, and total cost together. Coordinator guides and assesses Executor's bounded work.
+Cognitive Routing places work across configured profiles in one agent/session to improve quality, continuity, responsiveness, and total cost together. Coordinator owns user interaction, governing direction, delegation, and acceptance. When enabled, Helper is the normal delegate for supporting work; Executor is commissioned for substantive or consequential results, including implementation and artifacts. Helper and Executor share ordinary active history; only Coordinator delegates and only one profile executes at a time.
 
-Use the latest Runtime State for control, profile, and current responsibility. Under Manual or inactive routing, stop applying the automatic split and follow ordinary Workflow.
+Use the latest Runtime State for control, profile, delegation mode, and current responsibility. In Automatic control, follow the selected mode: helper-only permits Coordinator substantive production with Helper support; executor-only delegates environment work to Executor; both uses Helper by default for support and Executor for substantive work. A mode change does not retarget an accepted assignment or its recovery. Under Manual control, the held Coordinator, Helper, or Executor follows ordinary unsplit Workflow without Automatic role restrictions. Do not release the user's hold. When routing is inactive, stop applying this split.
 
-Before relying on automatic routing, read the complete cognitive-routing skill if its body is absent. This bootstrap read is the only environment call in that response. If unavailable, stop and report the missing method. Reload it after context loss before applying remembered routing rules.
+Before relying on Automatic routing, read the complete cognitive-routing skill if its body is absent. This bootstrap read is the only environment call in that response. If unavailable, stop and report the missing method. Reload it after context loss before applying remembered routing rules.
 
-When projection is on, Executor must project every completed skill and instructional-reference read, including this bootstrap read. Follow the skill for tool access, execution, evidence, handoffs, context cleaning, and recovery.
+When projection is on, the active worker must project every completed skill and instructional-reference read, including this bootstrap read. Follow the skill for work placement, environment access, evidence, handoffs, and recorded-worker recovery. Under Automatic routing, a worker return or passing check is not Coordinator acceptance; completed Slice closure requires Coordinator's supported judgment and explicit closure instruction. Manual control follows ordinary Workflow and Track Work instead.

package/skills/design-for-depth/SKILL.md

@@ -30,7 +30,7 @@ A large mechanical change may need no design escalation. A one-line change may n
 
 Use the lens early when interface, ownership, state, or failure choices could harden into caller contracts. It can support discussion, a Spec or Plan, implementation preparation, or selecting a test seam.
 
-Before substantial implementation, or before writing its guiding design, read [Implementation Decisions](references/implementation-decisions.md) when unresolved representation, identity, ownership, algorithm, or failure choices could invalidate significant dependent work. Select a supported mechanism or identify the missing observation; leave ordinary mechanics free. The reference helps make those choices explicit and check their realization, not impose a blueprint on every task.
+Read [Implementation Decisions](references/implementation-decisions.md) when unresolved representation, identity, ownership, algorithm, dependency, or failure choices could materially change a technical recommendation or invalidate significant dependent work. Apply it before recommending a mechanism during discussion, writing its guiding design, or beginning substantial implementation. Explore alternatives against the current goal and constraints; select a supported mechanism or identify the missing observation or user-owned choice. Leave ordinary mechanics free. The reference helps make those choices explicit and check their realization, not impose a blueprint on every task.
 
 Once a boundary is supported, do not reopen it merely because the skill remains in context. Re-enter when evidence shows growing caller coordination, scattered policy, exposed internal states, fragile test choreography, unclear dependency/failure ownership, or an invalidated design assumption.
 

package/skills/design-for-depth/references/implementation-decisions.md

@@ -1,12 +1,12 @@
 # Implementation Decisions
 
-Read this before substantial implementation, or before writing its guiding design, when unresolved representation, identity, ownership, algorithm, or failure choices could invalidate significant dependent work. Skip it for a supported local change whose remaining mechanics do not alter those boundaries.
+Read this when unresolved representation, identity, ownership, algorithm, dependency, or failure choices could materially change a technical recommendation or invalidate significant dependent work. Apply it before recommending a mechanism during discussion, writing its guiding design, or beginning substantial implementation. Skip it for a supported local change whose remaining mechanics do not alter those boundaries.
 
 Use this method under Design for Depth and the current activity. It does not create another planning phase, document requirement, approval gate, or compute role.
 
 ## Identify What Implementation Would Still Have To Invent
 
-Start from the accepted outcome, relevant source evidence, and existing design. Ask:
+Start from the current goal and constraints, relevant source evidence, and existing design. During discussion, mark unsettled outcomes and approaches as provisional: compare their consequences without turning an explored option into an accepted requirement. Select supported engineering details within the agreement; return user-owned choices through the current activity. Ask:
 
 > Which remaining choices could change correctness, complexity, failure behavior, or force substantial dependent work to be redone?
 
@@ -73,4 +73,4 @@ Weak direction: "Make persistence idempotent and robust."
 
 Useful direction: "The append owner distinguishes observed acknowledgment from an uncertain attempt. An equal entry in memory does not resolve an earlier failure. Validate before mutation; publish accepted state only at the supported acknowledgment boundary. Test append advancing memory then failing, followed by the identical operation: uncertainty must remain until supported reconciliation. Also test an acknowledged duplicate so the implementation does not reject every retry. Do not infer filesystem durability from readback. Reconsider the mechanism if the actual host boundary differs."
 
-Stop when the next implementation has a supported approach and intentional local freedom, or its blocking question is explicit. Do not pursue a complete blueprint for later work whose premises remain unsettled.
+Stop when the current discussion has a supported recommendation or explicit open question, or the next implementation has a supported approach and intentional local freedom. Preserve provisional versus accepted decisions when passing the result back to the current activity; discussion does not authorize implementation. Do not pursue a complete blueprint for later work whose premises remain unsettled.

package/skills/discuss/SKILL.md

@@ -26,6 +26,8 @@ Identify which understanding is missing:
 - **What:** the problem or opportunity, desired result, accepted behavior, constraints, non-goals, and what would count as success.
 - **How:** the mechanism, dependencies, affected boundaries, tradeoffs, and evidence needed to produce that result in the actual environment.
 
+Use [Design for Depth](../design-for-depth/SKILL.md) when representation, identity, ownership, interfaces, algorithms, state, dependencies, or failure behavior materially shape the choice. If unresolved choices could materially change a technical recommendation or invalidate significant dependent work, read its Implementation Decisions method before recommending a mechanism. Use it to explain the differences that matter between viable approaches, not to turn ordinary discussion or a supported local change into an architecture exercise.
+
 These questions can be answered together. Reuse what remains supported instead of running two compulsory discovery passes. A detailed request may settle what while leaving how open; an investigation may reveal that the initial problem description was wrong.
 
 Keep supported facts and explicit decisions distinct from hypotheses, proposed mechanisms, and unresolved choices. Do not turn an assistant recommendation into a requirement because it is repeated or recorded.
@@ -57,8 +59,6 @@ Ask about priorities, behavior, constraints, and tradeoffs the user owns. Keep o
 
 Before recommending a new obligation, distinguish a requirement from a limitation of the current approach. Explain consequences in user terms: "requires changing and distributing a patched host," not merely "needs a provenance interface." Include a simpler in-scope alternative when one is supported. Do not weaken required behavior to make an approach look simpler.
 
-Use [Design for Depth](../design-for-depth/SKILL.md) when ownership, interfaces, state, dependencies, or failure behavior materially shape the choice. A lens is not a reason to design a broader system.
-
 ## Frame And Assess A Learning Action
 
 Use an experiment or prototype when existing evidence cannot settle a material question and exercising behavior can distinguish the remaining answers. A separate prototype should isolate the uncertainty more safely or economically than changing production; unfamiliarity alone does not require one.