@jaybeeuu/agent-cortex 1.41.1 → 1.43.0

package/docs/technical-direction/migration-execution-labels.md

@@ -13,14 +13,21 @@
 
 ## Current-state constraints
 
-- bd CLI is a global binary (`~/.local/bin/bd`); label ops: `bd label list-all [--json]`,
-  `bd list --label-pattern/regex [--json]`, `bd label add/remove` (batch multiple ids).
+- bd is a globally installed CLI resolved from `PATH` (whatever single `bd` is on PATH —
+  Homebrew, npm, or the install script); `BD_PATH` is the override for machines where `bd` is
+  not on PATH. Skill scripts invoke `BD_PATH || 'bd'` and never hardcode an install path.
+  Label ops: `bd label list-all [--json]`, `bd list --label-pattern/regex [--json]`,
+  `bd label add/remove` (batch multiple ids).
+- A `bd` whose install target has been removed (`~/.local/bin` orphans, dangling pnpm shims)
+  must not be pinned: it can be a schema behind the workspace DB and fail with a schema
+  version mismatch. Keep exactly one `bd` on PATH so `bd` and the DB version agree.
 - `bd list` supports `--label-pattern`/`--json`; `bd count` does NOT support `--label-pattern`.
 - `bd ready --label-pattern 'stage:*'` works; `bd ready -l execution:afk` verified.
-- 3 script packages exist with per-skill `package.json` + own `pnpm-workspace.yaml` +
-  own `pnpm-lock.yaml` (create-task, validate-agent-dir, run-pipeline-stage). They are NOT
-  members of the root workspace (root glob `skills/*/scripts` does not match the nested
-  `skills/<domain>/<name>/scripts`; root lockfile has zero refs to them).
+- 3 script packages still exist with their own `package.json` (create-task,
+  validate-agent-dir, run-pipeline-stage). They ARE root workspace members (root glob
+  `skills/**/scripts`; all three are in the root `pnpm-lock.yaml`). Residual per-skill
+  `pnpm-lock.yaml` (all three) and `pnpm-workspace.yaml` (validate-agent-dir,
+  run-pipeline-stage) are stale artefacts of the pre-D2 layout.
 - All 3 scripts are stdlib-only (`node:child_process`, `node:fs`, `node:path`, `node:url`).
 - Extensions (`extensions/skill-stats`) have real peer deps on `@earendil-works/pi-coding-agent`
   — they remain workspace members with their own package.json.
@@ -162,8 +169,9 @@
 
 ## References
 
-- Code evidence: `bin/agent-cortex.mjs` + `lib/cli.mjs` (CLI surface), `skills/*/scripts/
-  package.json` (3 orphaned), root `package.json` + `pnpm-workspace.yaml`, bd CLI help
-  (`bd list`, `bd label`, `bd create`), epic `agnt-ctx-s5xd` notes.
+- Code evidence: `bin/agent-cortex.mjs` + `lib/cli.mjs` (CLI surface),
+  `skills/*/*/scripts/package.json` (3, root workspace members), root `package.json` +
+  `pnpm-workspace.yaml`, bd CLI help (`bd list`, `bd label`, `bd create`), epic
+  `agnt-ctx-s5xd` notes.
 - Idea file: `docs/ideas/ctx-alias-version-and-update-commands.md` (ctx alias + version/update
   surface that `migrate` joins).

package/extensions/agent-modes/discover.test.ts

@@ -244,6 +244,25 @@ describe("discoverAgents (flat fallback)", () => {
     assert.deepEqual(strategy.tools, ["bash", "fetch_content", "read"]);
     assert.match(strategy.prompt, /Flat body of strategy\./);
   });
+  it("reads a space-separated scalar tools list instead of falling back to defaults", () => {
+    const fx = track(makeFixture());
+    writeFlatAgent(fx, "ralph", FLAT_FRONTMATTER("ralph", '"bash read grep task"'));
+
+    const agents = discoverAgents(fx.agentsDir, REAL_TOKEN_MAP);
+
+    // A collapsed scalar would land on DEFAULT_TOOLS, lifting the restriction
+    // rather than applying it — the tool names must survive the parse.
+    assert.deepEqual(agents[0].tools, ["bash", "grep", "read", "task"]);
+  });
+
+  it("reads a comma-separated scalar tools list", () => {
+    const fx = track(makeFixture());
+    writeFlatAgent(fx, "ralph", FLAT_FRONTMATTER("ralph", '"bash, view, task"'));
+
+    const agents = discoverAgents(fx.agentsDir, REAL_TOKEN_MAP);
+
+    assert.deepEqual(agents[0].tools, ["bash", "read", "task"]);
+  });
 });
 
 // ─── loadTokenMap ────────────────────────────────────────────────────────────

