portable-agent-layer 0.70.0 → 0.72.0

package/src/tools/control-room/ui/signal.tsx

@@ -0,0 +1,161 @@
+import type { DueBadge, RatingPoint, SignalView } from "../data";
+import { percent, tenths } from "./format";
+import { Panel, Pending, useLoaded } from "./panel";
+
+const LOW_RATING = 3;
+const W = 320;
+const H = 72;
+const PAD = 4;
+
+function sparkPath(points: RatingPoint[]): {
+  line: string;
+  area: string;
+  xy: [number, number][];
+} {
+  if (points.length === 0) return { line: "", area: "", xy: [] };
+  const step = points.length > 1 ? (W - PAD * 2) / (points.length - 1) : 0;
+  const xy = points.map<[number, number]>((p, i) => [
+    PAD + i * step,
+    H - PAD - ((p.rating - 1) / 9) * (H - PAD * 2),
+  ]);
+  const line = xy
+    .map(([x, y], i) => `${i === 0 ? "M" : "L"}${x.toFixed(1)} ${y.toFixed(1)}`)
+    .join(" ");
+  const area = `${line} L${xy.at(-1)?.[0].toFixed(1)} ${H} L${xy[0][0].toFixed(1)} ${H} Z`;
+  return { line, area, xy };
+}
+
+function Sparkline({ points }: { points: RatingPoint[] }) {
+  const { line, area, xy } = sparkPath(points);
+  const last = xy.at(-1);
+  const midY = H - PAD - (4 / 9) * (H - PAD * 2);
+  return (
+    <svg
+      className="spark"
+      viewBox={`0 0 ${W} ${H}`}
+      preserveAspectRatio="none"
+      role="img"
+      aria-label="ratings"
+    >
+      <title>ratings, oldest to newest</title>
+      <defs>
+        <linearGradient id="sparkfill" x1="0" x2="0" y1="0" y2="1">
+          <stop offset="0" stopColor="#f0b14a" stopOpacity="0.28" />
+          <stop offset="1" stopColor="#f0b14a" stopOpacity="0" />
+        </linearGradient>
+      </defs>
+      <line className="rule" x1={PAD} x2={W - PAD} y1={midY} y2={midY} />
+      <path className="area" d={area} />
+      <path className="line" d={line} />
+      {points.map((p, i) =>
+        p.rating <= LOW_RATING ? (
+          <circle key={p.ts} className="low" cx={xy[i][0]} cy={xy[i][1]} r="2" />
+        ) : null
+      )}
+      {last && <circle className="last" cx={last[0]} cy={last[1]} r="3" />}
+    </svg>
+  );
+}
+
+function Figure({ value, label, tone }: { value: string; label: string; tone?: string }) {
+  return (
+    <div className="figure">
+      <div className={`value ${tone ?? ""}`}>{value}</div>
+      <div className="label">{label}</div>
+    </div>
+  );
+}
+
+const BADGE_LOOK: Record<DueBadge["state"], { row: string; tag: string }> = {
+  due: { row: "due", tag: "amber" },
+  clear: { row: "clear", tag: "good" },
+  "n/a": { row: "na", tag: "ghost" },
+};
+
+function Due({ name, badge }: { name: string; badge: DueBadge }) {
+  const look = BADGE_LOOK[badge.state];
+  return (
+    <div className={`due-row ${look.row}`}>
+      <span className={`tag ${look.tag}`}>{badge.state}</span>
+      <span className="detail">
+        {name}
+        {badge.detail ? ` — ${badge.detail}` : ""}
+      </span>
+    </div>
+  );
+}
+
+function ratingTone(avg: number): string {
+  if (avg < 5) return "bad";
+  if (avg >= 7) return "good";
+  return "";
+}
+
+export function Signal() {
+  const view = useLoaded<SignalView>("/api/signal");
+  return (
+    <Panel
+      index="02 · feedback"
+      title="Signal"
+      span={4}
+      order={1}
+      aside={
+        view.state === "ready" && view.data.synthesizedAt
+          ? `synthesised ${view.data.synthesizedAt.slice(0, 10)}`
+          : ""
+      }
+    >
+      <Pending value={view} />
+      {view.state === "ready" && (
+        <>
+          <div className="figures">
+            <Figure
+              value={view.data.ratings ? tenths(view.data.ratings.recentAvg) : "–"}
+              label="last 10"
+              tone={view.data.ratings ? ratingTone(view.data.ratings.recentAvg) : ""}
+            />
+            <Figure
+              value={view.data.ratings ? tenths(view.data.ratings.avg) : "–"}
+              label={`avg of ${view.data.ratings?.count ?? 0}`}
+            />
+            <Figure
+              value={view.data.ratings ? String(view.data.ratings.lowCount) : "–"}
+              label="low (≤3)"
+              tone={view.data.ratings && view.data.ratings.lowCount > 5 ? "bad" : ""}
+            />
+          </div>
+          {view.data.series.length > 0 ? (
+            <Sparkline points={view.data.series} />
+          ) : (
+            <div className="empty">No ratings yet.</div>
+          )}
+          <div className="spark-caption">
+            <span>last {view.data.series.length} ratings</span>
+            <span>{view.data.ratings?.trend ?? ""}</span>
+          </div>
+          <div className="figures" style={{ marginTop: 16 }}>
+            <Figure
+              value={
+                view.data.algorithm ? String(view.data.algorithm.reflectionCount) : "–"
+              }
+              label="reflections"
+            />
+            <Figure
+              value={view.data.algorithm ? percent(view.data.algorithm.passRate) : "–"}
+              label="criteria pass"
+            />
+            <Figure
+              value={view.data.algorithm ? tenths(view.data.algorithm.avgSentiment) : "–"}
+              label="sentiment"
+            />
+          </div>
+          <div className="due">
+            <Due name="learning analysis" badge={view.data.due.analysis} />
+            <Due name="algorithm review" badge={view.data.due.algorithmReview} />
+            <Due name="relationship reflect" badge={view.data.due.relationshipReflect} />
+          </div>
+        </>
+      )}
+    </Panel>
+  );
+}

