ace-wake 0.1.0

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

@@ -0,0 +1,112 @@
+// 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.
+ */
+
+/**
+ * One changed target of a watch wake: the watched path, the change kind, the
+ * BEFORE→AFTER change signatures, and — when the file content was readable —
+ * a short capped sanitized excerpt of the new content.
+ *
+ * @typedef {object} WatchDelta
+ * @property {string} path Absolute path of the changed target.
+ * @property {"created" | "modified" | "deleted"} kind Change kind.
+ * @property {string} before Signature of the last delivered state.
+ * @property {string} after Signature of the current state.
+ * @property {string} [excerpt] Sanitized single-line head of the new content.
+ */
+
+/**
+ * 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}`;
+}
+
+/**
+ * Append the watch change delta to a watch wake message: one line per changed
+ * target with path, change kind, and BEFORE→AFTER signatures, plus an
+ * `excerpt:` line when the file content was readable. Loop wakes and watch
+ * wakes without a delta keep the bare message.
+ *
+ * @param {string} message
+ * @param {Array<WatchDelta>} deltas
+ * @returns {string}
+ */
+export function formatWatchDelta(message, deltas) {
+  if (!Array.isArray(deltas) || deltas.length === 0) {
+    return message;
+  }
+  const lines = deltas.map((delta) => {
+    const head = `changed: ${delta.path} (${delta.kind}) ${delta.before} → ${delta.after}`;
+    return delta.excerpt === undefined ? head : `${head}\nexcerpt: ${delta.excerpt}`;
+  });
+  return `${message}\n${lines.join("\n")}`;
+}

data/handbook/extensions/ace-wake/wake/wake-command-parser.js

@@ -0,0 +1,169 @@
+import { WakeError } from "./types.js";
+
+/**
+ * Parse the argument string of a /loop or /watch command.
+ *
+ * Supported forms:
+ *   add NAME --interval SECONDS --message TEXT
+ *   add NAME --path PATH --message TEXT
+ *   list
+ *   remove NAME
+ *
+ * Parsing is token-based: quoted values (including values that contain text
+ * resembling options, e.g. --path "logs/--message.txt") stay single tokens,
+ * quoted spans embedded in --flag=value tokens (e.g. --message="check the
+ * build") keep their full value, and option names match exactly, so
+ * "--message-prefix" never satisfies "--message". Unquoted message text may
+ * span the remaining tokens; unterminated quotes are rejected.
+ *
+ * @param {string} kind "loop" or "watch", used for error text only.
+ * @param {string} input Raw argument string after the command name.
+ * @returns {{subcommand: string, name?: string, flags: Record<string, string>, message?: string}}
+ */
+export function parseWakeCommand(kind, input) {
+  const tokens = tokenize((input ?? "").trim());
+  const subcommand = tokens[0]?.text;
+  if (!subcommand) {
+    throw new WakeError(usage(kind));
+  }
+
+  if (subcommand === "list") {
+    if (tokens.length > 1) {
+      throw new WakeError(`${kind} list takes no arguments`);
+    }
+    return { subcommand };
+  }
+
+  if (subcommand === "remove") {
+    if (tokens.length !== 2) {
+      throw new WakeError(`usage: /${kind} remove NAME`);
+    }
+    return { subcommand, name: tokens[1].text };
+  }
+
+  if (subcommand !== "add") {
+    throw new WakeError(`unknown ${kind} subcommand: ${subcommand}; ${usage(kind)}`);
+  }
+
+  if (tokens.length < 2) {
+    throw new WakeError(usage(kind));
+  }
+
+  const name = tokens[1].text;
+  const { flags, message } = parseFlags(kind, tokens.slice(2));
+
+  return { subcommand, name, flags, message };
+}
+
+function usage(kind) {
+  if (kind === "loop") {
+    return "usage: /loop add NAME --interval SECONDS --message TEXT | /loop list | /loop remove NAME";
+  }
+  return "usage: /watch add NAME --path PATH --message TEXT | /watch list | /watch remove NAME";
+}
+
+/**
+ * Split an argument string into tokens. A quote opens a quoted span only at
+ * the start of a token or immediately after `=` — so `--message="check the
+ * build"` and `--path="my file.txt"` keep their full values, while prose
+ * apostrophes mid-token (`don't`) stay literal. Inside a span, backslash
+ * escapes are honored and the span may contain whitespace and text
+ * resembling options; quotes are stripped. Unterminated spans are rejected
+ * instead of silently accepting the partial fragment.
+ *
+ * @param {string} raw
+ * @returns {Array<{text: string, quoted: boolean}>}
+ */
+function tokenize(raw) {
+  const tokens = [];
+  let index = 0;
+  while (index < raw.length) {
+    if (/\s/.test(raw[index])) {
+      index += 1;
+      continue;
+    }
+    const tokenStart = index;
+    const leadingQuote = raw[tokenStart];
+    let text = "";
+    while (index < raw.length && !/\s/.test(raw[index])) {
+      const character = raw[index];
+      const opensSpan = (character === "\"" || character === "'")
+        && (index === tokenStart || raw[index - 1] === "=");
+      if (!opensSpan) {
+        text += character;
+        index += 1;
+        continue;
+      }
+      index += 1;
+      let value = "";
+      while (index < raw.length && raw[index] !== character) {
+        if (raw[index] === "\\" && index + 1 < raw.length) {
+          value += raw[index + 1];
+          index += 2;
+          continue;
+        }
+        value += raw[index];
+        index += 1;
+      }
+      if (index >= raw.length) {
+        throw new WakeError(`unterminated quoted value starting at position ${tokenStart}`);
+      }
+      index += 1;
+      text += value;
+    }
+    tokens.push({ text, quoted: leadingQuote === "\"" || leadingQuote === "'" });
+  }
+  return tokens;
+}
+
+/**
+ * Extract --flag value pairs and the trailing message from add-tokens.
+ * Option names match exactly; an unquoted --message value spans all
+ * remaining tokens (joined with single spaces) since it is documented last.
+ *
+ * @param {string} kind
+ * @param {Array<{text: string, quoted: boolean}>} tokens
+ */
+function parseFlags(kind, tokens) {
+  const valueFlags = kind === "loop" ? ["interval", "message"] : ["path", "message"];
+  const flags = {};
+  let message;
+  let index = 0;
+  while (index < tokens.length) {
+    const token = tokens[index];
+    if (!token.text.startsWith("--") || token.quoted) {
+      index += 1;
+      continue;
+    }
+    const [flagName, inlineValue] = token.text.slice(2).split(/=(.*)/s, 2);
+    if (!valueFlags.includes(flagName)) {
+      index += 1;
+      continue;
+    }
+    if (inlineValue !== undefined) {
+      if (flagName === "message") {
+        message = inlineValue;
+      } else {
+        flags[flagName] = inlineValue;
+      }
+      index += 1;
+      continue;
+    }
+    if (flagName === "message") {
+      const rest = tokens.slice(index + 1);
+      if (rest.length === 0) {
+        throw new WakeError("message must not be empty");
+      }
+      message = rest.map((token_) => token_.text).join(" ");
+      index = tokens.length;
+      continue;
+    }
+    const value = tokens[index + 1];
+    if (value === undefined) {
+      throw new WakeError(`${flagName} requires a value`);
+    }
+    flags[flagName] = value.text;
+    index += 2;
+  }
+  return { flags, message };
+}

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

