ace-handbook-integration-pi 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0aecac8cdb81dfb6b51efda48199aeaf10e7267bbaed81dcec49acb0fa985553
-  data.tar.gz: baeff1aa2723ed7a0333c28d78fc5825d6b32dc5b6cdb7090900f3350358239f
+  metadata.gz: 7c5ab037a9338b9466fc32aaed92e0418c5ef05e436ca790a6ef6c6706b88ffb
+  data.tar.gz: 1181cb6b7863f29e907af9e3cd9a008b10265225dd00537d55aa6127cfe80a05
 SHA512:
-  metadata.gz: 761967528dfe314d715ea45cbc25476f27d2d5a2835bd12a3b39b3b2faba352adae6ff81ec7e91b0168fd9af44bb28f71a3a7e98f35fb55edf69cb1bae98edfd
-  data.tar.gz: bf06c8004e8b1c865093685cf7d17e3463857d3521fcfc3dfe89d088a4f6fd73d9b2f5d27b539d8e3555a843b4c7ed3e906a47aab92befeee9a4803311dd4c2d
+  metadata.gz: 85683a4338df4a155fbc01bee9d8324b5be22cc9a5a0eaad3501d2359a5497d38545b7f45eae03b3eaf180095236bbaed7c8b5081130ed7300a89e72522e1c77
+  data.tar.gz: da305a0888d369118bc6c6c1e2ac965bc0468f807138a4f3a0a60e1c95f146f841fd083c125137d7a55718d1a3c91993ee2ca0c4751a05b2af9ae5531cb98fc7

data/.ace-defaults/handbook/providers/pi.yml

@@ -1,3 +1,4 @@
 provider: pi
 output_dir: .pi/skills
 prompts_dir: .pi/prompts
+extensions_dir: .pi/extensions

data/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to ace-handbook-integration-pi will be documented in this fi
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-28
+
+### Added
+- Shipped the **ace-wake** Pi extension (`handbook/extensions/ace-wake/index.js`, projected to `.pi/extensions/`): session-scoped `/loop` timers and `/watch` file subscriptions that wake the live agent through queued `sendUserMessage` messages only. Wakes are bounded, source-prefixed, coalesce per source while one is queued, and reach busy agents as queued follow-ups that never interrupt an in-flight tool operation. Concurrent sources deliver into an active run immediately (serialization guards only the idle-to-running transition). Delivery ambiguities from Pi's void `sendUserMessage` resolve toward redelivery over loss: unconfirmed attempts re-fire on a bounded recovery window, and watch changes refused while no model is selected retry on that window without needing another filesystem event. Definitions persist as session entries and reconcile exactly once per session start, reload, or branch switch with no missed-tick replay. No cron, systemd, or external heartbeat dependency.
+- Provider manifest now declares `extensions_dir: .pi/extensions`; `ace-handbook sync` projects extension assets and prunes stale projected files via a projection receipt without touching user-authored extensions.
+- Command flags accept quoted values both after the flag (`--message "check the build"`) and inline (`--message="check the build"`); an unterminated quote fails the command instead of storing a truncated value, while prose apostrophes mid-token stay literal.
+
+### Changed
+- Renamed the backlog-running prompt from `/loop` to `/work-backlog` (template `handbook/prompts/work-backlog.md`) so the timer command owns the `/loop` name. Behavior unchanged; no alias is provided.
+- Package verification now includes the JavaScript wake suite (run on the installed Node runtime) and an installed-extension acceptance scenario inside the real Pi SDK runtime (`test/feat/`).
+
 ## [0.4.0] - 2026-09-27
 
 ### Added

data/README.md

@@ -21,7 +21,9 @@
 
 **Consume canonical skills from PI tooling** - keep provider-specific behavior while preserving shared semantics, so agents running under pi-agent get the same skill intent as any other provider.
 
-**Run the in-process overseer loop with `/loop`** - the canonical `handbook/prompts/loop.md` template projects to `.pi/prompts/loop.md` (`ace-handbook sync --provider pi`), giving pi a slash command that cycles the task backlog (select → execute via `as-task-work` → verify → report) inside the pi session itself - no tmux windows or external orchestrator.
+**Run the in-process overseer loop with `/work-backlog`** - the canonical `handbook/prompts/work-backlog.md` template projects to `.pi/prompts/work-backlog.md` (`ace-handbook sync --provider pi`), giving pi a slash command that cycles the task backlog (select → execute via `as-task-work` → verify → report) inside the pi session itself - no tmux windows or external orchestrator.
+
+**Wake idle agents with `/loop` timers and `/watch` file subscriptions** - the bundled ace-wake extension (projected to `.pi/extensions/ace-wake/index.js`) queues bounded wake messages to the live agent through `sendUserMessage` only. Wakes coalesce per source, busy agents receive queued follow-ups instead of interruptions, definitions survive reload/restart with exactly-once re-registration, and there is no cron, systemd, or external heartbeat dependency. See [docs/usage.md](docs/usage.md).
 
 **Keep provider updates constrained** - update projection assets inside this package instead of canonical definitions, keeping changes isolated from [ace-handbook](../ace-handbook).
 
