@jaybeeuu/agent-cortex 2.8.0 → 2.10.0

package/agents/guppi/claude/frontmatter.json

@@ -0,0 +1,6 @@
+{
+  "name": "agent-cortex:guppi",
+  "description": "Resident prioritising collaborator for human-in-the-loop work. Recommends what to look at next from the committed strategy, then helps plan, grill, flesh out or hand off the chosen item. Use when asking 'what should I work on', choosing the next HITL item, or disagreeing with a priority.",
+  "tools": ["Bash", "Read", "Edit", "Write", "Grep", "Glob", "AskUserQuestion", "Task", "Skill"],
+  "argumentHint": "Guppi — what should I look at next?"
+}

package/agents/guppi/pi/frontmatter.json

@@ -0,0 +1,6 @@
+{
+  "name": "agent-cortex:guppi",
+  "description": "Resident prioritising collaborator for human-in-the-loop work. Recommends what to look at next from the committed strategy, then helps plan, grill, flesh out or hand off the chosen item. Use when asking 'what should I work on', choosing the next HITL item, or disagreeing with a priority.",
+  "tools": ["bash", "view", "edit", "create", "grep", "glob", "ask_user", "task", "read_agent", "skill", "interrupt_checkpoint", "interrupt_resume"],
+  "argumentHint": "Guppi — what should I look at next?"
+}

package/agents/plan/agent.md