package/src/tools/ledger/view.ts

@@ -40,6 +40,8 @@ export interface LedgerViewRow {
   change: string;
   outcome: string;
   reason?: string;
+  /** Present only on a blocked shell action, where the target is a directory. */
+  command?: string;
 }
 
 export interface LedgerView {
@@ -100,6 +102,7 @@ function toRow(entry: LedgerEntry, registry: ActorRegistryEntry[]): LedgerViewRo
     outcome: entry.outcome,
   };
   if (entry.reason) row.reason = entry.reason;
+  if (entry.command) row.command = entry.command;
   return row;
 }
 

package/src/tools/lib/algorithm-reflect.ts

@@ -0,0 +1,84 @@
+/**
+ * The shape of an algorithm reflection: what a LEARN phase records, and the
+ * defaults and clamps applied to whatever the CLI was handed.
+ *
+ * The tool around this is only ever spawned, so the stamping, the clamp and the
+ * scope default were reachable only through argv. They take their clock and
+ * their directory as parameters here, which is what makes them assertable.
+ */
+
+import { currentAttribution, type RecordAttribution } from "../../hooks/lib/actor";
+import { encodeAnchor } from "../../hooks/lib/anchor";
+
+const MIN_SENTIMENT = 1;
+const MAX_SENTIMENT = 10;
+const DEFAULT_SENTIMENT = 5;
+
+export interface AlgorithmReflection extends RecordAttribution {
+  timestamp: string;
+  cwd: string;
+  task: string;
+  criteria_count: number;
+  criteria_passed: number;
+  criteria_failed: number;
+  sentiment: number;
+  q1: string;
+  q2: string;
+  q3: string;
+  /** general = the improvement ideas generalize to the algorithm; task-specific = bound to this task. */
+  scope: "general" | "task-specific";
+}
+
+export interface ReflectionInput {
+  task: string;
+  q1: string;
+  q2: string;
+  q3: string;
+  criteria_count?: number;
+  criteria_passed?: number;
+  criteria_failed?: number;
+  sentiment?: number;
+  scope?: string;
+}
+
+/** An absent flag reads as its default; a non-numeric one reads as NaN, not zero. */
+export function intOr(value: string | undefined, fallback: number): number {
+  return Number.parseInt(value || String(fallback), 10);
+}
+
+export function clampSentiment(sentiment: number | undefined): number {
+  return Math.max(MIN_SENTIMENT, Math.min(MAX_SENTIMENT, sentiment ?? DEFAULT_SENTIMENT));
+}
+
+/**
+ * General is the ~94% case, so only an explicit "task-specific" opts out of
+ * algorithm-update's clustering — anything else, including a typo, stays general.
+ */
+export function scopeOf(scope: string | undefined): AlgorithmReflection["scope"] {
+  return scope === "task-specific" ? "task-specific" : "general";
+}
+
+export function buildReflection(
+  input: ReflectionInput,
+  now: Date = new Date(),
+  cwd: string = process.cwd()
+): AlgorithmReflection {
+  return {
+    timestamp: now.toISOString(),
+    cwd: encodeAnchor(cwd),
+    ...currentAttribution(),
+    task: input.task,
+    criteria_count: input.criteria_count ?? 0,
+    criteria_passed: input.criteria_passed ?? 0,
+    criteria_failed: input.criteria_failed ?? 0,
+    sentiment: clampSentiment(input.sentiment),
+    q1: input.q1,
+    q2: input.q2,
+    q3: input.q3,
+    scope: scopeOf(input.scope),
+  };
+}
+
+export function reflectionLine(reflection: AlgorithmReflection): string {
+  return `${JSON.stringify(reflection)}\n`;
+}

