@hassangameryt/freeflow 0.7.2 → 0.8.0

package/pi-extension/dist/compaction/results.js

@@ -0,0 +1,158 @@
+import { resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { estimateTokens } from "./carry.js";
+import { currentCycle } from "./harness.js";
+/**
+ * The result index: this cycle's larger tool results, each with an id the agent can carry by. Ids number tool results
+ * in branch order (r1, r2, ...), so they stay stable while the branch grows, and a result from an earlier cycle still
+ * resolves because its entry stays stored after compaction.
+ */
+const SIZE_FLOOR = 500;
+const MAX_ROWS = 40;
+/**
+ * The most tokens the rendered index can take: 40 rows of at most about 140 characters (an 80-character label plus
+ * id, tool, size and carried note) and a heading. Below the warning by more than this, the index cannot reach it.
+ */
+export const INDEX_TOKEN_BOUND = 2_000;
+/** Freeflow's own control calls: no evidence to carry, as routing's evidence selection also excludes them. */
+const CONTROL_TOOLS = new Set([
+  "freeflow_delegate",
+  "freeflow_return",
+  "freeflow_project",
+  "freeflow_unit",
+  "freeflow_compact",
+]);
+const resultText = (message) =>
+  (message?.content ?? [])
+    .map((part) => (part?.type === "text" ? part.text : part?.type === "image" ? "[image]" : ""))
+    .join("");
+function label(name, input) {
+  const firstLine = (text) =>
+    text
+      .split("\n")
+      .map((line) => line.trim())
+      .find(Boolean) ?? "";
+  const value =
+    typeof input?.command === "string"
+      ? input.command
+      : typeof input?.path === "string"
+        ? input.path
+        : typeof input?.url === "string"
+          ? input.url
+          : typeof input?.code === "string"
+            ? `script: ${firstLine(input.code)}`
+            : Array.isArray(input?.queries)
+              ? input.queries.join("; ")
+              : typeof input?.query === "string"
+                ? input.query
+                : name;
+  const line = firstLine(String(value));
+  return line.length > 80 ? `${line.slice(0, 77)}...` : line;
+}
+/** The Freeflow package root: reads of its skills, references and prompts are instructions, not work to carry. */
+const FREEFLOW_ROOT = fileURLToPath(new URL("../../../", import.meta.url));
+const INSTRUCTION_DIRS = ["capabilities", "skills", "runtime"].map((dir) => resolve(FREEFLOW_ROOT, dir) + sep);
+function isFreeflowInstruction(tool, input) {
+  if (tool !== "read" || typeof input?.path !== "string") return false;
+  const path = resolve(input.path);
+  return INSTRUCTION_DIRS.some((dir) => path.startsWith(dir));
+}
+/** Every tool result on the branch with its id, oldest first. */
+function allResults(branch) {
+  const calls = new Map();
+  const results = [];
+  for (const entry of branch) {
+    const message = entry?.type === "message" ? entry.message : undefined;
+    if (message?.role === "assistant")
+      for (const block of message.content ?? [])
+        if (block?.type === "toolCall") calls.set(block.id, { name: block.name, input: block.arguments });
+    if (message?.role !== "toolResult") continue;
+    const call = calls.get(message.toolCallId);
+    const text = resultText(message);
+    const tool = call?.name ?? message.toolName ?? "tool";
+    results.push({
+      id: `r${results.length + 1}`,
+      tool,
+      label: label(tool, call?.input),
+      tokens: estimateTokens(text),
+      text,
+      ...firstLineOf(tool, call?.input, message),
+      entry,
+      input: call?.input,
+    });
+  }
+  return results;
+}
+/** A text read of a file starts at its offset (Pi's read is 1-based); an image or failed read has no lines. */
+function firstLineOf(tool, input, message) {
+  if (tool !== "read" || typeof input?.path !== "string" || message?.isError) return {};
+  if ((message?.content ?? []).some((part) => part?.type === "image")) return {};
+  return { firstLine: Number.isInteger(input?.offset) && input.offset > 0 ? input.offset : 1 };
+}
+/** The first line of the read result in a session entry, for a result carried by routing ref. */
+export function resultFirstLine(branch, entryId) {
+  return allResults(branch).find((result) => result.entry?.id === entryId)?.firstLine;
+}
+export function resolveResult(branch, id) {
+  const found = allResults(branch).find((result) => result.id === id);
+  if (!found) return undefined;
+  const { entry: _entry, input: _input, ...result } = found;
+  return result;
+}
+/**
+ * The tool results of the work in progress, newest first: the current assignment's under Cognitive Routing (by
+ * routing ref), otherwise this cycle's (by r-id). Freeflow's control calls and reads of its own instructions are left
+ * out: they are how the agent works, not what it worked on.
+ */
+export function scopeResults(branch, assignment) {
+  const cycle = new Set(currentCycle(branch));
+  return allResults(branch)
+    .filter((result) => (assignment ? assignment.entryIds.has(result.entry.id) : cycle.has(result.entry)))
+    .filter((result) => !CONTROL_TOOLS.has(result.tool) && !isFreeflowInstruction(result.tool, result.input))
+    .reverse()
+    .map(({ entry, input, ...result }) => ({
+      ...result,
+      id: assignment ? `ctx:${entry.id}` : result.id,
+      entryId: entry.id,
+      ...(typeof input?.path === "string" ? { path: input.path } : {}),
+    }));
+}
+/** This cycle's results above the size floor, newest first, then results the last Freeflow compaction carried. */
+export function resultIndex(branch) {
+  const cycle = new Set(currentCycle(branch));
+  const results = allResults(branch);
+  const rows = results
+    .filter(
+      (result) =>
+        cycle.has(result.entry) &&
+        result.tokens >= SIZE_FLOOR &&
+        !CONTROL_TOOLS.has(result.tool) &&
+        !isFreeflowInstruction(result.tool, result.input),
+    )
+    .reverse()
+    .map(({ id, tool, label, tokens }) => ({ id, tool, label, tokens }));
+  const latest = [...branch].reverse().find((entry) => entry?.type === "compaction" && entry.details?.freeflow);
+  for (const item of latest?.details?.freeflow?.carried ?? []) {
+    if (item?.kind !== "result" || rows.some((row) => row.id === item.ref)) continue;
+    const result = results.find((each) => each.id === item.ref);
+    if (result)
+      rows.push({
+        id: result.id,
+        tool: result.tool,
+        label: result.label,
+        tokens: result.tokens,
+        firstCycle: item.firstCycle,
+      });
+  }
+  return rows.slice(0, MAX_ROWS);
+}
+export function renderIndex(rows) {
+  if (!rows.length) return "No tool results large enough to list; carry files by path.";
+  return [
+    "Results you can carry by id:",
+    ...rows.map(
+      (row) =>
+        `- ${row.id}  ${row.tool}  ${row.label}  ~${row.tokens} tokens${row.firstCycle ? `  (carried since cycle ${row.firstCycle})` : ""}`,
+    ),
+  ].join("\n");
+}

package/pi-extension/dist/compaction/thresholds.js

@@ -0,0 +1,35 @@
+/**
+ * When compaction is due. Pi compacts on its own once context passes the window minus its reserve, and stays as the
+ * fallback for a full context. Freeflow says "compact now" 25k tokens before that, leaving room to prepare after a
+ * safe point, and warns earlier still: at 70% of the window, and at least 20k tokens before "compact now", so the
+ * agent has room to reach a safe point first.
+ */
+export const DEFAULT_RESERVE_TOKENS = 16_384;
+const WARNING_SHARE = 0.7;
+const WARNING_LEAD = 20_000;
+const COMPACT_NOW_HEADROOM = 25_000;
+/** Pi's effective reserve for a model: its per-model override, else the ordinary setting, else Pi's default. */
+export function reserveTokens(settings, model) {
+  const compaction = settings?.compaction ?? {};
+  const override = model ? compaction.modelOverrides?.[`${model.provider}/${model.id}`] : undefined;
+  const value = override?.reserveTokens ?? compaction.reserveTokens;
+  return Number.isSafeInteger(value) && value >= 0 ? value : DEFAULT_RESERVE_TOKENS;
+}
+export function thresholds(window, reserve) {
+  const trigger = Math.max(0, window - reserve);
+  const compactNow = Math.max(0, trigger - COMPACT_NOW_HEADROOM);
+  return {
+    window,
+    trigger,
+    warning: Math.max(0, Math.min(Math.floor(window * WARNING_SHARE), compactNow - WARNING_LEAD)),
+    compactNow,
+  };
+}
+/** The strictest thresholds across models that may receive the full history (the active model and routing workers). */
+export function strictest(models, settings) {
+  const all = models
+    .filter((model) => typeof model?.contextWindow === "number" && model.contextWindow > 0)
+    .map((model) => thresholds(model.contextWindow, reserveTokens(settings, model)));
+  if (!all.length) return undefined;
+  return all.reduce((a, b) => (b.warning < a.warning ? b : a));
+}

package/pi-extension/dist/compaction/tool.js

@@ -0,0 +1,57 @@
+export const FREEFLOW_COMPACT = "freeflow_compact";
+const DESCRIPTION =
+  "Compact the conversation into a new cycle. Use only when Freeflow says compaction is due or the user asks, and read the compaction skill first. Pass your summary and what to carry; compaction happens at the end of this turn, and the run continues from the summary, the carried context and a recovery message.";
+/** Registered once, declared only while Freeflow compaction is effective (see applyCompactionTools). */
+export function registerCompactionTool(pi, controller) {
+  pi.registerTool({
+    name: FREEFLOW_COMPACT,
+    label: "Compact",
+    description: DESCRIPTION,
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        summary: {
+          type: "string",
+          description:
+            "The next cycle's working state, for a reader with none of this conversation. The compaction skill says what it must keep.",
+        },
+        carry: {
+          type: "array",
+          description:
+            "What to carry into the next cycle, within the budget the notice gives: files by path (read fresh at compaction, optional line ranges) and tool results by id from the notice's index.",
+          items: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              file: { type: "string" },
+              lines: { type: "array", items: { type: "integer" }, description: "[first, last], 1-based" },
+              result: {
+                type: "string",
+                description:
+                  "A tool result: its routing ref (such as ctx:1a2b3c4d) when Cognitive Routing is on, otherwise its id from the notice's list (such as r12)",
+              },
+            },
+          },
+        },
+      },
+      required: ["summary"],
+    },
+    // Callable from codemode scripts as well: agents that look for tools there first concluded, when it was missing,
+    // that they could not compact. The compaction still happens at the end of the turn, after the script returns.
+    exposure: "direct",
+    defaultActive: false,
+    executionMode: "sequential",
+    async execute(_id, params, _signal, _update, ctx) {
+      return { content: [{ type: "text", text: await controller.request(params, ctx) }] };
+    },
+  });
+}
+/** Declare or withdraw freeflow_compact when compaction's effective state changes, keeping other tools in place. */
+export function applyCompactionTools(pi, effective) {
+  if (typeof pi.getActiveTools !== "function" || typeof pi.setActiveTools !== "function") return;
+  const current = pi.getActiveTools();
+  const present = current.includes(FREEFLOW_COMPACT);
+  if (effective && !present) pi.setActiveTools([...current, FREEFLOW_COMPACT]);
+  if (!effective && present) pi.setActiveTools(current.filter((name) => name !== FREEFLOW_COMPACT));
+}