@@ -6,6 +6,12 @@ You follow the **plan** skill workflow. The skill is defined in `{{PATH:skills/w
 
 ## Workflow summary
 
+### Phase 0 — Report the HITL queue
+1. Load the `hitl-queue` skill and report its queue exactly as the script prints it — before asking
+   the user anything, presenting a plan, or dispatching a task.
+2. Name the top item plainly: its id, its title, and what answering it unblocks. When nothing is
+   scored, report the unscored list and ask which bead to score rather than picking one by feel.
+
 ### Phase 1 — Understand and specify
 1. Ask the user to describe the problem, goal, or feature.
 2. Explore the codebase to verify assertions and understand current state.

package/agents/ralph-plan/agent.md

@@ -24,6 +24,12 @@ Do **not** write anywhere else. No source files, no READMEs, no tracked docs, no
 ### 1. Load context
 Invoke the **beads** skill (set workspace root, run `bd prime`). Hold the output in memory.
 
+Then report the HITL queue: load the **hitl-queue** skill, run its `queue` subcommand, and report
+the list exactly as the script prints it, naming the top item — its id, its title, and what
+answering it unblocks. It is the first thing the session says, before any sub-agent is dispatched
+or any plan is proposed. When nothing is scored, report the unscored list and ask which bead to
+score rather than picking one by feel.
+
 If the input looks like a PRD (product requirements document), invoke the **prd-to-tasks** skill first — it handles exploration, user quizzing, and creates epics and task beads directly. Then continue from step 7 (Agree with the user).
 
 ### 2. Understand the request

package/bin/installers/claude.mjs

@@ -75,6 +75,7 @@ import { homedir } from "node:os";
 import { composeAgent, loadTokenMap, substituteTokens } from "../../scripts/lib/compose-agent.mjs";
 import { installDocs } from "../../scripts/lib/docs.mjs";
 import { isDirectory, isFile } from "../../scripts/lib/fs.mjs";
+import { normaliseRepository } from "../../scripts/lib/manifest.mjs";
 import { flattenSkillLinks } from "../../scripts/lib/skill-links.mjs";
 
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
@@ -155,10 +156,14 @@ function byName(a, b) {
 
 /**
  * Compose every agent from agents/<name>/ — all harnesses share the composable sources.
+ * `{{PATH:...}}` rows resolve against the plugin root, as they do in skills: a bare
+ * relative path would name a file relative to the reader's working directory, and the
+ * install ships the file under ${CLAUDE_PLUGIN_ROOT}.
  * @param {string} root
+ * @param {{ pluginRoot: string | undefined, warn: Warn }} options
  * @returns {Promise<{ files: { file: string, content: string }[] }>}
  */
-async function buildAgents(root) {
+async function buildAgents(root, { pluginRoot, warn }) {
   const files = [];
   const entries = (await readdir(join(root, "agents"), { withFileTypes: true })).sort((a, b) =>
     byName(a.name, b.name),
@@ -169,7 +174,7 @@ async function buildAgents(root) {
     const dir = join(root, "agents", entry.name);
     if (!(await isFile(join(dir, "agent.md"))) || !(await isFile(join(dir, "claude", "frontmatter.json")))) continue;
 
-    const fm = await composeAgent(root, entry.name, CLAUDE);
+    const fm = await composeAgent(root, entry.name, CLAUDE, { pluginRoot, resolveRelativePaths: true, warn });
     const slug = fm.name.startsWith(NAME_PREFIX) ? fm.name.slice(NAME_PREFIX.length) : fm.name;
     const header =
       `---\n` +
@@ -268,26 +273,6 @@ async function copyTree(src, dest, transform, dryRun) {
   return { md, files };
 }
 
-/**
- * Normalise package.json's `repository` field into the string Claude Code's
- * plugin manifest requires. npm permits a string or an object
- * (`{ type, url, directory }`); Claude rejects anything but a string, and one
- * invalid manifest makes the whole plugin fail to load, so the object form must
- * never be copied through. Prefer `url`, fall back to `directory`, and omit the
- * field when neither is usable rather than emitting junk.
- * @param {unknown} repository  parsed package.json `repository` value
- * @returns {string | undefined}
- */
-function normaliseRepository(repository) {
-  if (typeof repository === "string") return repository.trim() === "" ? undefined : repository;
-  if (repository === null || typeof repository !== "object") return undefined;
-  const { url, directory } = /** @type {{ url?: unknown, directory?: unknown }} */ (repository);
-  for (const candidate of [url, directory]) {
-    if (typeof candidate === "string" && candidate.trim() !== "") return candidate;
-  }
-  return undefined;
-}
-
 /**
  * plugin.json manifest; version tracks the package so it can never go stale.
  * @param {string} root
@@ -739,7 +724,7 @@ export async function installClaude({ root = PACKAGE_ROOT, output, dryRun = fals
       ? await installInstructions({ root, target: instructionsTarget, dryRun, warn: warnSink })
       : null;
 
-  const agents = await buildAgents(root);
+  const agents = await buildAgents(root, { pluginRoot: rootPlugin, warn: warnSink });
   const skillOut = join(out, "skills");
   const skills = await buildSkills(root, skillOut, { dryRun, pluginRoot: rootPlugin, tokenMap, warn: warnSink });
   const docs = await installDocs({ root, output: out, dryRun, tokenMap });

package/bin/installers/pi.mjs

@@ -12,7 +12,9 @@
 //
 //   <output>/package.json            pi manifest — keywords ["pi-package"],
 //                                    pi.extensions + pi.skills (conventional
-//                                    dirs plus the bundled third-party packages)
+//                                    dirs plus the bundled third-party packages),
+//                                    repository (this package's origin, so the
+//                                    shipped skills resolve it from the install)
 //   <output>/agents/<slug>.agent.md  composed flat agents (agents/<name>/
 //                                    agent.md + pi/ harness dirs, {{TOOL:...}} /
 //                                    {{PATH:...}} substituted against
@@ -122,6 +124,7 @@ import { homedir } from "node:os";
 import { composeAgent, loadTokenMap, substituteTokens, translateToolList } from "../../scripts/lib/compose-agent.mjs";
 import { installDocs } from "../../scripts/lib/docs.mjs";
 import { isDirectory, isFile } from "../../scripts/lib/fs.mjs";
+import { normaliseRepository } from "../../scripts/lib/manifest.mjs";
 
 const PI = "pi";
 
@@ -137,7 +140,7 @@ const PI = "pi";
 /**
  * The generated package's pi manifest (`//` carries the generated-file marker).
  * @typedef {{ "//": string, name: string, version: string, private: boolean,
- *             description: string, type: string, keywords: string[],
+ *             description: string, repository?: string, type: string, keywords: string[],
  *             pi: { extensions: string[], skills: string[] } }} PiManifest
  */
 