@@ -29,10 +31,11 @@
 
 ## Testing
 
-This package is **fast-only** in the ACE testing model.
+This package ships fast tests plus one installed-extension acceptance level.
 
-- Deterministic test coverage lives under `test/fast/`.
-- This migration does not introduce `test/feat/` or `test/e2e/` for this package.
+- Deterministic coverage (including the JavaScript wake suite run via Node) lives under `test/fast/` and `test/js/`.
+- `test/feat/` runs the ace-wake acceptance scenario against the projected extension inside the real Pi SDK runtime; it requires the `pi` CLI and Node.
+- This package does not introduce `test/e2e/`.
 
 Verification commands:
 

data/handbook/extensions/ace-wake/index.js

@@ -0,0 +1,341 @@
+// ace-wake — in-process loop and file-watch wakes for Pi agents.
+//
+// Named /loop timers and /watch file subscriptions queue a bounded wake
+// message to the agent through sendUserMessage only. The agent decides what
+// to do after waking; the extension never executes tasks and never depends on
+// cron, systemd, or any external heartbeat service. While the agent is busy a
+// wake is queued as a follow-up instead of interrupting an in-flight tool
+// operation. Definitions persist as session entries, survive compaction, and
+// reconcile exactly once per session start, reload, or branch switch.
+//
+// Commands:
+//   /loop add NAME --interval SECONDS --message TEXT
+//   /loop list
+//   /loop remove NAME
+//   /watch add NAME --path PATH --message TEXT
+//   /watch list
+//   /watch remove NAME
+
+import { clearInterval, setInterval } from "node:timers";
+
+import { WakeDispatcher } from "./wake/wake-dispatcher.js";
+import { parseWakeCommand } from "./wake/wake-command-parser.js";
+import { createLoopPort } from "./wake/loop-subscription.js";
+import { createWatchPort, nodeStatFn, nodeWatchFactory } from "./wake/watch-subscription.js";
+import {
+  SESSION_ENTRY_TYPE,
+  WakeError,
+  boundMessage,
+} from "./wake/types.js";
+import { WakeRegistry } from "./wake/wake-registry.js";
+
+const STATUS_KEY = "ace-wake";
+
+/**
+ * Extension factory. Pi calls it as `factory(pi)`; the optional second
+ * argument exists so tests can inject deterministic clock, watcher, and
+ * stat ports. Production defaults are real Node timers and fs.
+ *
+ * All mutable state lives inside this factory closure: one extension runtime
+ * (one pi process, or one SDK session) owns exactly one state slot, and
+ * multiple runtimes in one process never share state.
+ *
+ * @param {object} pi ExtensionAPI surface provided by Pi.
+ * @param {object} [ports] Injectable host ports for deterministic tests.
+ */
+export default function (pi, ports = {}) {
+  /** @type {{registry: WakeRegistry} | undefined} */
+  let runtime;
+
+  const getRuntime = () => runtime;
+  const bindRuntime = (ctx) => {
+    runtime?.registry.dispose();
+    runtime = { registry: createRegistry(pi, ctx, ports) };
+    runtime.registry.reconcile();
+  };
+
+  pi.registerCommand("loop", {
+    description: "Manage named timer loops that wake this agent (add | list | remove)",
+    handler: async (args, ctx) => {
+      await handleCommand(ctx, "loop", args, getRuntime, bindRuntime);
+    },
+  });
+
+  pi.registerCommand("watch", {
+    description: "Manage named file watches that wake this agent (add | list | remove)",
+    handler: async (args, ctx) => {
+      await handleCommand(ctx, "watch", args, getRuntime, bindRuntime);
+    },
+  });
+
+  // session_start covers startup, reload, resume, fork, and new sessions;
+  // session_tree covers branch switches. Reconciliation is idempotent, so a
+  // reload re-registers each configured subscription exactly once.
+  pi.on("session_start", async (_event, ctx) => {
+    bindRuntime(ctx);
+  });
+  pi.on("session_tree", async (_event, ctx) => {
+    bindRuntime(ctx);
+  });
+
+  // A run has begun: wakes dispatched concurrently during the idle-to-running
+  // transition can now enter the follow-up queue safely, so the registry
+  // drains anything it serialized.
+  pi.on("agent_start", async () => {
+    runtime?.registry.noteRunStarted();
+  });
+
+  // The agent consumed every queued continuation; same-source wakes may
+  // deliver again. Watches whose change was absorbed by a pending wake are
+  // re-checked so no change is lost without a new filesystem event.
+  pi.on("agent_settled", async () => {
+    runtime?.registry.settleAll();
+  });
+
+  // Manual compaction rejects sendUserMessage asynchronously (before, during,
+  // and briefly after the compaction events) and never emits agent_settled:
+  // wakes are retained while it runs and flushed once the context is actually
+  // idle again. Automatic compaction happens inside a run whose pending wakes
+  // stay legitimately queued, so it is left untouched.
+  pi.on("session_before_compact", async (event) => {
+    if (event.reason === "manual") {
+      runtime?.registry.pauseDelivery();
+    }
+  });
+  pi.on("session_compact", async (event, ctx) => {
+    if (event.reason === "manual") {
+      runtime?.registry.resumeDelivery();
+      scheduleManualCompactionFlush(ctx);
+    }
+  });
+  pi.on("session_compact_failed", async (event, ctx) => {
+    if (event.reason === "manual") {
+      runtime?.registry.resumeDelivery();
+      scheduleManualCompactionFlush(ctx);
+    }
+  });
+
+  pi.on("session_shutdown", async () => {
+    runtime?.registry.dispose();
+    runtime = undefined;
+  });
+
+  /**
+   * Poll until the host context is genuinely idle (no run, no compaction) and
+   * then flush retained wakes. A single deferred callback is not enough: other
+   * session_compact handlers may await asynchronous work while Pi still rejects
+   * prompts. Bounded polling covers the idle-after-compaction case; a run that
+   * continues after compaction flushes via agent_settled instead.
+   */
+  function scheduleManualCompactionFlush(ctx) {
+    const pollMs = 100;
+    // Bound the poll to the session that scheduled it: a rebind or shutdown
+    // replaces the registry, and the old poll must not flush the new one.
+    const registry = runtime.registry;
+    const attempt = () => {
+      if (runtime?.registry !== registry) {
+        return;
+      }
+      let idle;
+      try {
+        idle = ctx.isIdle();
+      } catch {
+        return; // Stale context: session_start rebinds.
+      }
+      if (idle) {
+        registry.completeResume();
+        return;
+      }
+      const timer = setTimeout(attempt, pollMs);
+      timer.unref?.();
+    };
+    attempt();
+  }
+}
+
+function createRegistry(pi, ctx, ports) {
+  const dispatcher = new WakeDispatcher({
+    deliver: (sourceKey, text) => deliverWake(pi, ctx, sourceKey, text),
+  });
+  /** The registry is created after its watch port, so deactivation hooks go
+   * through this holder once it exists. */
+  let registry;
+  const built = new WakeRegistry({
+    loops: createLoopPort({
+      setIntervalFn: ports.setIntervalFn ?? ((callback, ms) => setInterval(callback, ms)),
+      clearIntervalFn: ports.clearIntervalFn ?? ((handle) => clearInterval(handle)),
+    }),
+    watches: createWatchPort({
+      watchFactory: ports.watchFactory ?? nodeWatchFactory,
+      statFn: ports.statFn ?? nodeStatFn,
+      baseDir: ctx.cwd,
+      scheduleReconcile: ports.scheduleReconcile,
+      onDeactivate: () => registry?.refreshStatus(),
+    }),
+    state: sessionStatePort(pi, ctx),
+    status: statusPort(ctx),
+    dispatcher,
+    dispatchRecoveryMs: ports.dispatchRecoveryMs,
+    isHostQueued: () => {
+      try {
+        return ctx.hasPendingMessages();
+      } catch {
+        return true;
+      }
+    },
+    isHostIdle: () => {
+      try {
+        return ctx.isIdle();
+      } catch {
+        return false;
+      }
+    },
+  });
+  registry = built;
+  return built;
+}
+
+/**
+ * Queue-only delivery, always as a queued follow-up. Pi runs a follow-up
+ * immediately when nothing is in flight and queues it behind any active run
+ * otherwise, so no window — between runs, during a tool, or while earlier
+ * wakes are queued — can drop a wake or interrupt an in-flight operation.
+ * The complete rendered message (source prefix included) is bounded.
+ */
+function deliverWake(pi, ctx, sourceKey, text) {
+  const message = boundMessage(`[ace-wake ${sourceKey}] ${text}`);
+  try {
+    // Known synchronous preflight: without a selected model Pi rejects the
+    // prompt asynchronously and no lifecycle event ever acknowledges it, so
+    // the wake is refused here and the next tick re-attempts instead of
+    // coalescing behind a stranded pending marker.
+    if (!ctx.model) {
+      return false;
+    }
+    pi.sendUserMessage(message, { deliverAs: "followUp" });
+    return true;
+  } catch {
+    // A stale context (session replaced/reloaded) or a rejecting host must
+    // not crash the timer callback; the next session_start rebinds.
+    return false;
+  }
+}
+
+function sessionStatePort(pi, ctx) {
+  return {
+    load() {
+      let snapshot;
+      for (const entry of ctx.sessionManager.getBranch()) {
+        if (entry.type === "custom" && entry.customType === SESSION_ENTRY_TYPE && entry.data) {
+          snapshot = entry.data;
+        }
+      }
+      // getBranch() returns the stored entries themselves; cloning keeps
+      // registry mutations from rewriting historical session entries, which
+      // would leak later edits back into branched-away history.
+      return snapshot ? structuredClone(snapshot) : { loops: [], watches: [] };
+    },
+    save(snapshot) {
+      pi.appendEntry(SESSION_ENTRY_TYPE, snapshot);
+    },
+  };
+}
+
+function statusPort(ctx) {
+  return {
+    render(entries) {
+      try {
+        // Every context access — including hasUI — throws once the context
+        // is stale after session replacement, reload, or disposal.
+        if (!ctx.hasUI) {
+          return;
+        }
+        if (entries.length === 0) {
+          ctx.ui.setStatus(STATUS_KEY, undefined);
+          return;
+        }
+        const parts = entries.map((entry) => {
+          const state = entry.error ? " error" : entry.pending ? " pending" : "";
+          return `${entry.kind} ${entry.name}${state} ${entry.detail}`;
+        });
+        ctx.ui.setStatus(STATUS_KEY, parts.join(" | "));
+      } catch {
+        // Stale context: skip the render; the next session_start rebinds.
+      }
+    },
+  };
+}
+
+async function handleCommand(ctx, kind, args, getRuntime, bindRuntime) {
+  try {
+    if (!getRuntime()) {
+      bindRuntime(ctx);
+    }
+    const registry = getRuntime().registry;
+    const parsed = parseWakeCommand(kind, args);
+    switch (parsed.subcommand) {
+      case "add":
+        addSubscription(registry, kind, parsed);
+        notify(ctx, `${kind} "${parsed.name}" added`, "info");
+        break;
+      case "list":
+        notify(ctx, formatList(kind, registry.list()), "info");
+        break;
+      case "remove":
+        removeSubscription(registry, kind, parsed.name);
+        notify(ctx, `${kind} "${parsed.name}" removed; no further wakes will fire`, "info");
+        break;
+      default:
+        throw new WakeError(`unknown ${kind} subcommand: ${parsed.subcommand}`);
+    }
+  } catch (error) {
+    notify(ctx, error instanceof WakeError ? error.message : `${kind} failed: ${error.message}`, "error");
+  }
+}
+
+function addSubscription(registry, kind, parsed) {
+  if (kind === "loop") {
+    registry.addLoop({
+      name: parsed.name,
+      intervalSeconds: parsed.flags.interval,
+      message: parsed.message,
+    });
+    return;
+  }
+  registry.addWatch({
+    name: parsed.name,
+    path: parsed.flags.path,
+    message: parsed.message,
+  });
+}
+
+function removeSubscription(registry, kind, name) {
+  if (kind === "loop") {
+    registry.removeLoop(name);
+    return;
+  }
+  registry.removeWatch(name);
+}
+
+/**
+ * @returns {string}
+ */
+function formatList(kind, entries) {
+  const plural = kind === "watch" ? "watches" : `${kind}s`;
+  const scoped = entries.filter((entry) => entry.kind === kind);
+  if (scoped.length === 0) {
+    return `no ${plural} configured`;
+  }
+  return scoped
+    .map((entry) => {
+      const state = entry.error ? ` ERROR: ${entry.error}` : entry.pending ? " (wake pending)" : "";
+      return `${entry.name} — ${entry.detail}${state}`;
+    })
+    .join("\n");
+}
+
+function notify(ctx, message, type) {
+  if (ctx.hasUI) {
+    ctx.ui.notify(message, type);
+  }
+}