package/extensions/agent-modes/discover.ts

@@ -290,6 +290,21 @@ interface FlatParsed {
   prompt: string;
 }
 
+/**
+ * Split a scalar `tools` value into tool names.
+ *
+ * Accepts the quoted string the pi installer renders (`tools: "bash, read"`)
+ * as well as an unquoted whitespace-separated list (`tools: bash read`).
+ * Commas alone are not enough: a whitespace-separated list would collapse to
+ * one bogus name and the agent would run with no usable tool allowlist.
+ */
+function splitToolList(raw: string): string[] {
+  return raw
+    .replace(/^["']|["']$/g, "")
+    .split(/[,\s]+/)
+    .filter(Boolean);
+}
+
 function parseFlatFrontmatter(raw: string): FlatParsed {
   const lines = raw.split(/\r?\n/);
   if (lines[0] !== "---") return { prompt: raw };
@@ -327,11 +342,16 @@ function parseFlatFrontmatter(raw: string): FlatParsed {
   }
 
   // Parse tools from the tools frontmatter.
-  // Supports two formats:
-  //   tools: ["bash", "view"]        (JSON array, single line)
-  //   tools:                         (YAML list, subsequent lines)
+  // Supports three formats:
+  //   tools: ["bash", "view"]          (JSON array, single line)
+  //   tools: "bash, view"              (scalar list, comma or whitespace separated)
+  //   tools:                           (YAML list, subsequent lines)
   //     - bash
   //     - view
+  //
+  // The scalar form is what the pi installer renders for generated agents, so
+  // it must be read here rather than dropped to DEFAULT_TOOLS (which lifts the
+  // restriction instead of applying it).
   let inToolsBlock = false;
   for (const line of yamlLines) {
     const trimmed = line.trim();
@@ -354,6 +374,8 @@ function parseFlatFrontmatter(raw: string): FlatParsed {
           tools = [];
           continue;
         }
+        tools = splitToolList(val);
+        continue;
       }
     }
 

package/extensions/session-start/README.md

@@ -0,0 +1,38 @@
+# session-start
+
+A PI extension that injects, at the start of every session, the project's context files:
+
+- `AGENTS.md`
+- `docs/user-preferences.md`
+
+Paths are relative to the session working directory (`ctx.cwd`); missing or empty files are
+skipped. Content is injected as a hidden `session-start` message on `before_agent_start`, so it
+reaches the model without cluttering the transcript UI.
+
+## No skill list here — on purpose
+
+Earlier versions of this extension appended a hand-written blurb advertising three skills with
+`/skill:<name>` syntax. Both halves were wrong:
+
+- pi has no `/skill:` resolver — nothing maps that token to a read. Skills are used by reading
+  the `SKILL.md` path that pi lists.
+- pi's own system prompt already lists **every** discovered skill with its absolute `SKILL.md`
+  path, so a local three-skill list was incomplete and drifted from `skills/` silently.
+
+The blurb is gone and `index.test.ts` pins the absence of both `/skill:` syntax and hardcoded
+skill names. Keep the authoritative list in `skills/`; do not reintroduce it here.
+
+## Installation
+
+Bundled with the `agent-cortex` PI package — install the package for auto-discovery:
+
+```bash
+pi install git:https://github.com/jaybeeuu/agent-cortex
+```
+
+## Development
+
+```bash
+pnpm --filter @agent-cortex/session-start test
+pnpm --filter @agent-cortex/session-start typecheck
+```

package/extensions/session-start/index.test.ts

@@ -0,0 +1,122 @@
+import { after, before, describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import sessionStartExtension from "./index.ts";
+
+// ─── Harness ─────────────────────────────────────────────────────────────────
+
+interface InjectedMessage {
+  customType: string;
+  content: string;
+  display: boolean;
+}
+
+/** A handler recorded from `pi.on`, invoked via Reflect.apply so its exact
+ *  overload signature does not leak into the fake. */
+type RecordedHandler = (...args: never[]) => unknown;
+
+interface FakePi {
+  pi: ExtensionAPI;
+  /** Simulate pi dispatching `before_agent_start` and return the injected message. */
+  start(cwd: string): Promise<InjectedMessage | undefined>;
+}
+
+function createFakePi(): FakePi {
+  const handlers = new Map<string, RecordedHandler[]>();
+
+  const pi: ExtensionAPI = {
+    on: (event: string, handler: RecordedHandler) => {
+      const list = handlers.get(event) ?? [];
+      list.push(handler);
+      handlers.set(event, list);
+    },
+  } as unknown as ExtensionAPI;
+
+  return {
+    pi,
+    async start(cwd) {
+      const handler = handlers.get("before_agent_start")?.[0];
+      assert.ok(handler, "session-start should register a before_agent_start handler");
+      const run = handler as unknown as (
+        event: unknown,
+        ctx: { cwd: string },
+      ) => Promise<{ message?: InjectedMessage } | undefined>;
+      const result = await run({}, { cwd });
+      return result?.message;
+    },
+  };
+}
+
+/** Run one simulated session start against `cwd` and return the injected text. */
+async function inject(cwd: string): Promise<string | undefined> {
+  const fake = createFakePi();
+  sessionStartExtension(fake.pi);
+  const message = await fake.start(cwd);
+  return message?.content;
+}
+
+// ─── Fixtures ────────────────────────────────────────────────────────────────
+
+const AGENTS_MD = "# AGENTS\n\nProject instructions live here.";
+const PREFERENCES_MD = "# User Preferences\n\nPrefer pnpm over npm.";
+
+describe("session-start injection", () => {
+  let emptyProject: string;
+  let fullProject: string;
+
+  before(() => {
+    emptyProject = mkdtempSync(join(tmpdir(), "session-start-empty-"));
+    fullProject = mkdtempSync(join(tmpdir(), "session-start-full-"));
+    writeFileSync(join(fullProject, "AGENTS.md"), AGENTS_MD, "utf-8");
+    mkdirSync(join(fullProject, "docs"), { recursive: true });
+    writeFileSync(join(fullProject, "docs", "user-preferences.md"), PREFERENCES_MD, "utf-8");
+  });
+
+  after(() => {
+    rmSync(emptyProject, { recursive: true, force: true });
+    rmSync(fullProject, { recursive: true, force: true });
+  });
+
+  it("injects AGENTS.md and docs/user-preferences.md content", async () => {
+    const content = await inject(fullProject);
+    assert.ok(content, "expected the context files to be injected");
+    assert.match(content, /--- AGENTS\.md ---/);
+    assert.match(content, /Project instructions live here\./);
+    assert.match(content, /--- user-preferences\.md ---/);
+    assert.match(content, /Prefer pnpm over npm\./);
+  });
+
+  it("marks the injected message as a hidden session-start message", async () => {
+    const fake = createFakePi();
+    sessionStartExtension(fake.pi);
+    const message = await fake.start(fullProject);
+
+    assert.ok(message);
+    assert.equal(message.customType, "session-start");
+    assert.equal(message.display, false);
+  });
+
+  it("injects nothing for a project without context files", async () => {
+    const content = await inject(emptyProject);
+    assert.equal(content, undefined, "no context files means no injected message");
+  });
+
+  it("never advertises skills with pi-unresolvable /skill: syntax", async () => {
+    const content = await inject(fullProject);
+    assert.ok(content);
+    assert.ok(!content.includes("/skill:"), "pi has no /skill: resolver — drop the hint blurb");
+  });
+
+  it("never enumerates a fixed subset of skill names", async () => {
+    // pi's system prompt already lists every discovered skill with its SKILL.md
+    // path; a hand-maintained subset here drifts from skills/ silently.
+    const content = (await inject(fullProject)) ?? "";
+    for (const skill of ["using-agent-skills", "bd-tool", "git-workflow"]) {
+      assert.ok(!content.includes(skill), `${skill} should not be hardcoded in session-start`);
+    }
+  });
+});

package/extensions/session-start/index.ts

@@ -0,0 +1,27 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadSessionContext } from "../lib/context-loader.ts";
+
+/**
+ * Session-start extension.
+ *
+ * Injects the project context files (AGENTS.md, docs/user-preferences.md) at
+ * the start of every PI session.
+ *
+ * It deliberately injects nothing about skills: pi's own system prompt already
+ * lists every discovered skill with the absolute path to its SKILL.md, so a
+ * local copy is incomplete by construction and drifts from `skills/` silently.
+ */
+export default function (pi: ExtensionAPI) {
+  pi.on("before_agent_start", async (_event, ctx) => {
+    const contextFiles = loadSessionContext(ctx.cwd);
+    if (!contextFiles) return;
+
+    return {
+      message: {
+        customType: "session-start",
+        content: contextFiles,
+        display: false,
+      },
+    };
+  });
+}

package/extensions/session-start/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@agent-cortex/session-start",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "node --test --import tsx/esm index.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.78.1"
+  }
+}