package/pi-extension/dist/host/branch.js

@@ -0,0 +1,13 @@
+// Keyed by the reader and its getBranch function, so a reader whose source is swapped is walked again.
+const cache = new WeakMap();
+export function cachedBranch(reader) {
+  if (!reader?.getBranch) return [];
+  // Without a leaf id the branch cannot be keyed; fall back to Pi's walk.
+  if (!reader.getLeafId) return reader.getBranch();
+  const leaf = reader.getLeafId();
+  const hit = cache.get(reader);
+  if (hit && hit.leaf === leaf && hit.source === reader.getBranch) return hit.branch;
+  const branch = Object.freeze([...reader.getBranch()]);
+  cache.set(reader, { leaf, source: reader.getBranch, branch });
+  return branch;
+}

package/pi-extension/dist/host/canonical.js

@@ -0,0 +1,12 @@
+const isObject = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+/** Deterministic JSON: object keys sorted, undefined properties omitted, so equal values serialize equally. */
+export function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (isObject(value))
+    return `{${Object.keys(value)
+      .filter((k) => value[k] !== undefined)
+      .sort()
+      .map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`)
+      .join(",")}}`;
+  return JSON.stringify(value) ?? "null";
+}

package/pi-extension/dist/host/catalog.js

@@ -0,0 +1,77 @@
+import { fileURLToPath } from "node:url";
+/**
+ * Freeflow's fixed command and skill surface: the commands it registers, the skills it lists to the model, and where
+ * their files live.
+ */
+export const WORKFLOW_COMMANDS = [
+  { command: "discuss", skill: "discuss" },
+  { command: "action-selection", skill: "action-selection" },
+  { command: "track-work", skill: "track-work" },
+  { command: "write-spec", skill: "write-spec" },
+  { command: "review-artifact", skill: "review-artifact" },
+  { command: "write-plan", skill: "write-plan" },
+  { command: "write-docs", skill: "write-docs" },
+  { command: "execute-work", skill: "execute-work" },
+  { command: "simplify-code", skill: "simplify-code" },
+  { command: "migration-work", skill: "migration-work" },
+  { command: "diagnose-failure", skill: "diagnose-failure" },
+  { command: "verify-work", skill: "verify-work" },
+  { command: "review-work", skill: "review-work" },
+  { command: "commit-work", skill: "commit-work" },
+  { command: "handoff", skill: "handoff" },
+  { command: "finish-branch", skill: "finish-branch" },
+  { command: "release-work", skill: "release-work" },
+  { command: "launch-work", skill: "launch-work" },
+  { command: "bypass", skill: "bypass" },
+];
+export const CONTRIBUTOR_COMMANDS = ["setup-freeflow", "write-skill", "evaluate-skill"];
+const FREEFLOW_MODEL_SKILL_NAMES = [
+  "action-selection",
+  "bypass",
+  "commit-work",
+  "decision-gate",
+  "migration-work",
+  "design-for-depth",
+  "diagnose-failure",
+  "discuss",
+  "evaluate-skill",
+  "execute-work",
+  "finish-branch",
+  "handoff",
+  "release-work",
+  "review-artifact",
+  "review-work",
+  "setup-freeflow",
+  "launch-work",
+  "simplify-code",
+  "track-work",
+  "verify-work",
+  "workflow",
+  "write-docs",
+  "write-plan",
+  "write-skill",
+  "write-spec",
+];
+export const STABLE_FREEFLOW_SURFACE = Object.freeze({
+  enabled: true,
+  cognitiveRouting: { effective: true },
+  toolExecution: { effective: true },
+  compaction: { effective: true },
+});
+export function freeflowSkillPath(skillName) {
+  return fileURLToPath(new URL(`../../../skills/${skillName}/SKILL.md`, import.meta.url));
+}
+export function freeflowCapabilitySkillPath(skillName) {
+  return fileURLToPath(new URL(`../../../capabilities/${skillName}/SKILL.md`, import.meta.url));
+}
+export function freeflowModelSkillPaths(capabilityState = undefined) {
+  const paths = FREEFLOW_MODEL_SKILL_NAMES.map((skillName) => freeflowSkillPath(skillName));
+  if (capabilityState?.cognitiveRouting?.effective === true)
+    paths.push(freeflowCapabilitySkillPath("cognitive-routing"));
+  if (capabilityState?.compaction?.effective === true) paths.push(freeflowCapabilitySkillPath("compaction"));
+  return paths;
+}
+export function skillPrompt(skill, args) {
+  const trimmed = args?.trim();
+  return trimmed ? `/skill:${skill}\n\n${trimmed}` : `/skill:${skill}`;
+}