data/handbook/extensions/ace-wake/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

data/handbook/extensions/ace-wake/wake/loop-subscription.js

@@ -0,0 +1,62 @@
+/**
+ * Loop subscription port owning native interval handles.
+ *
+ * Each start schedules an in-process interval from "now". After disposal and
+ * re-registration (reload, restart, reconcile) the next tick is a full
+ * interval away: no missed or catch-up ticks are ever replayed.
+ *
+ * @param {object} ports
+ * @param {(callback: () => void, ms: number) => unknown} ports.setIntervalFn
+ * @param {(handle: unknown) => void} ports.clearIntervalFn
+ * @returns {{
+ *   start: (definition: import("./types.js").LoopDefinition, onTick: (definition: import("./types.js").LoopDefinition) => void) => void,
+ *   stop: (name: string) => void,
+ *   stopAll: () => void,
+ *   errorOf: (name: string) => string | undefined,
+ *   activeCount: () => number,
+ * }}
+ */
+export function createLoopPort({ setIntervalFn, clearIntervalFn }) {
+  /** @type {Map<string, unknown>} */
+  const handles = new Map();
+
+  return {
+    start(definition, onTick) {
+      stopExisting(definition.name);
+      const milliseconds = definition.intervalSeconds * 1000;
+      const handle = setIntervalFn(() => onTick(definition), milliseconds);
+      // Never hold the host process open on the extension's behalf.
+      handle?.unref?.();
+      handles.set(definition.name, handle);
+    },
+
+    stop(name) {
+      stopExisting(name);
+    },
+
+    stopAll() {
+      for (const handle of handles.values()) {
+        clearIntervalFn(handle);
+      }
+      handles.clear();
+    },
+
+    errorOf() {
+      // Intervals do not produce runtime errors; the clock either runs or the
+      // process is gone.
+      return undefined;
+    },
+
+    activeCount() {
+      return handles.size;
+    },
+  };
+
+  function stopExisting(name) {
+    const handle = handles.get(name);
+    if (handle !== undefined) {
+      clearIntervalFn(handle);
+      handles.delete(name);
+    }
+  }
+}

