@jaybeeuu/agent-cortex 2.7.0 → 2.9.0

package/extensions/interrupt-bookmark/index.ts

@@ -0,0 +1,354 @@
+/**
+ * Interrupt bookmark extension.
+ *
+ * An interruption mid-task — a meeting note, PR feedback to pass on, a Slack
+ * todo — drags its turns into the context that the original task then has to
+ * carry. PI can rewind a session tree and summarise the abandoned branch, but
+ * nothing exposes that as a deliberate operation. This extension adds two tools:
+ *
+ *   - `interrupt_checkpoint` captures the current leaf id and returns it, so the
+ *     caller holds a resume point;
+ *   - `interrupt_resume` rewinds to that id, keeps the abandoned branch under a
+ *     summary, and labels the summary entry `interrupt`.
+ *
+ * The summary comes from pi's own tree-navigation summariser
+ * (`navigateTree(..., { summarize: true })`). This extension makes no model call
+ * of its own. Nothing is deleted: the abandoned branch stays in the session
+ * file, reachable from the session tree.
+ *
+ * ## Why the rewind runs in two steps
+ *
+ * PI exposes `waitForIdle()` and `navigateTree()` on `ExtensionCommandContext`
+ * only, because they can deadlock when called from a handler that runs inside a
+ * turn (`docs/extensions.md`, "ExtensionCommandContext"). A tool receives
+ * `ExtensionToolContext`, and the session throws on navigation while it is
+ * streaming — which it always is while a tool call is running. A tool therefore
+ * cannot navigate the tree, and waiting for idle inside a tool call could never
+ * finish.
+ *
+ * So the resume tool validates the request, records it, and ends the turn. An
+ * `agent_settled` handler then dispatches the command that performs the rewind,
+ * which is the pattern pi documents for a tool that must reach a command-only
+ * API (`docs/extensions.md`, "ctx.reload()"). One consequence is worth stating:
+ * the summary entry is reported to the human and written to the session as a
+ * custom entry, not returned in the tool result — the tool result belongs to the
+ * branch that the rewind summarises.
+ */
+
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+  ExtensionToolContext,
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+/** The tool that captures a resume point. */
+export const CHECKPOINT_TOOL = "interrupt_checkpoint";
+
+/** The tool that asks for a rewind. */
+export const RESUME_TOOL = "interrupt_resume";
+
+/** The command that performs the rewind, dispatched once the turn settles. */
+export const REWIND_COMMAND = "interrupt-rewind";
+
+/** The label pi attaches to the branch-summary entry a rewind leaves behind. */
+export const SUMMARY_LABEL = "interrupt";
+
+/** Custom-entry type recording the outcome. Never part of the model's context. */
+export const REWIND_ENTRY = "interrupt-rewind";
+
+/**
+ * How many times a rewind is attempted: the first try, then exactly one retry.
+ * A second failure is reported, never retried again.
+ */
+export const REWIND_ATTEMPTS = 2;
+
+/** A rewind waiting for the turn to settle. */
+export interface RewindRequest {
+  /** The entry id the caller wants to return to. */
+  checkpointId: string;
+  /** What the interruption was about, as summariser instructions. */
+  summary: string;
+}
+
+/** What a rewind did, or why it did nothing. */
+export interface RewindReport {
+  ok: boolean;
+  /** How many navigation attempts were made. */
+  attempts: number;
+  /** The `branch_summary` entry the rewind left behind, when there is one. */
+  summaryEntryId?: string;
+  /** True when pi cancelled the navigation (an extension or the user declined). */
+  cancelled?: boolean;
+  /** Why the last attempt failed. */
+  reason?: string;
+}
+
+/** The parts of the command context a rewind uses. */
+type RewindContext = Pick<
+  ExtensionCommandContext,
+  "waitForIdle" | "navigateTree" | "sessionManager"
+>;
+
+/** The parts of the tool context the two tools read. */
+type BookmarkContext = Pick<ExtensionToolContext, "sessionManager">;
+
+/** Instructions for pi's summariser: what the interruption was, and why it is summarised. */
+export function summariserInstructions(summary: string): string {
+  return [
+    "The task was interrupted. Record what the interruption was about, and what the abandoned turns",
+    "were doing, so the task can resume without them.",
+    `The interruption: ${summary}`,
+  ].join(" ");
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * The branch-summary entry a navigation from `previousLeaf` appended, if any.
+ *
+ * `navigateTree()` returns this entry, but `ExtensionCommandContext` declares
+ * only `cancelled` in its result type, and after the call the leaf is the label
+ * entry pi appends on top of the summary. The entry is therefore found by the
+ * `fromId` pi records on it — no cast, and no assumption about the leaf.
+ */
+function summaryAfter(
+  sessionManager: RewindContext["sessionManager"],
+  previousLeaf: string | null,
+): string | undefined {
+  const entries = sessionManager.getEntries();
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const entry = entries[index];
+    if (entry.type === "branch_summary" && entry.fromId === previousLeaf) return entry.id;
+  }
+  return undefined;
+}
+
+/**
+ * Rewind to `checkpointId`, summarising the abandoned branch.
+ *
+ * Navigation rejects while a response, a compaction or another navigation is
+ * active, so each attempt waits for idle first. Waits and attempts are
+ * deliberately paired: an attempt that skips the wait fails for the reason the
+ * wait exists.
+ */
+export async function rewind(ctx: RewindContext, request: RewindRequest): Promise<RewindReport> {
+  let reason = "";
+
+  for (let attempt = 1; attempt <= REWIND_ATTEMPTS; attempt += 1) {
+    await ctx.waitForIdle();
+
+    // Captured before the navigation, so the summary it writes can be found by
+    // the branch it abandoned.
+    const previousLeaf = ctx.sessionManager.getLeafId();
+
+    try {
+      const result = await ctx.navigateTree(request.checkpointId, {
+        summarize: true,
+        customInstructions: summariserInstructions(request.summary),
+        label: SUMMARY_LABEL,
+      });
+
+      return {
+        ok: true,
+        attempts: attempt,
+        cancelled: result.cancelled,
+        summaryEntryId: summaryAfter(ctx.sessionManager, previousLeaf),
+      };
+    } catch (error) {
+      reason = errorMessage(error);
+    }
+  }
+
+  return { ok: false, attempts: REWIND_ATTEMPTS, reason };
+}
+
+/**
+ * Why this request cannot be rewound, or undefined when it can.
+ *
+ * An unknown id is refused here, before anything is queued or written, so the
+ * session is untouched and the message names the id that failed.
+ */
+export function refusal(ctx: BookmarkContext, request: RewindRequest): string | undefined {
+  if (ctx.sessionManager.getEntry(request.checkpointId) === undefined) {
+    return `Unknown checkpoint id: ${request.checkpointId}. Call ${CHECKPOINT_TOOL} to record a resume point.`;
+  }
+
+  if (ctx.sessionManager.getLeafId() === request.checkpointId) {
+    return `Checkpoint ${request.checkpointId} is the current position, so there are no interrupt turns to summarise. Nothing was rewound.`;
+  }
+
+  return undefined;
+}
+
+export default function interruptBookmarkExtension(pi: ExtensionAPI): void {
+  /**
+   * The rewind the next settle must dispatch. At most one: a second would
+   * navigate from a position the first has already replaced.
+   */
+  let pending: RewindRequest | undefined;
+
+  /**
+   * The summary waiting for its dispatch, keyed by checkpoint id. The command
+   * receives the id in its argument text and the summary from here, so a summary
+   * with spaces or newlines never has to survive a command line. One entry at a
+   * time: a new request replaces the previous one.
+   */
+  const handoff = new Map<string, string>();
+
+  pi.registerTool({
+    name: CHECKPOINT_TOOL,
+    label: "Interrupt Checkpoint",
+    description:
+      "Record the current session position and return its id, so an interruption can be rewound later.",
+    promptSnippet: `${CHECKPOINT_TOOL}: record a resume point before handling an interruption`,
+    promptGuidelines: [
+      `Use ${CHECKPOINT_TOOL} before an interruption is handled, and ${RESUME_TOOL} to return to it afterwards.`,
+    ],
+    parameters: Type.Object({}),
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      const leafId = ctx.sessionManager.getLeafId();
+
+      if (leafId === null) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: "The session has no entries yet, so there is no position to record.",
+            },
+          ],
+          details: { checkpointId: null },
+        };
+      }
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Checkpoint ${leafId}. Pass this id to ${RESUME_TOOL} to rewind here.`,
+          },
+        ],
+        details: { checkpointId: leafId },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: RESUME_TOOL,
+    label: "Interrupt Resume",
+    description:
+      "Rewind to a checkpoint, keep the abandoned branch under a summary, then continue from the checkpoint. Runs after the current turn ends.",
+    promptSnippet: `${RESUME_TOOL}: rewind to a checkpoint and summarise the interruption away`,
+    parameters: Type.Object({
+      checkpointId: Type.String({
+        description: `The id ${CHECKPOINT_TOOL} returned.`,
+      }),
+      summary: Type.String({
+        description: "What the interruption was about, so the summariser records it.",
+      }),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      if (pending !== undefined) {
+        throw new Error(
+          `A rewind to ${pending.checkpointId} is already scheduled. Nothing was changed.`,
+        );
+      }
+
+      const problem = refusal(ctx, params);
+      if (problem !== undefined) {
+        // A thrown message reaches the model as the tool's error result, and
+        // nothing has been written or queued at this point.
+        throw new Error(problem);
+      }
+
+      pending = { checkpointId: params.checkpointId, summary: params.summary };
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text:
+              `Rewind to ${params.checkpointId} scheduled. The abandoned branch is kept under a ` +
+              `summary labelled "${SUMMARY_LABEL}" once this turn ends; this tool call is part of it.`,
+          },
+        ],
+        details: { checkpointId: params.checkpointId, scheduled: true },
+        // The rewind needs the turn over, so end it rather than letting the model
+        // keep working in a context that is about to be rewound.
+        terminate: true,
+      };
+    },
+  });
+
+  // Command handlers are the only place pi allows tree navigation. The dispatch
+  // uses `expandPromptTemplates`, which runs the command instead of prompting the
+  // model, so nothing is sent to a provider here.
+  pi.registerCommand(REWIND_COMMAND, {
+    description: "Rewind to a scheduled interrupt checkpoint and summarise the abandoned branch",
+    handler: async (args, ctx) => {
+      const checkpointId = args.trim();
+
+      if (checkpointId === "") {
+        ctx.ui.notify("No checkpoint was named, so nothing was rewound.", "warning");
+        return;
+      }
+
+      const summary = handoff.get(checkpointId);
+      if (summary === undefined) {
+        ctx.ui.notify(
+          `No interrupt rewind is pending for ${checkpointId}, so nothing was rewound.`,
+          "warning",
+        );
+        return;
+      }
+      handoff.delete(checkpointId);
+
+      const report = await rewind(ctx, { checkpointId, summary });
+      pi.appendEntry(REWIND_ENTRY, {
+        checkpointId,
+        attempts: report.attempts,
+        ok: report.ok,
+        cancelled: report.cancelled ?? false,
+        summaryEntryId: report.summaryEntryId,
+        reason: report.reason,
+      });
+
+      if (!report.ok) {
+        ctx.ui.notify(
+          `Interrupt rewind to ${checkpointId} failed after ${report.attempts} attempts: ${report.reason}. The conversation is unchanged; continue in the current context and say the rewind failed.`,
+          "error",
+        );
+        return;
+      }
+
+      if (report.cancelled === true) {
+        ctx.ui.notify(
+          `Interrupt rewind to ${checkpointId} was cancelled. The conversation is unchanged.`,
+          "warning",
+        );
+        return;
+      }
+
+      const summaryEntry =
+        report.summaryEntryId === undefined ? "" : ` (summary entry ${report.summaryEntryId})`;
+      ctx.ui.notify(
+        `Rewound to ${checkpointId}${summaryEntry}. The abandoned branch is kept, labelled "${SUMMARY_LABEL}".`,
+        "info",
+      );
+    },
+  });
+
+  pi.on("agent_settled", () => {
+    const request = pending;
+    if (request === undefined) return;
+
+    // Taken here, so a second settle cannot dispatch the same rewind twice. A
+    // dispatch that never runs leaves no pending request behind.
+    pending = undefined;
+    handoff.clear();
+    handoff.set(request.checkpointId, request.summary);
+    pi.sendUserMessage(`/${REWIND_COMMAND} ${request.checkpointId}`, { expandPromptTemplates: true });
+  });
+}

package/extensions/interrupt-bookmark/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@agent-cortex/interrupt-bookmark",
+  "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": "^1.5.2",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typebox": "^1.1.38",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "typebox": "*"
+  }
+}

package/extensions/post-merge-watch/README.md

@@ -0,0 +1,133 @@
+# Post-Merge Watch Extension
+
+Wakes an idle PI session with the verdict of a post-merge CI run.
+
+A human merges the feature PR, and the CI run for the merge commit decides what
+happens next: nothing, a fix, or a revert. That merge lands outside the session,
+so nothing tells the agent when the run concludes. This extension polls the
+deterministic post-merge check and delivers the verdict as a follow-up message,
+which starts a turn in an idle session.
+
+## Usage
+
+```bash
+pi --post-merge-watch <bead>
+```
+
+| Input | Meaning |
+| --- | --- |
+| `--post-merge-watch <bead>` | Watch the post-merge check for this bead and wake the session with the verdict |
+| `AGENT_CORTEX_POST_MERGE_CHECK` | Path of the check script, when the shipped one is not the one to run |
+
+The flag is registered at load time, so it is accepted on the command line. A
+session without the flag starts no watch, spawns no process, and writes no state.
+
+The default script is `skills/workflow/ralph/scripts/post-merge-check.mjs`,
+resolved relative to this extension's own file. In a staged install
+(`extensions/` beside `skills/`) and in a checkout of this repository the same
+relative path resolves, so no absolute path is baked in.
+
+## What it does
+
+1. At session start, with the flag set, it records the watch and runs the check.
+2. It runs the check every 15 seconds, up to 40 times (about 10 minutes).
+3. When the check exits `0` (passed) or `1` (failed), or the attempt cap is
+   reached, it sends one message and stops watching.
+
+Each invocation passes `--wait 0`, so the script reports once instead of waiting
+inside itself: the poll interval and the bound belong to this extension, and a
+stopped watch never blocks on a running child process.
+
+The wake uses the confirmed PI signature
+`pi.sendMessage(message, { deliverAs: "followUp", triggerTurn: true })`: an idle
+session starts a turn from it, and a session in the middle of a turn reads it
+after that turn instead of being interrupted.
+
+The message names the bead, the verdict, the exit code, the reason, the run URL,
+the project, and the number of checks made. It carries the same fields as message
+`details`, so a renderer can read them without parsing the text.
+
+## What it never does
+
+- **No verdict logic.** The check's exit code is the verdict: `0` passed, `1`
+  failed, every other code (including a timeout kill) inconclusive. The run URL
+  and the reason are read from the script's JSON report and forwarded verbatim.
+  The extension never decides whether a run passed and never re-runs a workflow.
+- **No model call.** No prompt, no summarisation, no title generation. One turn
+  happens only because the delivered message starts one.
+- **No `@earendil-works/*` value import.** Types only, so the staged install
+  loads with pi absent from the extension's own `node_modules`
+  (`test/pi-extensions-load.test.mjs` proves this).
+- **No second watch for the same bead.** A session reload re-fires
+  `session_start`; the extension starts one watch per bead.
+
+## State
+
+| Item | Value |
+| --- | --- |
+| Directory | `~/.pi/agent-cortex/post-merge-watch/` |
+| File name | `<project dir name>-<bead>-<digest of full project path and bead>.json` |
+| Written | At watch start, then after each poll |
+| Removed | When the watch settles, when the session shuts down, and again if a write was still in flight |
+
+The digest covers the whole project path, so two checkouts whose directory names
+match — or two projects watching the same bead — never share a file. A watch that
+is still polling is the only thing the directory should hold.
+
+The write and the removal can race: a stop removes the file, and a write that is
+still in flight then recreates it. The write therefore re-checks whether the
+watch stopped once it completes, and removes the file again, so a stop cannot
+leave a state file behind. One narrow case survives: a write that **fails** while
+a stop is in progress returns before that re-check, so it can leave a partial
+file. No code reads the directory, so a partial file is cosmetic; do not read it
+as a live watch.
+
+The in-flight record is diagnostic: it names the bead, the project, the script,
+the pid, the attempt count, and the last exit code and reason. Nothing reads it
+back, so a watch never resumes from it; a new session with the same flag starts a
+new watch.
+
+## Bounds and shutdown
+
+| Bound | Value |
+| --- | --- |
+| Poll interval | 15 s |
+| Checks | 40 |
+| One check invocation | 120 s, then pi kills it |
+
+The pending timer is unref'd, so a watch never holds the host process open. On
+`session_shutdown` the timer is cancelled, a check already in flight is ignored,
+and the state file is removed: an abandoned watch wakes nobody and leaves nothing
+behind.
+
+## What has been proven
+
+The wake path has been run once end to end against a stub check script: the RPC
+wake itself was reproduced (`agent_settled` → `agent_start`, the custom message
+arriving with no client prompt), and a real model turn ran on it. That run did not
+read a real CI run, because the shipped `post-merge-check.mjs` was replaced by a
+stub: the poll-and-wake path is proven, and the check's own judgement is covered
+by `test/post-merge-check.test.mjs`, not by any test here. Treat the pair as one
+path only after a watch has read a genuine merge-commit run.
+
+## Claude Code parity
+
+PI-only. Claude Code has its own watch tools, which the Claude side uses instead of
+an extension.
+
+## Development
+
+```bash
+pnpm test        # the poll lifecycle, the wake payload, the state file, the wiring
+pnpm typecheck   # tsc --noEmit
+```
+
+`watch.test.ts` drives the whole lifecycle with a scheduler it steps by hand and a
+check runner that returns scripted exit codes, so no test sleeps or waits on a
+timer. `index.test.ts` drives the extension through a partial `ExtensionAPI`
+double; the complete-literal guard that fails `tsc` when pi's interface grows is
+`extensions/agent-modes/index.test.ts`.
+
+To watch the poll end to end against a script that is not the shipped one, point
+`AGENT_CORTEX_POST_MERGE_CHECK` at any executable that follows the check's
+contract: JSON on stdout and exit `0`/`1`/`2`.