@hassangameryt/freeflow 0.8.0 → 0.9.0

package/pi-extension/dist/ask-user/form.js

@@ -0,0 +1,250 @@
+import { Input, Key, matchesKey, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+const OWN_ANSWER = "Type my own answer";
+export class QuestionForm {
+  questions;
+  theme;
+  done;
+  requestRender;
+  options;
+  tab = 0;
+  cursor;
+  picked;
+  written = new Map();
+  notes = new Map();
+  answered = new Set();
+  mode = "choose";
+  input = new Input();
+  cache;
+  focusedValue = false;
+  constructor(questions, theme, done, requestRender = () => {}, options = {}) {
+    this.questions = questions;
+    this.theme = theme;
+    this.done = done;
+    this.requestRender = requestRender;
+    this.options = options;
+    this.cursor = questions.map(() => 0);
+    this.picked = questions.map(() => new Set());
+    this.input.onSubmit = (value) => this.submitInput(value);
+    this.input.onEscape = () => this.leaveInput();
+  }
+  get focused() {
+    return this.focusedValue;
+  }
+  set focused(value) {
+    this.focusedValue = value;
+    this.input.focused = value && this.mode !== "choose";
+  }
+  get many() {
+    return this.questions.length > 1;
+  }
+  get onSubmitTab() {
+    return this.many && this.tab === this.questions.length;
+  }
+  get ownAnswer() {
+    return this.options.ownAnswer !== false;
+  }
+  rows(index) {
+    return this.questions[index].options.length + (this.ownAnswer ? 1 : 0);
+  }
+  refresh() {
+    this.cache = undefined;
+    this.requestRender();
+  }
+  finish() {
+    const answers = this.questions.map((question, index) => {
+      const note = this.notes.get(index);
+      const text = this.written.get(index);
+      return {
+        header: question.header,
+        question: question.question,
+        selected:
+          text === undefined
+            ? [...this.picked[index]].sort((a, b) => a - b).map((at) => question.options[at].label)
+            : [],
+        ...(text === undefined ? {} : { text }),
+        ...(note ? { note } : {}),
+      };
+    });
+    this.done({ status: "answered", answers });
+  }
+  /** After a question is answered: the next unanswered question, the Submit tab, or done for a single question. */
+  advance() {
+    this.answered.add(this.tab);
+    if (!this.many) return this.finish();
+    const next = this.questions.findIndex((_, index) => !this.answered.has(index));
+    this.tab = next === -1 ? this.questions.length : next;
+    this.refresh();
+  }
+  submitInput(value) {
+    const text = value.trim();
+    if (this.mode === "own") {
+      if (!text) return;
+      this.written.set(this.tab, text);
+      this.picked[this.tab].clear();
+      this.leaveInput(false);
+      this.advance();
+      return;
+    }
+    if (text) this.notes.set(this.tab, text);
+    else this.notes.delete(this.tab);
+    this.leaveInput();
+  }
+  leaveInput(render = true) {
+    this.mode = "choose";
+    this.input.setValue("");
+    this.input.focused = false;
+    if (render) this.refresh();
+  }
+  enterInput(mode) {
+    this.mode = mode;
+    this.input.setValue(mode === "note" ? (this.notes.get(this.tab) ?? "") : (this.written.get(this.tab) ?? ""));
+    this.input.focused = this.focusedValue;
+    this.refresh();
+  }
+  handleInput(data) {
+    if (this.mode !== "choose") {
+      this.input.handleInput(data);
+      this.refresh();
+      return;
+    }
+    if (matchesKey(data, Key.escape)) return this.done({ status: "dismissed" });
+    if (this.many && (matchesKey(data, Key.tab) || matchesKey(data, Key.right))) {
+      this.tab = (this.tab + 1) % (this.questions.length + 1);
+      return this.refresh();
+    }
+    if (this.many && (matchesKey(data, Key.shift("tab")) || matchesKey(data, Key.left))) {
+      this.tab = (this.tab + this.questions.length) % (this.questions.length + 1);
+      return this.refresh();
+    }
+    if (this.onSubmitTab) {
+      if (matchesKey(data, Key.enter) && this.answered.size === this.questions.length) this.finish();
+      return;
+    }
+    const question = this.questions[this.tab];
+    const at = this.cursor[this.tab];
+    const own = at === question.options.length;
+    if (matchesKey(data, Key.up)) {
+      this.cursor[this.tab] = Math.max(0, at - 1);
+      return this.refresh();
+    }
+    if (matchesKey(data, Key.down)) {
+      this.cursor[this.tab] = Math.min(this.rows(this.tab) - 1, at + 1);
+      return this.refresh();
+    }
+    if (data === "n" && this.options.notes !== false) return this.enterInput("note");
+    if (question.multiSelect && data === " " && !own) {
+      const picked = this.picked[this.tab];
+      if (picked.has(at)) picked.delete(at);
+      else picked.add(at);
+      this.written.delete(this.tab);
+      this.answered.delete(this.tab);
+      return this.refresh();
+    }
+    if (matchesKey(data, Key.enter)) {
+      if (own) return this.enterInput("own");
+      const picked = this.picked[this.tab];
+      if (!question.multiSelect) {
+        picked.clear();
+        picked.add(at);
+      } else if (picked.size === 0) picked.add(at);
+      this.written.delete(this.tab);
+      this.advance();
+    }
+  }
+  invalidate() {
+    this.cache = undefined;
+  }
+  render(width) {
+    if (this.cache) return this.cache;
+    const t = this.theme;
+    const w = Math.max(1, width);
+    const lines = [];
+    const wrap = (prefix, text) => {
+      const indent = visibleWidth(prefix);
+      const body = wrapTextWithAnsi(text, Math.max(1, w - indent));
+      body.forEach((line, i) => lines.push(`${i === 0 ? prefix : " ".repeat(indent)}${line}`));
+    };
+    lines.push(t.fg("accent", "─".repeat(w)));
+    if (this.many) {
+      const tabs = this.questions.map((question, index) => {
+        const label = ` ${this.answered.has(index) ? "■" : "□"} ${question.header} `;
+        return index === this.tab
+          ? t.bold(t.fg("accent", label))
+          : t.fg(this.answered.has(index) ? "success" : "muted", label);
+      });
+      const ready = this.answered.size === this.questions.length;
+      const submit = " ✓ Submit ";
+      tabs.push(this.onSubmitTab ? t.bold(t.fg("accent", submit)) : t.fg(ready ? "success" : "dim", submit));
+      wrap(" ", tabs.join(" "));
+      lines.push("");
+    }
+    if (this.onSubmitTab) {
+      wrap(" ", t.bold("Your answers"));
+      lines.push("");
+      this.questions.forEach((question, index) => {
+        const text = this.written.get(index);
+        const chosen = [...this.picked[index]].map((at) => question.options[at].label).join(", ");
+        const answer =
+          text !== undefined ? `"${text}"` : this.answered.has(index) ? chosen : t.fg("warning", "not answered");
+        wrap(" ", `${t.fg("muted", `${question.header}:`)} ${answer}`);
+        const note = this.notes.get(index);
+        if (note) wrap("   ", t.fg("dim", `note: ${note}`));
+      });
+      lines.push("");
+      wrap(
+        " ",
+        this.answered.size === this.questions.length
+          ? t.fg("success", "Enter to submit")
+          : t.fg("warning", "Answer every question to submit"),
+      );
+    } else {
+      const index = this.tab;
+      const question = this.questions[index];
+      wrap(" ", `${t.fg("muted", `${question.header} ·`)} ${t.bold(question.question)}`);
+      lines.push("");
+      const rows = [...question.options, ...(this.ownAnswer ? [{ label: OWN_ANSWER }] : [])];
+      rows.forEach((option, at) => {
+        const own = at === question.options.length;
+        const here = at === this.cursor[index] && this.mode === "choose";
+        const mark = question.multiSelect && !own ? (this.picked[index].has(at) ? "[x] " : "[ ] ") : "";
+        const chosen = !question.multiSelect && !own && this.answered.has(index) && this.picked[index].has(at);
+        const label = `${at + 1}. ${mark}${option.label}${chosen ? " ✓" : ""}`;
+        wrap(here ? t.fg("accent", "› ") : "  ", here ? t.fg("accent", label) : label);
+        const description = own ? this.written.get(index) : option.description;
+        if (description) wrap("     ", t.fg("muted", own ? `"${description}"` : description));
+      });
+      const note = this.notes.get(index);
+      if (note && this.mode !== "note") {
+        lines.push("");
+        wrap(" ", t.fg("dim", `Note: ${note}`));
+      }
+      if (this.mode !== "choose") {
+        lines.push("");
+        wrap(" ", t.fg("muted", this.mode === "own" ? "Your answer:" : "Note for this question:"));
+        for (const line of this.input.render(Math.max(1, w - 2))) lines.push(` ${line}`);
+      }
+    }
+    lines.push("");
+    if (this.options.deadline !== undefined) {
+      const left = Math.max(0, Math.ceil((this.options.deadline - Date.now()) / 1000));
+      wrap(
+        " ",
+        t.fg("dim", `Closes in ${Math.floor(left / 60)}:${String(left % 60).padStart(2, "0")} without an answer`),
+      );
+    }
+    const help =
+      this.mode !== "choose"
+        ? "Enter to save · Esc to go back"
+        : [
+            "↑↓ move",
+            this.questions[this.tab]?.multiSelect ? "Space toggle · Enter confirm" : "Enter choose",
+            ...(this.options.notes !== false ? ["n note"] : []),
+            ...(this.many ? ["Tab next"] : []),
+            "Esc close without answering",
+          ].join(" · ");
+    wrap(" ", t.fg("dim", help));
+    lines.push(t.fg("accent", "─".repeat(w)));
+    this.cache = lines;
+    return lines;
+  }
+}

package/pi-extension/dist/ask-user/questions.js

@@ -0,0 +1,66 @@
+/*
+ * The questions ask_user puts to the user, and the answers it returns: Claude Code's AskUserQuestion shape (1-4
+ * questions, a short header each, 2-4 options with descriptions, multi-select), since models know it. Every question
+ * also accepts the user's own words and a note; the dialog adds those, the model never lists them.
+ */
+export const MAX_QUESTIONS = 4;
+export const MIN_OPTIONS = 2;
+export const MAX_OPTIONS = 4;
+export const MAX_HEADER = 12;
+const text = (value) => (typeof value === "string" ? value.trim() : "");
+/** The questions as given, or the first reason they cannot be asked. */
+export function validateQuestions(value) {
+  if (!Array.isArray(value) || value.length < 1 || value.length > MAX_QUESTIONS)
+    return { error: `Ask 1 to ${MAX_QUESTIONS} questions.` };
+  const questions = [];
+  const headers = new Set();
+  for (const [index, raw] of value.entries()) {
+    const at = `Question ${index + 1}`;
+    const question = text(raw?.question);
+    const header = text(raw?.header);
+    if (!question) return { error: `${at} has no question text.` };
+    if (!header || header.length > MAX_HEADER)
+      return { error: `${at} needs a header of 1 to ${MAX_HEADER} characters.` };
+    if (headers.has(header)) return { error: `${at} repeats the header "${header}".` };
+    headers.add(header);
+    const options = Array.isArray(raw?.options) ? raw.options : [];
+    if (options.length < MIN_OPTIONS || options.length > MAX_OPTIONS)
+      return { error: `${at} needs ${MIN_OPTIONS} to ${MAX_OPTIONS} options.` };
+    const labels = new Set();
+    const normalized = [];
+    for (const option of options) {
+      const label = text(option?.label);
+      if (!label) return { error: `${at} has an option with no label.` };
+      if (/^other\b/i.test(label))
+        return { error: `${at} lists "${label}": the dialog adds the user's own answer itself; remove it.` };
+      if (labels.has(label)) return { error: `${at} repeats the option "${label}".` };
+      labels.add(label);
+      const description = text(option?.description);
+      normalized.push(description ? { label, description } : { label });
+    }
+    questions.push({
+      question,
+      header,
+      options: normalized,
+      ...(raw?.multiSelect === true ? { multiSelect: true } : {}),
+    });
+  }
+  return { questions };
+}
+/** What the model reads after the dialog. */
+export function outcomeText(outcome) {
+  if (outcome.status === "unavailable") return `${outcome.reason} Ask in your reply and end your turn.`;
+  if (outcome.status === "dismissed")
+    return "The user closed the dialog without answering. Do not act on the choice: ask in your reply, or continue only with work that does not depend on it.";
+  const lines = ["The user answered in a dialog:"];
+  for (const answer of outcome.answers) {
+    lines.push(`- ${answer.header}: ${answer.question}`);
+    if (answer.text !== undefined) lines.push(`  Answer, in their words: ${answer.text}`);
+    else lines.push(`  Answer: ${answer.selected.join("; ")}`);
+    if (answer.note) lines.push(`  Note: ${answer.note}`);
+  }
+  lines.push(
+    "Each answer decides only its question. A note or written answer that asks something, sets a condition or asks for more information is not a decision: respond to it before acting.",
+  );
+  return lines.join("\n");
+}

package/pi-extension/dist/ask-user/tool.js

@@ -0,0 +1,124 @@
+import { Text } from "@earendil-works/pi-tui";
+import { firstLine, foldRow, paint } from "../host/rows.js";
+import { askUser } from "./ask.js";
+import { MAX_HEADER, MAX_OPTIONS, MAX_QUESTIONS, MIN_OPTIONS, outcomeText, validateQuestions } from "./questions.js";
+export const ASK_USER = "ask_user";
+const DESCRIPTION = [
+  "Ask the user in a dialog when a choice is theirs to make: what to do, which direction to take, whether to go beyond what they asked. The call waits for their answer.",
+  `Ask 1 to ${MAX_QUESTIONS} questions. Each has a full-sentence question, a header of at most ${MAX_HEADER} characters, and ${MIN_OPTIONS} to ${MAX_OPTIONS} options: a label of a few words and a description of what choosing it means. Put your recommended option first and end its label with "(Recommended)". Use multiSelect when the options are not exclusive. The dialog adds a field for the user's own answer and a note, so never list an "Other" option.`,
+  "Several questions in one call only when each is the user's and none depends on another's answer. Say any context the choice needs in your reply before calling: the dialog shows only the questions and options.",
+  "If the user closes the dialog or no one can answer it, the result says so: then ask in your reply.",
+].join("\n\n");
+// Pi adds a tool's guidelines to the system prompt's rules while the tool is active.
+const GUIDELINE =
+  "Use ask_user for a choice that is the user's to make, with the options that matter and your recommendation first; never for facts you can look up or work out.";
+const textOf = (result) =>
+  (result?.content ?? [])
+    .filter((part) => part?.type === "text")
+    .map((part) => part.text ?? "")
+    .join("\n");
+/** Registered once, declared only while Freeflow is effective outside subagents. */
+export function registerAskUserTool(pi, host) {
+  pi.registerTool({
+    name: ASK_USER,
+    label: "Question",
+    description: DESCRIPTION,
+    promptGuidelines: [GUIDELINE],
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        questions: {
+          type: "array",
+          minItems: 1,
+          maxItems: MAX_QUESTIONS,
+          items: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              question: { type: "string", description: "The full question, ending with a question mark." },
+              header: {
+                type: "string",
+                description: `A label of at most ${MAX_HEADER} characters, such as "Default".`,
+              },
+              options: {
+                type: "array",
+                minItems: MIN_OPTIONS,
+                maxItems: MAX_OPTIONS,
+                items: {
+                  type: "object",
+                  additionalProperties: false,
+                  properties: {
+                    label: { type: "string", description: "A few words; the recommended one first." },
+                    description: { type: "string", description: "What choosing it means, and its tradeoff." },
+                  },
+                  required: ["label", "description"],
+                },
+              },
+              multiSelect: { type: "boolean", description: "True when the user may choose more than one." },
+            },
+            required: ["question", "header", "options"],
+          },
+        },
+      },
+      required: ["questions"],
+    },
+    // It asks the user, so scripts must not call it, and its transcript views apply (see task_memory).
+    exposure: "model-only",
+    defaultActive: false,
+    executionMode: "sequential",
+    // One line each for what was asked and what the user answered; options and notes when expanded or short.
+    renderCall: (args, theme, context) => {
+      const questions = (Array.isArray(args?.questions) ? args.questions : []).filter((q) => q?.question);
+      const title = paint(theme, "toolTitle", "Question");
+      if (!questions.length) return new Text(title, 0, 0);
+      const head =
+        questions.length === 1
+          ? `${title} · ${paint(theme, "accent", String(questions[0].header ?? ""))}: ${firstLine(questions[0].question, 120)}`
+          : `${title} · ${questions.map((q) => paint(theme, "accent", String(q.header ?? ""))).join(", ")}`;
+      const body = questions.flatMap((q) => [
+        ...(questions.length > 1 ? [`${q.header}: ${q.question}`] : q.question.length > 120 ? [q.question] : []),
+        ...(Array.isArray(q.options) ? q.options : []).map(
+          (o) => `${questions.length > 1 ? "  " : ""}- ${o.label}${o.description ? ` — ${o.description}` : ""}`,
+        ),
+      ]);
+      return foldRow(head, context?.expanded === true ? body : [], context?.expanded === true, theme);
+    },
+    renderResult: (result, options, theme) => {
+      const outcome = result?.details?.outcome;
+      if (outcome?.status === "answered") {
+        const lines = outcome.answers.map(
+          (answer) =>
+            `${answer.header}: ${answer.text !== undefined ? `"${answer.text}"` : answer.selected.join(", ")}${answer.note ? ` (note: ${answer.note})` : ""}`,
+        );
+        const head = paint(theme, "success", lines.length === 1 ? `Answered · ${lines[0]}` : "Answered");
+        return foldRow(head, lines.length === 1 ? [] : lines, options?.expanded === true, theme);
+      }
+      if (outcome?.status === "dismissed")
+        return new Text(paint(theme, "warning", "Closed without answering (Esc)"), 0, 0);
+      return new Text(paint(theme, "warning", firstLine(textOf(result)) || "Not asked"), 0, 0);
+    },
+    async execute(_id, params, signal, _update, ctx) {
+      const refused = host.refusal(ctx);
+      const checked = validateQuestions(params?.questions);
+      let outcome;
+      if (refused) outcome = { status: "unavailable", reason: refused };
+      else if ("error" in checked)
+        return { content: [{ type: "text", text: checked.error }], details: {}, isError: true };
+      else outcome = await askUser(ctx, checked.questions, signal);
+      return {
+        content: [{ type: "text", text: refused ? refused : outcomeText(outcome) }],
+        details: { outcome },
+        ...(outcome.status === "answered" ? {} : { isError: true }),
+      };
+    },
+  });
+}
+/** Declare or withdraw ask_user, keeping other tools in place. */
+export function applyAskUserTool(pi, effective) {
+  if (typeof pi.getActiveTools !== "function" || typeof pi.setActiveTools !== "function") return;
+  const current = pi.getActiveTools();
+  const present = current.includes(ASK_USER);
+  if (effective && !present) pi.setActiveTools([...current, ASK_USER]);
+  if (!effective && present) pi.setActiveTools(current.filter((name) => name !== ASK_USER));
+}