package/extensions/session-start/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "strict": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "skipLibCheck": true
+  },
+  "include": ["*.ts"]
+}

package/extensions/subagent/README.md

@@ -58,7 +58,7 @@ This tool executes a separate `pi` subprocess with a delegated system prompt and
 
 **Project-local agents** (`.pi/agents/*.md`) are repo-controlled prompts that can instruct the model to read files, run bash commands, etc.
 
-**Default behavior:** Only loads **user-level agents** from `~/.pi/agent/agents`.
+**Default behavior:** Only loads **user-level agents** — pi's own `~/.pi/agent/agents`, plus the `agents/` tree of the package this extension ships inside when that is a rendered (staged) tree, e.g. `~/.agent-cortex/pi/agents` after `agent-cortex install pi`.
 
 To enable project-local agents, pass `agentScope: "both"` (or `"project"`). Only do this for repositories you trust.
 

package/extensions/subagent/agents.test.ts

@@ -0,0 +1,176 @@
+/**
+ * Subagent agent discovery — the directories the "user" scope reads.
+ *
+ * pi has no agent resource type: agents ship beside the extensions that serve
+ * them, so user-scope discovery covers pi's own user agent dir (hand-written
+ * personal agents, plus copies older installers made) and the package this
+ * extension ships inside. `agent-cortex install pi` renders the flat pi agents
+ * into `<package>/agents`; a source checkout keeps its composable tree there
+ * instead, plus flat renders for other harnesses, which are not pi's agents.
+ */
+
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { describe, it } from "node:test";
+import { fileURLToPath } from "node:url";
+import { discoverAgents, loadUserAgents, parseToolList, resolveUserAgentDirs } from "./agents.ts";
+
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+/** Write a flat agent file the way a renderer does: frontmatter plus body. */
+function writeAgent(dir: string, name: string, body = `# ${name}\n`): string {
+	const filePath = join(dir, `${name}.agent.md`);
+	mkdirSync(dir, { recursive: true });
+	writeFileSync(filePath, `---\nname: "${name}"\ndescription: "${name} agent"\n---\n\n${body}`);
+	return filePath;
+}
+
+/** Write a composable agent source dir: `<agentsDir>/<name>/agent.md`. */
+function writeComposableAgent(agentsDir: string, name: string): void {
+	const dir = join(agentsDir, name);
+	mkdirSync(dir, { recursive: true });
+	writeFileSync(join(dir, "agent.md"), `# ${name}\n`);
+}
+
+describe("resolveUserAgentDirs", () => {
+	it("reads the agents a staged package rendered beside the extension", () => {
+		const root = mkdtempSync(join(tmpdir(), "subagent-package-"));
+		try {
+			const shipped = writeAgent(join(root, "agents"), "ralph", "Staged ralph body.\n");
+
+			const dirs = resolveUserAgentDirs(root);
+
+			assert.ok(dirs.includes(join(root, "agents")), `expected ${join(root, "agents")} in ${dirs.join(", ")}`);
+			assert.equal(loadUserAgents(dirs).find((agent) => agent.name === "ralph")?.filePath, shipped);
+		} finally {
+			rmSync(root, { recursive: true, force: true });
+		}
+	});
+
+	it("leaves a source checkout's composable agents tree to the agent-modes extension", () => {
+		const root = mkdtempSync(join(tmpdir(), "subagent-checkout-"));
+		try {
+			writeComposableAgent(join(root, "agents"), "ralph");
+			writeAgent(join(root, "agents"), "ralph", "Copilot render.\n");
+
+			const dirs = resolveUserAgentDirs(root);
+
+			assert.ok(!dirs.includes(join(root, "agents")), `checkout agents dir must not be read: ${dirs.join(", ")}`);
+		} finally {
+			rmSync(root, { recursive: true, force: true });
+		}
+	});
+});
+
+describe("discoverAgents (user scope)", () => {
+	it("does not hand pi the flat renders this checkout holds for other harnesses", () => {
+		const { agents } = discoverAgents(tmpdir(), "user");
+
+		assert.ok(
+			agents.every((agent) => !agent.filePath.startsWith(join(PACKAGE_ROOT, "agents"))),
+			`checkout renders leaked into discovery: ${agents.map((agent) => agent.filePath).join(", ")}`,
+		);
+	});
+});
+
+describe("loadUserAgents", () => {
+	it("merges every dir and lets the earlier dir win a name collision", () => {
+		const root = mkdtempSync(join(tmpdir(), "subagent-agents-"));
+		try {
+			const personal = join(root, "pi", "agent", "agents");
+			const shipped = join(root, "package", "agents");
+			writeAgent(personal, "plan", "Personal plan body.\n");
+			writeAgent(personal, "personal-only", "Personal agent body.\n");
+			writeAgent(shipped, "plan", "Shipped plan body.\n");
+			writeAgent(shipped, "shipped-only", "Shipped agent body.\n");
+
+			const agents = loadUserAgents([personal, shipped]);
+
+			assert.deepEqual(
+				agents.map((agent) => agent.name).sort(),
+				["personal-only", "plan", "shipped-only"],
+			);
+			assert.equal(agents.find((agent) => agent.name === "plan")?.filePath, join(personal, "plan.agent.md"));
+		} finally {
+			rmSync(root, { recursive: true, force: true });
+		}
+	});
+
+	it("reads a tool list whether it is a YAML scalar or sequence", () => {
+		const root = mkdtempSync(join(tmpdir(), "subagent-agents-"));
+		try {
+			const shipped = join(root, "agents");
+			mkdirSync(shipped, { recursive: true });
+			writeFileSync(join(shipped, "scalar.agent.md"), `---\nname: "scalar"\ndescription: "d"\ntools: "bash, read"\n---\n\n# scalar\n`);
+			writeFileSync(join(shipped, "sequence.agent.md"), `---\nname: "sequence"\ndescription: "d"\ntools: ["bash", "read"]\n---\n\n# sequence\n`);
+
+			const tools = Object.fromEntries(loadUserAgents([shipped]).map((agent) => [agent.name, agent.tools]));
+
+			assert.deepEqual(tools, { scalar: ["bash", "read"], sequence: ["bash", "read"] });
+		} finally {
+			rmSync(root, { recursive: true, force: true });
+		}
+	});
+
+	it("ignores directories that do not exist", () => {
+		const root = mkdtempSync(join(tmpdir(), "subagent-agents-"));
+		try {
+			const shipped = join(root, "agents");
+			writeAgent(shipped, "ralph", "Shipped ralph body.\n");
+
+			const agents = loadUserAgents([join(root, "missing"), shipped]);
+
+			assert.deepEqual(
+				agents.map((agent) => agent.name),
+				["ralph"],
+			);
+		} finally {
+			rmSync(root, { recursive: true, force: true });
+		}
+	});
+});
+
+// The frontmatter `tools` value reaches this extension as one scalar string
+// (pi's parseFrontmatter does not split it) and is turned into `pi --tools`,
+// whose parser splits on commas. A whitespace-separated list used to collapse
+// into a single bogus name, producing an allowlist that matched no tool — the
+// delegated agent then started with an empty tool block (agnt-ctx-rpm3).
+
+describe("parseToolList", () => {
+	it("splits the comma-separated form", () => {
+		assert.deepEqual(parseToolList("bash, read, grep, find, task"), [
+			"bash",
+			"read",
+			"grep",
+			"find",
+			"task",
+		]);
+	});
+
+	it("splits the space-separated form instead of collapsing it to one name", () => {
+		assert.deepEqual(parseToolList("bash read grep find task"), [
+			"bash",
+			"read",
+			"grep",
+			"find",
+			"task",
+		]);
+	});
+
+	it("tolerates mixed and padded separators", () => {
+		assert.deepEqual(parseToolList("  bash,read   grep ,\ttask "), [
+			"bash",
+			"read",
+			"grep",
+			"task",
+		]);
+	});
+
+	it("returns undefined when there is no tool list", () => {
+		assert.equal(parseToolList(undefined), undefined);
+		assert.equal(parseToolList(""), undefined);
+		assert.equal(parseToolList("   "), undefined);
+	});
+});