package/src/tools/lib/analyze-report.ts

@@ -0,0 +1,120 @@
+/**
+ * The learning-analysis report, as lines rather than as console output.
+ *
+ * The tool around it is spawned, so every judgement in here — which colour a
+ * rating average earns, whether an entry came from a failure or a learning,
+ * what is shown when there is nothing to show — was written straight into
+ * console.log and could not be read back by a test.
+ */
+
+import type { AnalysisResult } from "../../hooks/lib/graduation";
+
+type PatternGroup = AnalysisResult["candidates"][number];
+type AnalysisEntry = PatternGroup["entries"][number];
+type RatingsSummary = NonNullable<AnalysisResult["ratings"]>;
+
+const c = {
+  bold: (s: string) => `\x1b[1m${s}\x1b[0m`,
+  dim: (s: string) => `\x1b[2m${s}\x1b[0m`,
+  cyan: (s: string) => `\x1b[36m${s}\x1b[0m`,
+  yellow: (s: string) => `\x1b[33m${s}\x1b[0m`,
+  green: (s: string) => `\x1b[32m${s}\x1b[0m`,
+  red: (s: string) => `\x1b[31m${s}\x1b[0m`,
+  magenta: (s: string) => `\x1b[35m${s}\x1b[0m`,
+};
+
+const RULE = c.dim("─────────────────────────────────────────────────");
+
+/** Green from 7, red at 4 and below, amber for the band between them. */
+function averageColour(average: number) {
+  if (average >= 7) return c.green;
+  return average <= 4 ? c.red : c.yellow;
+}
+
+function ratingsLines(r: RatingsSummary): string[] {
+  const average = averageColour(r.average)(`${r.average.toFixed(1)}/10`);
+  const low = c.red(`Low (≤4): ${r.low.count}`);
+  const high = c.green(`High (≥7): ${r.high.count}`);
+  return [
+    `\n  ${c.bold("Ratings:")} ${average} avg (${r.total} total)`,
+    `  ${low} | ${high}`,
+  ];
+}
+
+/** The source string carries where the entry came from; the tag says which. */
+function entryLine(entry: AnalysisEntry, maxChars: number): string {
+  const kind = entry.source.startsWith("failure:") ? "failure" : "learning";
+  const tag = kind === "failure" ? c.red(`[${kind}]`) : c.yellow(`[${kind}]`);
+  return `    ${c.dim(entry.date || "unknown")} ${tag} ${entry.text.slice(0, maxChars)}`;
+}
+
+function headingOf(group: PatternGroup): string {
+  const domain = c.cyan(`[${group.domain}]`);
+  const count = c.bold(`${group.entries.length}x`);
+  return `  ${domain} ${count}`;
+}
+
+function fileLines(group: PatternGroup): string[] {
+  return group.entries.map((entry) => `    ${c.dim(entry.path)}`);
+}
+
+function candidateLines(candidate: PatternGroup): string[] {
+  const framePath = c.magenta(`memory/wisdom/frames/${candidate.domain}.md`);
+  return [
+    `${headingOf(candidate)} occurrences`,
+    "",
+    ...candidate.entries.map((entry) => entryLine(entry, 100)),
+    `\n  ${c.dim("Files:")}`,
+    ...fileLines(candidate),
+    "",
+    `  Target frame: ${framePath}`,
+    `  ${RULE}\n`,
+  ];
+}
+
+function emergingLines(group: PatternGroup): string[] {
+  return [
+    headingOf(group),
+    ...group.entries.map((entry) => entryLine(entry, 80)),
+    "  Files:",
+    ...fileLines(group),
+    "",
+  ];
+}
+
+export function reportLines(result: AnalysisResult): string[] {
+  const hasPatterns = result.candidates.length > 0 || result.emerging.length > 0;
+  if (!hasPatterns && result.ratings === null) {
+    return ["\n  No patterns or ratings data found.\n"];
+  }
+
+  const lines: string[] = [];
+
+  if (result.ratings) lines.push(...ratingsLines(result.ratings));
+
+  if (result.candidates.length > 0) {
+    const header = `Graduation Report — ${result.candidates.length} pattern(s) detected`;
+    lines.push(`\n  ${c.bold(c.green(header))}\n`, `  ${RULE}\n`);
+    for (const candidate of result.candidates) lines.push(...candidateLines(candidate));
+  }
+
+  if (result.emerging.length > 0) {
+    lines.push(`  ${c.bold(c.yellow("Emerging (2x — one more to graduate)"))}\n`);
+    for (const group of result.emerging) lines.push(...emergingLines(group));
+  }
+
+  if (result.recommendations.length > 0) {
+    lines.push(`  ${c.bold("Recommendations:")}\n`);
+    for (const rec of result.recommendations) lines.push(`    ${rec}`);
+    lines.push("");
+  }
+
+  if (result.candidates.length > 0) {
+    lines.push(
+      "  To crystallize: add a line to the wisdom frame file.",
+      `  Format: ${c.green("- Your principle here [CRYSTAL: 85%]")}\n`
+    );
+  }
+
+  return lines;
+}