data/handbook/extensions/ace-wake/wake/types.js

@@ -0,0 +1,78 @@
+// Shared contracts for the ace-wake Pi extension.
+//
+// The extension wakes a Pi agent through queue/sendUserMessage only. It never
+// executes tasks, never spawns external timers or services, and never injects
+// text into an in-flight tool operation. Host capabilities (clock, interval
+// scheduling, filesystem watching, message queueing, session state, status
+// reporting) are injected as plain function ports so the registry can be
+// tested deterministically without Pi.
+
+/** Prefix for wake source keys originating from a named loop. */
+export const LOOP_SOURCE_PREFIX = "loop:";
+
+/** Prefix for wake source keys originating from a named watch. */
+export const WATCH_SOURCE_PREFIX = "watch:";
+
+/** Hard upper bound for a delivered wake message, in characters. */
+export const MAX_WAKE_MESSAGE_CHARS = 4000;
+
+/** Upper bound for a subscription name, in characters. */
+export const MAX_NAME_CHARS = 64;
+
+/** customType used for pi.appendEntry persistence of wake definitions. */
+export const SESSION_ENTRY_TYPE = "ace-wake";
+
+/**
+ * A configured recurring timer.
+ *
+ * @typedef {object} LoopDefinition
+ * @property {string} name Unique within loop subscriptions for the session.
+ * @property {number} intervalSeconds Finite number greater than zero.
+ * @property {string} message Wake text delivered on each fire.
+ */
+
+/**
+ * A configured filesystem watch.
+ *
+ * @typedef {object} WatchDefinition
+ * @property {string} name Unique within watch subscriptions for the session.
+ * @property {string} path Canonical absolute path of the watched file.
+ * @property {string} message Wake text delivered on change.
+ */
+
+/**
+ * Persisted session snapshot handed to the state port.
+ *
+ * @typedef {object} WakeSnapshot
+ * @property {LoopDefinition[]} loops
+ * @property {WatchDefinition[]} watches
+ */
+
+/**
+ * Raised for user-facing validation and lookup failures.
+ */
+export class WakeError extends Error {
+  /**
+   * @param {string} message
+   */
+  constructor(message) {
+    super(message);
+    this.name = "WakeError";
+  }
+}
+
+/**
+ * Truncate a message to the bounded length, reserving space for the
+ * truncation marker so the delivered message never exceeds the bound.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function boundMessage(text) {
+  const trimmed = text.trim();
+  const marker = "… [ace-wake: message truncated]";
+  if (trimmed.length <= MAX_WAKE_MESSAGE_CHARS) {
+    return trimmed;
+  }
+  return `${trimmed.slice(0, MAX_WAKE_MESSAGE_CHARS - marker.length)}${marker}`;
+}