@@ -0,0 +1,86 @@
+import { boundMessage } from "./types.js";
+
+/**
+ * Delivers wake messages with per-source coalescing.
+ *
+ * A wake is delivered through the injected queue port only; the dispatcher
+ * never interprets the message or triggers work itself. While a source has a
+ * wake queued (delivered but not yet settled), repeated triggers for the same
+ * source coalesce into the pending one. Distinct sources never coalesce.
+ *
+ * The adapter settles sources when Pi reports the agent fully settled, so a
+ * busy agent receives at most one queued follow-up per source per run cycle.
+ * Pending entries keep their message text so a delivery boundary that never
+ * sees a settlement (e.g. manual compaction rejecting prompts without an
+ * extension-visible signal) can reconcile unacknowledged attempts.
+ */
+export class WakeDispatcher {
+  /** @private @type {(sourceKey: string, text: string) => boolean} */
+  #deliver;
+
+  /** @private @type {Map<string, string>} */
+  pending = new Map();
+
+  /**
+   * @param {object} ports
+   * @param {(sourceKey: string, text: string) => boolean} ports.deliver
+   *   Queue the wake for the source. Returns true when Pi accepted it.
+   */
+  constructor({ deliver }) {
+    this.#deliver = deliver;
+  }
+
+  /**
+   * Queue a wake for the source, coalescing while one is already pending.
+   *
+   * @param {string} sourceKey Stable source identity, e.g. "loop:heartbeat".
+   * @param {string} text Wake text; bounded before delivery.
+   * @returns {{delivered: boolean, reason?: string}}
+   */
+  wake(sourceKey, text) {
+    if (this.pending.has(sourceKey)) {
+      return { delivered: false, reason: "coalesced" };
+    }
+
+    const bounded = boundMessage(text);
+    const accepted = this.#deliver(sourceKey, bounded);
+    if (!accepted) {
+      return { delivered: false, reason: "rejected" };
+    }
+
+    this.pending.set(sourceKey, bounded);
+    return { delivered: true };
+  }
+
+  /**
+   * Mark one source's queued wake as consumed.
+   *
+   * @param {string} sourceKey
+   */
+  settle(sourceKey) {
+    this.pending.delete(sourceKey);
+  }
+
+  /** Mark every source's queued wake as consumed (agent fully settled). */
+  settleAll() {
+    this.pending.clear();
+  }
+
+  /**
+   * Pending wake attempts as [sourceKey, text] pairs, for reconciliation at
+   * delivery boundaries that bypass the normal settlement signal.
+   *
+   * @returns {Array<[string, string]>}
+   */
+  pendingEntries() {
+    return [...this.pending.entries()];
+  }
+
+  /**
+   * @param {string} sourceKey
+   * @returns {boolean}
+   */
+  isPending(sourceKey) {
+    return this.pending.has(sourceKey);
+  }
+}