package/pi-extension/dist/cognitive-routing/assembler.js

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { viewHoldsSkill } from "./bootstrap.js";
 import { estimateRequest } from "./budget.js";
 import { prepareView } from "./projection.js";
 import { annotateSources } from "./provenance.js";
@@ -92,12 +93,28 @@ export class ContextAssembler {
       this.session.projectionError ? `Evidence limitation: ${this.session.projectionError}` : "",
       attention
         ? recovery
-          ? `Assessment paused for attention; ordinary admitted history remains. ${selection.selected.length} sources remain selected. Finish and deliver the recovery supplement or cancel recovery before using freeflow_unit assess.`
-          : `Assessment paused for attention; ordinary admitted history remains. ${selection.selected.length} sources remain selected. Use freeflow_unit assess to restore the assessment.`
+          ? `Assessment paused for attention; ordinary admitted history remains. ${selection.selected.length} sources remain selected. Finish and deliver the recovery supplement or cancel recovery before using routing_unit assess.`
+          : `Assessment paused for attention; ordinary admitted history remains. ${selection.selected.length} sources remain selected. Use routing_unit assess to restore the assessment.`
         : "",
       a?.state === "returned" && recovery?.state !== "reading"
         ? "Worker ordinary task work has ended. Only supported handoff correction is permitted."
         : "",
+      // After a compaction the routing skill may be out of view, and Haiku 5.5 workers then answered as Coordinator
+      // and ended without returning; Coordinator saw only "outstanding" and waited (Task 008 S-005).
+      state.control === "automatic" && a?.state === "outstanding" && worker && state.profile === worker
+        ? `You are ${label(worker)}: carry out A${assignmentNumber} from its delegate_work contract, then hand it back with return_work. Coordinator receives nothing until you return.`
+        : "",
+      state.control === "automatic" && a?.state === "outstanding" && worker && state.profile === "coordinator"
+        ? `${label(worker)}'s run on A${assignmentNumber} ended without return_work, so nothing was handed back. Send it again with delegate_work replace, close the unit, or ask the user.`
+        : "",
+      // Worker calls reach the Coordinator as assistant turns; Haiku 5.5 took them for its own (Task 008 S-005).
+      state.profile === "coordinator" && state.assessment
+        ? "The worker's run appears in your view as assistant turns: those calls are the worker's, as the source provenance after the run says, not yours."
+        : "",
+      // Selected bodies are not re-sent with the return; they stay where the worker produced them (Task 004 S-005).
+      state.profile === "coordinator" && state.assessment && selection.selected.length
+        ? "Selected evidence is already in your view, in place in the worker's run: the source provenance after the run names each selected ref's call (its path or command) and marks it `task evidence`. Recover only evidence the assessment needs that is not there."
+        : "",
       isWorkerProfile(this.session.turn?.profile) &&
       a &&
       this.session.turn.basisUserEntryId !== this.session.workerBasis(state, a.id)
@@ -166,19 +183,19 @@ export class ContextAssembler {
         const data = entry.data?.data;
         if (data?.type === "assessment-suspended" && data.handoffId === state.assessment?.handoffId)
           suspension = data.reason;
+        // A recovery during user attention leaves that attention outstanding, as the reducer does.
         if (
           data?.type === "recovery-request-accepted" &&
-          data.recovery?.assessmentHandoffId === state.assessment?.handoffId
+          data.recovery?.assessmentHandoffId === state.assessment?.handoffId &&
+          suspension !== "user-attention"
         )
           suspension = "recovery";
-        // After a recovery the Coordinator resumes the view it last saw, since it made no requests while suspended:
-        // only a suspension it kept working through (user attention) leaves evidence new to it at the resume.
-        if (
-          data?.type === "assessment-resumed" &&
-          data.handoffId === state.assessment?.handoffId &&
-          suspension !== "recovery"
-        )
-          resumedAt = rank;
+        // After a recovery alone the Coordinator resumes the view it last saw, since it made no requests while
+        // suspended: only a suspension it kept working through (user attention) leaves evidence new to it at the resume.
+        if (data?.type === "assessment-resumed" && data.handoffId === state.assessment?.handoffId) {
+          if (suspension !== "recovery") resumedAt = rank;
+          suspension = undefined;
+        }
         if (data?.type === "return-accepted" || data?.type === "recovery-supplement-accepted")
           assessedSinceCompaction.add(data.handoff.assignmentId);
         if (data?.type !== "selection-changed") continue;
@@ -333,6 +350,12 @@ export class ContextAssembler {
         prepared = this.prepared("coordinator", input);
       }
       check(prepared.ready, "context_unavailable", prepared.problems.map((p) => p.detail).join("; "));
+      if (this.session.routingSkill)
+        this.session.turn.skillInView = viewHoldsSkill(
+          prepared.messages,
+          this.session.routingSkill,
+          this.session.turn.profile,
+        );
       // Only worker views record exposure; hashing every source for the Coordinator's view would be wasted.
       if (isWorkerProfile(this.session.turn.profile)) {
         const known = this.session.stateData().exposure;
@@ -384,6 +407,7 @@ function compactedInAssignment(branch, assignmentId) {
   const freeflow = [...branch].reverse().find((entry) => entry?.type === "compaction")?.details?.freeflow;
   return freeflow && !freeflow.fallback && freeflow.assignment === assignmentId ? freeflow.cycle : undefined;
 }
+const label = (profile) => profile.charAt(0).toUpperCase() + profile.slice(1);
 function workerCompaction(branch) {
   const latest = [...branch].reverse().find((entry) => entry?.type === "compaction");
   const freeflow = latest?.details?.freeflow;

package/pi-extension/dist/cognitive-routing/bootstrap.js

@@ -0,0 +1,90 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const ROLE_REFERENCES = { coordinator: "coordinator.md", worker: "worker.md" };
+function lines(path) {
+  return readFileSync(path, "utf8")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+/** A reference and its markers: its heading and its closing line. */
+function reference(path) {
+  if (!existsSync(path)) return undefined;
+  try {
+    const text = lines(path);
+    const first = text[0],
+      last = text.at(-1);
+    return first && last && first !== last ? { path, first, last } : undefined;
+  } catch {
+    return undefined;
+  }
+}
+/** The packaged skill, its role references and their markers, or undefined when the skill cannot be read: then nothing is gated on it. */
+export function findRoutingSkill(packageRoots) {
+  for (const root of packageRoots) {
+    const dir = join(root, "capabilities", "cognitive-routing");
+    const path = join(dir, "SKILL.md");
+    if (!existsSync(path)) continue;
+    try {
+      const text = lines(path);
+      // The frontmatter's name line, and the closing rule: together they show the whole body was read.
+      const first = text.find((line) => line.startsWith("name:"));
+      const last = text.at(-1);
+      if (!first || !last || first === last) continue;
+      const roles = {};
+      for (const role of Object.keys(ROLE_REFERENCES)) {
+        const found = reference(join(dir, "references", ROLE_REFERENCES[role]));
+        if (found) roles[role] = found;
+      }
+      return { path, first, last, roles };
+    } catch {}
+  }
+  return undefined;
+}
+/** The role reference a view's profile needs; `solo` needs none. */
+export function routingRole(view) {
+  if (view === "coordinator") return "coordinator";
+  if (view === "helper" || view === "executor") return "worker";
+  return undefined;
+}
+const SKILL = 1,
+  COORDINATOR = 2,
+  WORKER = 4;
+const ROLE_BIT = { coordinator: COORDINATOR, worker: WORKER };
+/** Which files each tool result holds, per skill. Renderings are shared across requests, so each is checked once. */
+const holds = new WeakMap();
+function holdsFile(file, text) {
+  return !!file && text.includes(file.first) && text.includes(file.last);
+}
+/** Whether a prepared view holds a complete read of the skill and of the reference for the view's profile. */
+export function viewHoldsSkill(messages, skill, view) {
+  const role = routingRole(view);
+  const need = SKILL | (role && skill.roles[role] ? ROLE_BIT[role] : 0);
+  let cache = holds.get(skill);
+  if (!cache) holds.set(skill, (cache = new WeakMap()));
+  let found = 0;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message?.role !== "toolResult" || typeof message !== "object") continue;
+    let bits = cache.get(message);
+    if (bits === undefined) {
+      const text = Array.isArray(message.content)
+        ? message.content.map((block) => (block?.type === "text" ? block.text : "")).join("\n")
+        : String(message.content ?? "");
+      bits =
+        (holdsFile(skill, text) ? SKILL : 0) |
+        (holdsFile(skill.roles.coordinator, text) ? COORDINATOR : 0) |
+        (holdsFile(skill.roles.worker, text) ? WORKER : 0);
+      cache.set(message, bits);
+    }
+    found |= bits;
+    if ((found & need) === need) return true;
+  }
+  return false;
+}
+/** The files a profile must have in view before its commands or edits: the skill, then its role's reference. */
+export function requiredReads(skill, view) {
+  const role = routingRole(view);
+  const ref = role ? skill.roles[role] : undefined;
+  return ref ? [skill.path, ref.path] : [skill.path];
+}

package/pi-extension/dist/cognitive-routing/config.js

@@ -6,12 +6,11 @@ export const pairFromProfile = (profile) => ({
   modelId: profile.model,
   thinking: profile.thinking,
 });
+/** The keys `cognitiveRouting` accepts; the settings test checks each has a /freeflow settings row. */
+export const COGNITIVE_ROUTING_KEYS = ["enabled", "delegation", "projection", "profiles"];
 function parseLayer(raw) {
   if (raw === undefined) return {};
-  if (
-    !isObject(raw) ||
-    Object.keys(raw).some((key) => !["enabled", "delegation", "projection", "profiles"].includes(key))
-  )
+  if (!isObject(raw) || Object.keys(raw).some((key) => !COGNITIVE_ROUTING_KEYS.includes(key)))
     throw new Error(
       "Routing requires the enabled/delegation/projection/profiles schema; experimental legacy configuration is not migrated.",
     );

package/pi-extension/dist/cognitive-routing/event-store.js

@@ -87,7 +87,10 @@ export class EventStore {
           const event = parseRoutingEvent(entry.data);
           const receipt = this.observed.get(eventKey(event));
           return (
-            receipt?.entryId === entry.id && receipt.eventId === event.eventId && receipt.value === eventValue(event)
+            receipt !== undefined &&
+            receipt.entryId === entry.id &&
+            receipt.eventId === event.eventId &&
+            receipt.value === eventValue(event)
           );
         })
       ) {