@jaybeeuu/agent-cortex 2.3.0 → 2.4.1

package/extensions/subagent/components.ts

@@ -0,0 +1,182 @@
+/**
+ * Transcript components for the subagent tool's renderers.
+ *
+ * pi-tui's `Text`, `Container` and `Spacer` are not reachable from an installed
+ * extension: a value import of `@earendil-works/pi-tui` makes the extension fail
+ * to load outside the agent-cortex checkout (test/pi-extensions-load.test.mjs).
+ * These are the local equivalents, implementing the `Component` contract pi's
+ * transcript renderer calls: `render(width)` returns lines that fit `width`, and
+ * `invalidate()` drops cached layout.
+ *
+ * Two deliberate limits, because reimplementing pi-tui is not this change:
+ * markdown is drawn as plain text, and only SGR colour sequences (`ESC[…m`) are
+ * measured and carried across a wrapped line. Other escapes — OSC-8 hyperlinks,
+ * images — count as visible characters, the same way a naive strip does.
+ * Width is measured in terminal cells: a wide (East Asian) character, and any
+ * astral character such as an emoji, counts as two.
+ */
+
+/** Lines to draw at a given width — what pi's transcript renderer calls. */
+export interface Component {
+  render(width: number): string[];
+  invalidate(): void;
+}
+
+const SGR = /\x1b\[[0-9;]*m/g;
+const SGR_AT = /\x1b\[[0-9;]*m/y;
+const RESET = "\x1b[0m";
+
+/** A block of text, word-wrapped to the width it is drawn at. */
+export class Text implements Component {
+  readonly #text: string;
+  readonly #paddingX: number;
+  readonly #paddingY: number;
+
+  constructor(text = "", paddingX = 0, paddingY = 0) {
+    this.#text = text;
+    this.#paddingX = paddingX;
+    this.#paddingY = paddingY;
+  }
+
+  render(width: number): string[] {
+    const available = Math.max(1, width - this.#paddingX * 2);
+    const indent = " ".repeat(this.#paddingX);
+    const blank = indent.repeat(2);
+    const body = this.#text.split("\n").flatMap((line) => wrapLine(line, available));
+
+    return [
+      ...emptyLines(this.#paddingY, blank),
+      ...body.map((line) => `${indent}${line}${indent}`),
+      ...emptyLines(this.#paddingY, blank),
+    ];
+  }
+
+  invalidate(): void {}
+}
+
+/** Blank lines. */
+export class Spacer implements Component {
+  readonly #lines: number;
+
+  constructor(lines = 1) {
+    this.#lines = lines;
+  }
+
+  render(_width: number): string[] {
+    return emptyLines(this.#lines, "");
+  }
+
+  invalidate(): void {}
+}
+
+/** A vertical stack of components. */
+export class Container implements Component {
+  readonly #children: Component[] = [];
+
+  addChild(child: Component): void {
+    this.#children.push(child);
+  }
+
+  render(width: number): string[] {
+    return this.#children.flatMap((child) => child.render(width));
+  }
+
+  invalidate(): void {
+    for (const child of this.#children) child.invalidate();
+  }
+}
+
+/** `count` blank lines, each filled with `filler` (padding keeps the width). */
+function emptyLines(count: number, filler: string): string[] {
+  return Array.from({ length: Math.max(0, count) }, () => filler);
+}
+
+/** Visible cell count of a line: everything except SGR sequences, wide characters as two. */
+function visibleWidth(line: string): number {
+  let cells = 0;
+  for (const character of line.replace(SGR, "")) cells += cellWidth(character.codePointAt(0) ?? 0);
+  return cells;
+}
+
+/**
+ * Terminal cells one character occupies. Wide East Asian characters and astral
+ * characters (emoji included) occupy two; every other character occupies one.
+ * Counting in `String.length` units would let a wide character overflow: it is
+ * one unit but two cells.
+ */
+function cellWidth(codePoint: number): number {
+  if (codePoint > 0xffff) return 2;
+  return codePoint >= 0x1100 &&
+    (codePoint <= 0x115f ||
+      (codePoint >= 0x2e80 && codePoint <= 0xa4cf) ||
+      (codePoint >= 0xac00 && codePoint <= 0xd7a3) ||
+      (codePoint >= 0xf900 && codePoint <= 0xfaff) ||
+      (codePoint >= 0xfe30 && codePoint <= 0xfe6f) ||
+      (codePoint >= 0xff00 && codePoint <= 0xff60) ||
+      (codePoint >= 0xffe0 && codePoint <= 0xffe6))
+    ? 2
+    : 1;
+}
+
+/**
+ * Wrap one line to `width` visible columns without cutting an SGR sequence. A
+ * cut inside a coloured span closes the line and reopens the same colour on the
+ * continuation, so broken escapes never reach the terminal.
+ */
+function wrapLine(line: string, width: number): string[] {
+  const lines: string[] = [];
+  let rest = line;
+
+  while (visibleWidth(rest) > width) {
+    const cut = breakIndex(rest, width);
+    if (cut <= 0) break;
+
+    const head = rest.slice(0, cut);
+    const colour = lastColour(head);
+    lines.push(colour === "" ? head : `${head}${RESET}`);
+    // A break taken at a space consumes it, so the continuation starts with its word.
+    rest = `${colour}${rest.slice(rest[cut] === " " ? cut + 1 : cut)}`;
+  }
+
+  lines.push(rest);
+  return lines;
+}
+
+/**
+ * Index at which to cut `text` so its visible width stays within `width`:
+ * the last space at or before the limit, or the limit itself when the line has
+ * no usable space.
+ */
+function breakIndex(text: string, width: number): number {
+  let visible = 0;
+  let lastSpace = -1;
+  let index = 0;
+
+  while (index < text.length) {
+    SGR_AT.lastIndex = index;
+    const escape = SGR_AT.exec(text);
+    if (escape !== null) {
+      index += escape[0].length;
+      continue;
+    }
+
+    const codePoint = text.codePointAt(index) ?? 0;
+    const character = String.fromCodePoint(codePoint);
+    if (character === " ") lastSpace = index;
+    if (visible + cellWidth(codePoint) > width) return lastSpace > 0 ? lastSpace : index;
+
+    visible += cellWidth(codePoint);
+    index += character.length;
+  }
+
+  return lastSpace > 0 ? lastSpace : index;
+}
+
+/** The colour sequence left open at the end of `text`, or "" when none is. */
+function lastColour(text: string): string {
+  let colour = "";
+  for (const [sequence] of text.matchAll(SGR)) {
+    colour = sequence === RESET || sequence === "\x1b[m" ? "" : sequence;
+  }
+  return colour;
+}

package/extensions/subagent/frontmatter.test.ts

@@ -0,0 +1,74 @@
+/**
+ * The local frontmatter reader for agent files.
+ *
+ * pi's `parseFrontmatter` is unreachable from an installed extension, so this
+ * parser reads the subset agent files use. Agents are user-authored files at a
+ * system edge: a field this parser mishandles silently changes an agent's name,
+ * description or tool list, and an exception here would break discovery of every
+ * other agent, so both the parsing and the tolerance are covered.
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import { parseFrontmatter } from "./frontmatter.ts";
+
+describe("parseFrontmatter", () => {
+	it("splits fields from the body and trims the body", () => {
+		const { frontmatter, body } = parseFrontmatter(`---\nname: ralph\ndescription: d\n---\n\n# ralph\n`);
+
+		assert.deepEqual(frontmatter, { name: "ralph", description: "d" });
+		assert.equal(body, "# ralph");
+	});
+
+	it("reads a quoted scalar, unescaping it", () => {
+		const { frontmatter } = parseFrontmatter(`---\nname: "a: b\\"c\\n"\n---\n`);
+
+		assert.equal(frontmatter.name, 'a: b"c\n');
+	});
+
+	it("reads a flow sequence of quoted items", () => {
+		const { frontmatter } = parseFrontmatter(`---\ntools: ["bash", "read"]\n---\n`);
+
+		assert.deepEqual(frontmatter.tools, ["bash", "read"]);
+	});
+
+	it("reads a block sequence", () => {
+		const { frontmatter } = parseFrontmatter(`---\ntools:\n  - bash\n  - read\n---\n`);
+
+		assert.deepEqual(frontmatter.tools, ["bash", "read"]);
+	});
+
+	it("keeps a comma-separated tool list as one scalar", () => {
+		const { frontmatter } = parseFrontmatter(`---\ntools: "bash, read"\n---\n`);
+
+		assert.equal(frontmatter.tools, "bash, read");
+	});
+
+	it("separates fields from a following block sequence", () => {
+		const { frontmatter } = parseFrontmatter(`---\nname: ralph\ntools:\n  - bash\nmodel: fast\n---\n`);
+
+		assert.deepEqual(frontmatter, { name: "ralph", tools: ["bash"], model: "fast" });
+	});
+
+	it("normalises CRLF line endings", () => {
+		const { frontmatter, body } = parseFrontmatter(`---\r\nname: ralph\r\n---\r\n\r\nbody\r\n`);
+
+		assert.deepEqual(frontmatter, { name: "ralph" });
+		assert.equal(body, "body");
+	});
+
+	it("returns the whole document as body when there is no frontmatter", () => {
+		const { frontmatter, body } = parseFrontmatter("# just markdown\n");
+
+		assert.deepEqual(frontmatter, {});
+		assert.equal(body, "# just markdown\n");
+	});
+
+	it("treats an unclosed block as body rather than throwing", () => {
+		const { frontmatter, body } = parseFrontmatter(`---\nname: ralph\n`);
+
+		assert.deepEqual(frontmatter, {});
+		assert.equal(body, "---\nname: ralph\n");
+	});
+});

package/extensions/subagent/frontmatter.ts

@@ -0,0 +1,105 @@
+/**
+ * Read the YAML frontmatter block of a markdown document.
+ *
+ * pi's own `parseFrontmatter` is not reachable from an installed extension: a
+ * value import of `@earendil-works/pi-coding-agent` makes the extension fail to
+ * load outside the agent-cortex checkout (test/pi-extensions-load.test.mjs).
+ * This module is the subset agent files use — top-level `key: value` pairs,
+ * plain and quoted scalars, flow sequences (`[a, b]`) and block sequences
+ * (`- a`).
+ *
+ * Deliberately outside the subset: nested maps and block scalars (`|`, `>`) keep
+ * their literal text as the value. No construct throws — an unreadable block
+ * yields empty frontmatter — so one malformed agent file cannot break discovery
+ * of the others.
+ */
+
+/** A parsed document: its frontmatter fields and the markdown body. */
+export interface ParsedFrontmatter<T extends Record<string, unknown>> {
+  frontmatter: T;
+  body: string;
+}
+
+const FENCE = "---";
+
+/**
+ * Split a markdown document into frontmatter fields and body, matching pi's
+ * contract: the document must open with `---` and close the block with a line
+ * that starts with `---`; the body is trimmed.
+ */
+export function parseFrontmatter<T extends Record<string, unknown>>(content: string): ParsedFrontmatter<T> {
+  const normalized = content.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n");
+  const end = normalized.startsWith(FENCE) ? normalized.indexOf(`\n${FENCE}`, FENCE.length) : -1;
+  if (end === -1) return { frontmatter: {} as T, body: normalized };
+
+  return {
+    frontmatter: parseBlock(normalized.slice(FENCE.length + 1, end)) as T,
+    body: normalized.slice(end + FENCE.length + 1).trim(),
+  };
+}
+
+/** Parse the `key: value` lines of a frontmatter block. */
+function parseBlock(block: string): Record<string, unknown> {
+  const fields: Record<string, unknown> = {};
+  const lines = block.split("\n");
+
+  for (let index = 0; index < lines.length; index++) {
+    const match = /^([\w.-]+):(?:[ \t]+(.*))?$/.exec(lines[index]);
+    if (match === null) continue;
+
+    const [, key, inlineValue] = match;
+    if (inlineValue !== undefined && inlineValue.trim() !== "") {
+      fields[key] = parseValue(inlineValue.trim());
+      continue;
+    }
+
+    const { items, consumed } = readBlockSequence(lines, index + 1);
+    index += consumed;
+    fields[key] = items.length > 0 ? items : null;
+  }
+
+  return fields;
+}
+
+/**
+ * Read the indented `- item` lines that follow a `key:` line with no inline
+ * value. Returns the items and how many lines were consumed.
+ */
+function readBlockSequence(lines: string[], start: number): { items: string[]; consumed: number } {
+  const items: string[] = [];
+  let consumed = 0;
+
+  for (let index = start; index < lines.length; index++) {
+    const match = /^[ \t]+-[ \t]+(.*)$/.exec(lines[index]);
+    if (match === null) break;
+
+    const value = parseValue(match[1].trim());
+    items.push(typeof value === "string" ? value : String(value));
+    consumed++;
+  }
+
+  return { items, consumed };
+}
+
+/** Parse one scalar or flow sequence. */
+function parseValue(raw: string): unknown {
+  if (raw.startsWith("[") && raw.endsWith("]")) {
+    return raw
+      .slice(1, -1)
+      .split(",")
+      .map((item) => item.trim())
+      .filter(Boolean)
+      .map(parseValue);
+  }
+  if (raw.startsWith('"')) return unquote(raw, '"', (text) => text.replace(/\\(["\\/nrt])/g, (_, escape: string) => {
+    return escape === "n" ? "\n" : escape === "r" ? "\r" : escape === "t" ? "\t" : escape;
+  }));
+  if (raw.startsWith("'")) return unquote(raw, "'", (text) => text.replace(/''/g, "'"));
+  return raw;
+}
+
+/** Strip a matching quote pair and unescape the content; an unterminated quote keeps the raw text. */
+function unquote(raw: string, quote: string, unescape: (text: string) => string): string {
+  if (raw.length < 2 || !raw.endsWith(quote)) return raw;
+  return unescape(raw.slice(1, -1));
+}

package/extensions/subagent/index.ts

@@ -21,8 +21,13 @@ import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { Message } from "@earendil-works/pi-ai";
 import { type AgentConfig, type AgentScope, discoverAgents } from "./agents.ts";
 import { waitForAgents } from "./wait.ts";
-import { type ExtensionAPI, getMarkdownTheme, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
-import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Container, Spacer, Text } from "./components.ts";
+// `typebox` is the one bare runtime import an extension may make: pi documents
+// it as host-provided and its loader aliases it (pi's docs/packages.md), so it
+// resolves in the staged package too. Every `@earendil-works/*` import here is
+// `import type`, which is erased; a value import of pi's runtime breaks the
+// package outside this checkout (test/pi-extensions-load.test.mjs).
 import { Type } from "typebox";
 
 
@@ -236,9 +241,8 @@ async function writePromptToTempFile(agentName: string, prompt: string): Promise
 	const tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-subagent-"));
 	const safeName = agentName.replace(/[^\w.-]+/g, "_");
 	const filePath = path.join(tmpDir, `prompt-${safeName}.md`);
-	await withFileMutationQueue(filePath, async () => {
-		await fs.promises.writeFile(filePath, prompt, { encoding: "utf-8", mode: 0o600 });
-	});
+	// No mutation queue: the directory is fresh per call, so nothing else writes this file.
+	await fs.promises.writeFile(filePath, prompt, { encoding: "utf-8", mode: 0o600 });
 	return { dir: tmpDir, filePath };
 }
 
@@ -746,8 +750,6 @@ export default function (pi: ExtensionAPI) {
 				return new Text(text?.type === "text" ? text.text : "(no output)", 0, 0);
 			}
 
-			const mdTheme = getMarkdownTheme();
-
 			const renderDisplayItems = (items: DisplayItem[], limit?: number) => {
 				const toShow = limit ? items.slice(-limit) : items;
 				const skipped = limit && items.length > limit ? items.length - limit : 0;
@@ -798,7 +800,7 @@ export default function (pi: ExtensionAPI) {
 						}
 						if (finalOutput) {
 							container.addChild(new Spacer(1));
-							container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme));
+							container.addChild(new Text(finalOutput.trim(), 0, 0));
 						}
 					}
 					const usageStr = formatUsageStats(r.usage, r.model);
@@ -880,10 +882,10 @@ export default function (pi: ExtensionAPI) {
 							}
 						}
 
-						// Show final output as markdown
+						// Show final output as plain text
 						if (finalOutput) {
 							container.addChild(new Spacer(1));
-							container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme));
+							container.addChild(new Text(finalOutput.trim(), 0, 0));
 						}
 
 						const stepUsage = formatUsageStats(r.usage, r.model);
@@ -965,10 +967,10 @@ export default function (pi: ExtensionAPI) {
 							}
 						}
 
-						// Show final output as markdown
+						// Show final output as plain text
 						if (finalOutput) {
 							container.addChild(new Spacer(1));
-							container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme));
+							container.addChild(new Text(finalOutput.trim(), 0, 0));
 						}
 
 						const taskUsage = formatUsageStats(r.usage, r.model);