package/src/tools/lib/handoff-note.ts

@@ -0,0 +1,88 @@
+/**
+ * The handoff store: what an unfinished session leaves behind for the next one,
+ * keyed by the directory the work happened in.
+ *
+ * The tool around this is only ever spawned, so the shape of an entry and the
+ * trim that keeps the file a working set were reachable only by running the CLI
+ * and reading the file back. Everything here takes the store it operates on and
+ * the clock it stamps with.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { ensureDir, paths } from "../../hooks/lib/paths";
+
+export interface HandoffEntry {
+  timestamp: string;
+  title: string;
+  status: "in-progress" | "completed";
+  handoff: string;
+  artifacts: string[];
+  source: "deliberate" | "auto";
+  /** What the work needs from the human before it can move — the one thing an agent cannot unblock. */
+  waitingOn?: string;
+}
+
+export interface NoteInput {
+  cwd: string;
+  title: string;
+  text: string;
+  done: boolean;
+  waitingOn?: string;
+}
+
+export type HandoffStore = Record<string, HandoffEntry>;
+
+/** The file is a working set, not an archive: the oldest keys fall off first. */
+const MAX_ENTRIES = 20;
+
+export function handoffFile(): string {
+  return resolve(ensureDir(paths.state()), "last-handoff.json");
+}
+
+export function parseHandoffs(content: string): HandoffStore {
+  try {
+    return JSON.parse(content) as HandoffStore;
+  } catch {
+    return {};
+  }
+}
+
+export function readHandoffs(file: string = handoffFile()): HandoffStore {
+  if (!existsSync(file)) return {};
+  try {
+    return parseHandoffs(readFileSync(file, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+export function trimHandoffs(handoffs: HandoffStore): HandoffStore {
+  const entries = Object.entries(handoffs);
+  if (entries.length <= MAX_ENTRIES) return handoffs;
+  return Object.fromEntries(entries.slice(-MAX_ENTRIES));
+}
+
+export const statusOf = (note: NoteInput): HandoffEntry["status"] =>
+  note.done ? "completed" : "in-progress";
+
+/** A closed session carries no waiting line, so the key is absent rather than empty. */
+export function entryFor(note: NoteInput, now: Date): HandoffEntry {
+  return {
+    timestamp: now.toISOString(),
+    title: note.title,
+    status: statusOf(note),
+    handoff: note.text,
+    artifacts: [],
+    source: "deliberate",
+    ...(note.waitingOn ? { waitingOn: note.waitingOn } : {}),
+  };
+}
+
+export function recordNote(
+  store: HandoffStore,
+  note: NoteInput,
+  now: Date
+): HandoffStore {
+  return trimHandoffs({ ...store, [note.cwd]: entryFor(note, now) });
+}

package/src/tools/lib/note-flags.ts

@@ -0,0 +1,59 @@
+/**
+ * The flags the relationship-note tool takes, turned into notes to append.
+ *
+ * The tool is only ever spawned, so the one judgement here — what counts as a
+ * usable confidence, and what an empty invocation should do — could not be
+ * asserted from a test. A bad confidence is a typo, and writing the note anyway
+ * under a default would record a claim nobody made.
+ */
+
+type NoteType = "O" | "W" | "Session";
+
+interface NoteDraft {
+  type: NoteType;
+  text: string;
+  confidence?: number;
+}
+
+export interface NoteFlags {
+  o?: string[];
+  w?: string[];
+  b?: string;
+  confidence?: string;
+}
+
+/** What an opinion is worth when the caller did not say. */
+export const DEFAULT_CONFIDENCE = 0.75;
+
+export type NoteFlagsResult = { notes: NoteDraft[] } | { error: string };
+
+/** parseArgs leaves it a string; anything outside 0–1 is a typo, not a value. */
+export function parseConfidence(raw: string | undefined): number | null {
+  if (raw === undefined) return DEFAULT_CONFIDENCE;
+  const value = Number.parseFloat(raw);
+  if (Number.isNaN(value) || value < 0 || value > 1) return null;
+  return value;
+}
+
+export function notesFromFlags(flags: NoteFlags): NoteFlagsResult {
+  const opinions = flags.o ?? [];
+  const facts = flags.w ?? [];
+  if (opinions.length === 0 && facts.length === 0 && !flags.b) {
+    return { error: "Required: at least one of --o, --w, --b" };
+  }
+
+  const notes: NoteDraft[] = [];
+
+  if (opinions.length > 0) {
+    const confidence = parseConfidence(flags.confidence);
+    if (confidence === null) {
+      return { error: "--confidence must be a number between 0.0 and 1.0" };
+    }
+    for (const text of opinions) notes.push({ type: "O", text, confidence });
+  }
+
+  for (const text of facts) notes.push({ type: "W", text });
+  if (flags.b) notes.push({ type: "Session", text: flags.b });
+
+  return { notes };
+}

package/src/tools/lib/project-isc.ts

@@ -0,0 +1,151 @@
+/**
+ * ISCs — the numbered criteria a project is judged against, stored as markdown
+ * lines inside a project's ISA.md.
+ *
+ * The tool that edits them is only ever spawned, so the line format, the
+ * escaping that keeps a multi-paragraph criterion on one line, and the archive
+ * bookkeeping were reachable only by running the CLI. Each function here takes
+ * the text it operates on, plus the clock it stamps with.
+ */
+
+export type IscStatus = "open" | "done" | "retired";
+
+export const ISC_BOX: Record<IscStatus, string> = {
+  open: "[ ]",
+  done: "[x]",
+  retired: "[~]",
+};
+
+export function statusFromBox(box: string): IscStatus {
+  if (box.toLowerCase() === "x") return "done";
+  if (box === "~") return "retired";
+  return "open";
+}
+
+export interface Isc {
+  id: number;
+  text: string;
+  status: IscStatus;
+}
+
+/**
+ * An ISC is one markdown line, so a newline in its text would end the record
+ * and strand every paragraph after it as unparseable debris. Backslashes are
+ * escaped first so that decoding a literal "\n" in a regex cannot be mistaken
+ * for the separator.
+ */
+export function encodeIscText(text: string): string {
+  return text
+    .replaceAll("\\", "\\\\")
+    .replaceAll("\r\n", "\n")
+    .replaceAll("\r", "\n")
+    .replaceAll("\n", "\\n");
+}
+
+const ISC_UNESCAPE: Record<string, string> = { n: "\n", "\\": "\\" };
+
+export function decodeIscText(stored: string): string {
+  return stored.replaceAll(/\\(.)/g, (whole, ch) => ISC_UNESCAPE[ch] ?? whole);
+}
+
+export function parseIscs(criteria: string): Isc[] {
+  const out: Isc[] = [];
+  for (const line of criteria.split("\n")) {
+    const m = new RegExp(/^-\s+\[( |x|~)\]\s+ISC-(\d+):\s+(.+)$/i).exec(line);
+    if (m)
+      out.push({
+        id: Number(m[2]),
+        text: decodeIscText(m[3].trim()),
+        status: statusFromBox(m[1]),
+      });
+  }
+  return out;
+}
+
+/**
+ * A full ISC line collapsed to a glanceable title for resume: cut at the first
+ * clause boundary, then hard-cap length. Full text stays reachable via show-isc.
+ */
+export function iscTitle(text: string): string {
+  const boundary = text.search(/; | — | \(|\. /);
+  const clause = (boundary > 0 ? text.slice(0, boundary) : text).trim();
+  return clause.length > 80 ? `${clause.slice(0, 79).trimEnd()}…` : clause;
+}
+
+/** Scans Criteria AND Changelog so an archived id can never be handed out again. */
+export function nextIscId(criteria: string, changelog: string): number {
+  const ids = [...parseIscs(criteria), ...parseIscs(changelog)].map((i) => i.id);
+  return ids.length > 0 ? Math.max(...ids) + 1 : 1;
+}
+
+export function removeIscLine(
+  section: string,
+  id: number
+): { line: string | null; rest: string } {
+  const lines = section.split("\n");
+  const idx = lines.findIndex((l) =>
+    new RegExp(String.raw`^-\s+\[[ x~]\]\s+ISC-${id}:`).test(l)
+  );
+  if (idx === -1) return { line: null, rest: section };
+  const [line] = lines.splice(idx, 1);
+  return {
+    line,
+    rest: lines
+      .join("\n")
+      .replace(/\n{3,}/g, "\n\n")
+      .trim(),
+  };
+}
+
+/**
+ * Drops any "### Archived <date>" heading whose block has no content left —
+ * e.g. after every ISC filed under that date has been reopened.
+ */
+export function dropEmptyArchiveHeadings(changelog: string): string {
+  const lines = changelog.split("\n");
+  const blockHasContent = (headingIdx: number): boolean => {
+    for (let j = headingIdx + 1; j < lines.length && !lines[j].startsWith("### "); j++) {
+      if (lines[j].trim() !== "") return true;
+    }
+    return false;
+  };
+  return lines
+    .filter((l, i) => !(/^### Archived /.test(l) && !blockHasContent(i)))
+    .join("\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+export function archiveLine(
+  changelog: string | undefined,
+  doneLine: string,
+  kind: "Archived" | "Retired" = "Archived",
+  now: Date = new Date()
+): string {
+  const heading = `### ${kind} ${now.toISOString().slice(0, 10)}`;
+  const base = (changelog ?? "").trim();
+  if (base.includes(heading)) return `${base}\n${doneLine}`;
+  return base ? `${base}\n\n${heading}\n${doneLine}` : `${heading}\n${doneLine}`;
+}
+
+export function selectIscs(
+  open: Isc[],
+  done: Isc[],
+  retired: Isc[],
+  flags: Set<string>
+): Isc[] {
+  if (flags.has("--all")) return [...open, ...done, ...retired];
+  if (flags.has("--closed")) return done;
+  if (flags.has("--retired")) return retired;
+  return open;
+}
+
+/** A filesystem-safe stem for a task's own ISA, kept unique by the clock. */
+export function taskSlug(title: string, now: number = Date.now()): string {
+  const sanitized = title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40);
+  return `${sanitized}-${now.toString(36)}`;
+}