@@ -1338,6 +1341,9 @@ async function buildManifest({ root, dependencies }) {
     version: typeof pkg?.version === "string" ? pkg.version : "0.0.0",
     private: true,
     description: "agent-cortex pi resources — generated by `agent-cortex install pi`",
+    // Where this package came from, carried so the installed artefact states its own origin:
+    // the shipped skills read it instead of assuming a checkout or a hardcoded slug.
+    repository: normaliseRepository(pkg?.repository),
     type: "module",
     keywords: ["pi-package"],
     pi: {

package/extensions/interrupt-bookmark/README.md

@@ -0,0 +1,129 @@
+# Interrupt Bookmark Extension
+
+Gives an agent a checkpoint and a rewind, so an interruption does not drag its turns into the
+context the original task then has to carry.
+
+PI can rewind a session tree and summarise the branch it abandons. Nothing exposed that as a
+deliberate operation, so an interruption — a meeting note, PR feedback to pass on, a Slack todo —
+stayed in the live context and the task carried it. This extension adds two tools around pi's own
+navigation: one records a resume point, one returns to it.
+
+## Usage
+
+| Tool | Description |
+| `interrupt_checkpoint` | Records the current leaf id and returns it |
+| `interrupt_resume` | Rewinds to a checkpoint, keeps the abandoned branch under a summary, and ends the turn |
+
+`interrupt_resume` takes `{ checkpointId, summary }`. `summary` describes the interruption; it
+reaches pi's summariser as `customInstructions`.
+
+After the turn settles, the rewind happens on its own: the abandoned branch is summarised by pi,
+the summary entry is labelled `interrupt`, and the session continues from the checkpoint. The
+summary is reported in the session (a notification and an `interrupt-rewind` custom entry), not in
+the tool result — the tool call is part of the branch that the rewind summarises.
+
+Nothing is deleted. The abandoned branch stays in the session file and in `/tree`, under the
+summary. No model call is made by this extension: the summary comes from pi's own tree-navigation
+summariser.
+
+## The two steps, and why they are two
+
+`waitForIdle()` and `navigateTree()` exist on `ExtensionCommandContext` only. The installed
+`types.d.ts` (pi 1.5.2) declares them there, and `docs/extensions.md` states the reason: they
+deadlock when called while the turn that invoked them is still running. A tool receives
+`ExtensionToolContext`, which has no `navigateTree` at all, and the session itself throws while it
+is streaming — which it always is during a tool call.
+
+So `interrupt_resume` cannot navigate. It validates the request, records it, and returns
+`terminate: true`. An `agent_settled` handler then dispatches `/interrupt-rewind <checkpointId>`
+through `sendUserMessage(..., { expandPromptTemplates: true })`, which runs the command rather than
+prompting the model. That is the pattern pi documents for a tool that must reach a command-only API
+(`docs/extensions.md`, "ctx.reload()").
+
+The declared navigation signature, quoted from the installed package's own
+`dist/core/extensions/types.d.ts`:
+
+```ts
+navigateTree(targetId: string, options?: {
+    summarize?: boolean;
+    customInstructions?: string;
+    replaceInstructions?: boolean;
+    label?: string;
+}): Promise<{ cancelled: boolean }>;
+```
+
+Every option name here is real: `summarize`, `customInstructions`, `replaceInstructions` and
+`label`. `label` is applied to the branch-summary entry when `summarize` is set, and to the target
+entry when it is not.
+
+## Failure modes
+
+| Case | Behaviour |
+| Unknown checkpoint id | Fails before anything is written, naming the id |
+| Already at the checkpoint | Reports that there is no interrupt to summarise, and writes nothing |
+| Session still streaming | Waits for idle first, then navigates |
+| Navigation rejected | Retries once, after another wait for idle; a second failure reports the reason and leaves the session unchanged |
+| A second rewind requested | Refused while the first is scheduled |
+
+A failed rewind records `ok: false` and the reason, and tells the caller to continue in the current
+context rather than silently carrying the interruption.
+
+## What this extension does not do
+
+- It does not decide when to checkpoint or what to record. The interrupt protocol belongs to the
+  agent that asks for the checkpoint.
+- It cannot report the summary entry in the tool result, for the reason above.
+- It needs a harness that dispatches extension commands. Where the command never runs, the rewind
+  reports that nothing was pending and the session is unchanged.
+
+## Claude Code parity
+
+The mechanism differs in kind between harnesses, so it is named once through `token-map.json`: the
+`interrupt_rewind` row renders as `interrupt_resume` on pi and as Claude Code's own `/rewind` on
+claude. Claude Code checkpoints and rewinds with a user command rather than a model-callable tool,
+so prose that names the row must describe only what both do — the session returns to an earlier
+point and the abandoned turns leave the live context — never a call shape, and it must say who
+acts: the agent where the harness gives it a tool, the human where the harness gives it a user
+command. The row is consumed by `agents/guppi/agent.md`'s interrupt protocol, which checkpoints,
+records the interrupt, rewinds and resumes; `test/guppi-interrupt-render.test.mjs` stages both
+installs to prove the fork.
+
+Both halves are wired per harness. guppi's pi frontmatter declares this extension's
+`interrupt_checkpoint` and `interrupt_resume` in its tool list, so steps 1 and 3 of the protocol are
+callable there. On claude the agent declares neither, because `/rewind` is the human's command, and
+the protocol hands that step to the human.
+
+An agent that uses these tools declares them in its own tool list, under the registered names
+`interrupt_checkpoint` and `interrupt_resume`. pi replaces the whole tool selection when a list is
+given. A tool an agent does not name is therefore never declared to its model, and the agent cannot
+call it. A tool list carries tool names only, so the `interrupt_rewind` prose row never appears in
+one.
+
+## Proven against pi
+
+Behaviour is tested against a complete `ExtensionAPI` double, with a fake session that rejects
+navigation while a response is active, exactly as pi does. Only the **pi** install is staged and
+loaded by `test/pi-extensions-load.test.mjs`: `bin/installers/pi.mjs` copies `extensions/` into the
+staged package, so that test loads this extension from a temp directory outside the checkout. It
+covers no claude install, because there is no claude extension to load — `bin/installers/claude.mjs`
+generates agents, skills, hooks and docs, and copies no `extensions/` tree at all.
+
+The claude side was therefore checked by hand, not by a test of this extension: `/rewind` is one of
+the commands the installed Claude Code CLI defines itself (verified in 2.1.294), and the
+`interrupt_rewind` row renders as `interrupt_resume` on pi and `/rewind` on claude when the token is
+substituted directly. The row's consumer is guppi's interrupt protocol, and
+`test/guppi-interrupt-render.test.mjs` checks both staged renders; this hand check is what
+established the claude name before that test existed.
+
+The session shape a rewind produces was checked against pi's own `SessionManager` separately:
+`branchWithSummary()` plus the label change leaves a `branch_summary` entry parented at the
+checkpoint, with `fromId` naming the abandoned leaf, every original entry still present, and the
+label recorded. A full session run — a real summariser call and a live `/tree` — needs a configured
+model and was not exercised here.
+
+## Development
+
+```bash
+pnpm test        # behaviour: capture, refusal, dispatch, rewind, retry, branch retention
+pnpm typecheck   # tsc --noEmit, which also checks the complete ExtensionAPI double
+```