package/extensions/subagent/package.json

@@ -4,20 +4,19 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "test": "node --test --import tsx/esm wait.test.ts agents.test.ts",
+    "test": "node --test --import tsx/esm wait.test.ts agents.test.ts frontmatter.test.ts components.test.ts",
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
     "@earendil-works/pi-agent-core": "^0.78.1",
     "@earendil-works/pi-ai": "^0.78.1",
     "@earendil-works/pi-coding-agent": "^0.78.1",
-    "@earendil-works/pi-tui": "^0.78.1",
     "@types/node": "^22.0.0",
     "tsx": "^4.0.0",
     "typebox": "^1.1.38",
     "typescript": "^5.0.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.78.1"
+    "typebox": "*"
   }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaybeeuu/agent-cortex",
-  "version": "2.3.0",
+  "version": "2.4.1",
   "description": "Personal PI package with custom agents, skills, and extensions",
   "keywords": [
     "pi-package"

package/skills/planning/create-task/templates/review.md

@@ -16,21 +16,26 @@ Log stage start, security scan result, review outcome, and stage complete (see P
 
 ## Instructions
 **First**, invoke the `review-security` skill and run the scan against the changes. If the
-verdict is FAIL, set `REVIEW_OUTCOME: CHANGES_REQUESTED` immediately and list each finding
-as a required change — do not proceed with the quality review.
+verdict is FAIL, set `OUTCOME: BLOCKED` immediately and list each finding under
+`BLOCKING_ISSUES` — do not proceed with the quality review.
 
 **Then**, review the implementation for correctness, quality, and alignment with the task
 description and project conventions. Only flag genuine correctness issues or clear deviations
 from stated requirements — not stylistic preferences.
 
-End your response with a ---REPORT--- block:
+End your response with a ---REPORT--- block. The `run-pipeline-stage` skill's
+`prompts/stage-runner.md` holds the authoritative REPORT contract — if this block and that
+prompt differ, follow the prompt and correct this template.
 ---REPORT---
 BEAD_ID: <id>
-STAGE_COMPLETED: reviewing
+STAGE_COMPLETED: review
 SUMMARY: <2–3 sentence summary of what you reviewed>
 FILES_CHANGED: none
-REVIEW_OUTCOME: <APPROVED|CHANGES_REQUESTED>
-CHANGES_REQUESTED:       ← include only if REVIEW_OUTCOME is CHANGES_REQUESTED
-1. <required change>
-2. <required change>
+COMMIT: <sha, or "none" if this stage added no commit>
+PUSHED: <yes|no>
+PR: none
+OUTCOME: <SUCCESS|BLOCKED>
+BLOCKING_ISSUES:         ← include only if OUTCOME is BLOCKED; one numbered line per finding
+1. <path:line — what is wrong and what to fix>
+2. <path:line — what is wrong and what to fix>
 ---

package/skills/review/review-security/SKILL.md

@@ -54,7 +54,10 @@ bash "$(find ~ -path '*/agent-cortex/skills/review-security/scripts/install-gitl
 
 If the verdict is FAIL, report each finding as a required change. Do not proceed until secrets are removed.
 
-When running within a ralph review pipeline, the outcome is communicated through the `---REPORT---` block that ralph parses — set `REVIEW_OUTCOME: CHANGES_REQUESTED` in that block and list each finding under `CHANGES_REQUESTED` (see the review template at `skills/create-task/templates/review.md`).
+When running within a ralph review pipeline, the outcome is communicated through the
+`---REPORT---` block that ralph parses — set `OUTCOME: BLOCKED` in that block and list each
+finding under `BLOCKING_ISSUES` with its file and line (see the review template in the
+`create-task` skill's `templates/review.md`).
 
 ## Red Flags