sentinelayer-cli 0.19.0 → 0.20.0

package/src/session/wake/pump.js

@@ -0,0 +1,135 @@
+// Wake pump — the live event source for the sentid daemon (Wake-Up Bus L2).
+//
+// Connects a session's event stream to the dispatcher: fetch new events, run
+// them through dispatcher.dispatchBatch (which applies resolveTarget routing,
+// the at-least-once retry/DLQ contract, and the in-memory RESUME cursor), then
+// persist that cursor for restart RESUME.
+//
+// The event source `pollEvents` is INJECTED, not imported: importing
+// sync.js/listener.js would drag the heavy auth/`open` module graph into the
+// daemon and make this untestable. The thin sentid runtime entrypoint adapts
+// the real pollSessionEvents to the contract below; tests inject a fake.
+//
+// At-least-once end to end: the fetch cursor advances only to the cursor of the
+// last COMMITTED event (one whose seq the dispatcher actually advanced past). A
+// retryable/uncommitted failure stops the batch, the fetch cursor stays behind
+// it, and the next poll re-delivers that event — so a transient wake failure is
+// retried, never silently skipped.
+
+import { readWakeCursor, writeWakeCursor } from "./cursor-store.js";
+
+function seqOf(event) {
+  const raw = event?.sequenceId ?? event?.seq ?? event?.payload?.sequenceId;
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : null;
+}
+
+function cursorOf(event) {
+  const c = event?.cursor;
+  return typeof c === "string" && c ? c : null;
+}
+
+const defaultSleep = (ms, { signal } = {}) =>
+  new Promise((resolve) => {
+    const t = setTimeout(resolve, ms);
+    if (typeof t.unref === "function") t.unref();
+    if (signal) signal.addEventListener("abort", () => { clearTimeout(t); resolve(); }, { once: true });
+  });
+
+/**
+ * @param {object} opts
+ * @param {string} opts.sessionId
+ * @param {{ dispatchBatch:Function, getCursor:Function, setCursor:Function }} opts.dispatcher
+ * @param {(sessionId:string, o:{afterCursor:string|null}) => Promise<{events:object[], cursor?:string|null}>} opts.pollEvents
+ * @param {{ targetPath?:string, idleMs?:number, readCursor?:Function, writeCursor?:Function, sleep?:Function, logger?:Function }} [opts]
+ */
+export function createWakePump({
+  sessionId,
+  dispatcher,
+  pollEvents,
+  targetPath,
+  idleMs = 1500,
+  readCursor = readWakeCursor,
+  writeCursor = writeWakeCursor,
+  sleep = defaultSleep,
+  logger,
+} = {}) {
+  if (typeof sessionId !== "string" || sessionId.trim() === "") {
+    throw new TypeError("wake pump: sessionId must be a non-empty string");
+  }
+  if (!dispatcher || typeof dispatcher.dispatchBatch !== "function" || typeof dispatcher.getCursor !== "function") {
+    throw new TypeError("wake pump: dispatcher with dispatchBatch()/getCursor() is required");
+  }
+  if (typeof pollEvents !== "function") {
+    throw new TypeError("wake pump: pollEvents function is required");
+  }
+  const log = typeof logger === "function" ? logger : () => {};
+  let seeded = false;
+
+  // Seed the dispatcher's RESUME cursor from disk once, on first use.
+  async function ensureSeeded() {
+    if (seeded) return;
+    seeded = true;
+    if (typeof dispatcher.setCursor === "function") {
+      dispatcher.setCursor(await readCursor(sessionId, { targetPath }));
+    }
+  }
+
+  // The fetch cursor advances only to the last COMMITTED event's cursor.
+  function nextFetchCursor(events, committedSeq, fallback) {
+    let best = fallback;
+    let bestSeq = -Infinity;
+    for (const event of events) {
+      const seq = seqOf(event);
+      const cursor = cursorOf(event);
+      if (cursor !== null && seq !== null && seq <= committedSeq && seq > bestSeq) {
+        bestSeq = seq;
+        best = cursor;
+      }
+    }
+    return best;
+  }
+
+  /**
+   * One fetch -> dispatch -> persist cycle. Returns the next fetch cursor and the
+   * dispatch results so the caller (or a test) can observe progress.
+   */
+  async function tickOnce({ fetchCursor = null, deps = {} } = {}) {
+    await ensureSeeded();
+    const { events = [], cursor: latestCursor = null } = (await pollEvents(sessionId, { afterCursor: fetchCursor })) || {};
+    if (!Array.isArray(events) || events.length === 0) {
+      return { fetchCursor, results: [], idle: true };
+    }
+    const results = await dispatcher.dispatchBatch(events, deps);
+    const committedSeq = dispatcher.getCursor();
+    // Only adopt the poller's latest cursor if the WHOLE batch committed.
+    const allCommitted = results.length === events.length && results.every((r) => !r.retryable);
+    const advanced = nextFetchCursor(events, committedSeq, fetchCursor);
+    const next = allCommitted && typeof latestCursor === "string" && latestCursor ? latestCursor : advanced;
+    await writeCursor(sessionId, committedSeq, { targetPath });
+    log("debug", "wake pump tick", { committedSeq, fetched: events.length, advanced: next !== fetchCursor });
+    return { fetchCursor: next, results, idle: false };
+  }
+
+  /** Run the fetch loop until `signal` aborts. */
+  async function start({ signal, fetchCursor = null, deps = {} } = {}) {
+    let cursor = fetchCursor;
+    while (!signal?.aborted) {
+      let idle = true;
+      try {
+        const tick = await tickOnce({ fetchCursor: cursor, deps });
+        cursor = tick.fetchCursor;
+        idle = tick.idle;
+      } catch (error) {
+        if (signal?.aborted || error?.name === "AbortError") break;
+        log("error", "wake pump tick failed; backing off", { reason: error?.message });
+      }
+      if (!signal?.aborted) await sleep(idle ? idleMs : 0, { signal });
+    }
+    return { fetchCursor: cursor };
+  }
+
+  return { tickOnce, start, ensureSeeded };
+}
+
+export default createWakePump;

package/src/session/wake/registry.js

@@ -0,0 +1,80 @@
+// Wake adapter registry for the Senti Wake-Up & Notification Bus (L2).
+//
+// Decouples the `sentid` daemon from individual host adapters: the daemon
+// depends only on the LOCKED adapter interface --
+//   { hostName: string, wake(target[, deps]) -> Promise<{ok, hostName, ...}> }
+//   (optionally installWakeHook(opts))
+// -- and concrete adapters (wake/claude.js, wake/codex.js, ...) are registered
+// at wiring time. This means the daemon can be built and unit-tested against a
+// fake adapter with no dependency on which adapter PRs have merged.
+
+function assertValidAdapter(adapter) {
+  if (!adapter || typeof adapter !== "object") {
+    throw new TypeError("wake registry: adapter must be an object");
+  }
+  if (typeof adapter.hostName !== "string" || adapter.hostName.trim() === "") {
+    throw new TypeError("wake registry: adapter.hostName must be a non-empty string");
+  }
+  if (typeof adapter.wake !== "function") {
+    throw new TypeError(`wake registry: adapter "${adapter.hostName}" must expose a wake() function`);
+  }
+  return adapter;
+}
+
+/**
+ * Create a wake-adapter registry, optionally seeded with adapters.
+ *
+ * @param {Array<{hostName: string, wake: Function}>} [adapters]
+ */
+export function createWakeRegistry(adapters = []) {
+  const map = new Map();
+
+  function hosts() {
+    return [...map.keys()];
+  }
+
+  function register(adapter) {
+    assertValidAdapter(adapter);
+    if (map.has(adapter.hostName)) {
+      throw new Error(`wake registry: adapter for host "${adapter.hostName}" is already registered`);
+    }
+    map.set(adapter.hostName, adapter);
+    return adapter;
+  }
+
+  function resolve(hostName) {
+    const adapter = map.get(hostName);
+    if (!adapter) {
+      throw new Error(
+        `wake registry: no adapter registered for host "${hostName}" (known: ${hosts().join(", ") || "none"})`
+      );
+    }
+    return adapter;
+  }
+
+  function has(hostName) {
+    return map.has(hostName);
+  }
+
+  if (!Array.isArray(adapters)) {
+    throw new TypeError("wake registry: adapters must be an array");
+  }
+  adapters.forEach(register);
+
+  return { register, resolve, has, hosts };
+}
+
+/**
+ * Wake an agent through the registry in one call. Forwards `deps` (e.g. an
+ * injected execFileImpl) to the resolved adapter's wake().
+ *
+ * @param {{resolve: Function}} registry
+ * @param {{ host: string, sessionId: string, message: string }} target
+ * @param {object} [deps]
+ */
+export async function wakeVia(registry, { host, sessionId, message } = {}, deps = {}) {
+  const adapter = registry.resolve(host);
+  return adapter.wake({ sessionId, message }, deps);
+}
+
+export default createWakeRegistry;

package/src/session/wake/resolve-target.js

@@ -0,0 +1,146 @@
+// Wake target resolver for the sentid daemon (Wake-Up Bus L2 live-wiring).
+//
+// A sentid instance serves one local agent. This factory builds the
+// resolveTarget(event) the dispatcher (dispatcher.js) calls to decide whether a
+// session event should wake THAT agent, and if so with what host/sessionId.
+//
+// Targeting policy (returning null = "intentionally unroutable", which the
+// dispatcher treats as a clean skip that advances the cursor):
+//   - only wake event TYPES count (a session_message), not acks/reactions/views;
+//   - never wake the agent on its OWN events (no self-wake loop);
+//   - wake when the message is directed to this agent, is a broadcast, or is an
+//     untargeted room message; a message directed to a DIFFERENT agent is null.
+//
+// Routing mirrors listener.js's eventMatchesAgent vocabulary, but is kept
+// self-contained on purpose: importing listener.js would drag its whole
+// transitive graph (auth/sync/`open`/...) into the wake daemon. The matcher
+// here is small enough to own.
+
+const BROADCAST_RECIPIENTS = new Set(["*", "all", "broadcast", "everyone", "anyone", "agents", "all-agents"]);
+const DEFAULT_WAKE_EVENT_TYPES = new Set(["session_message", "help_request"]);
+const MAX_WAKE_MESSAGE_CHARS = 16_000;
+
+function requireNonEmptyString(value, label) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new TypeError(`resolve-target: ${label} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function agentIdOf(event) {
+  const payload = event && typeof event.payload === "object" && event.payload ? event.payload : {};
+  const a = event?.agentId ?? event?.agent_id ?? event?.agent ?? payload.agentId ?? payload.agent_id;
+  if (a && typeof a === "object") return typeof a.id === "string" ? a.id : null;
+  return typeof a === "string" ? a : null;
+}
+
+function eventTypeOf(event) {
+  return event?.event || event?.type || event?.payload?.event || null;
+}
+
+function normalizeComparableId(value) {
+  return String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/^@+/, "")
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function addRecipientValue(out, value) {
+  if (value === undefined || value === null) return;
+  if (Array.isArray(value)) {
+    for (const item of value) addRecipientValue(out, item);
+    return;
+  }
+  if (value && typeof value === "object") {
+    addRecipientValue(out, value.id ?? value.agentId ?? value.agent_id ?? value.name);
+    return;
+  }
+  for (const token of String(value).split(/[\s,;]+/g)) {
+    const normalized = normalizeComparableId(token);
+    if (normalized) out.push(normalized);
+  }
+}
+
+// Collect recipient tokens from the shapes the session stream uses.
+function recipientsOf(event) {
+  const payload = event && typeof event.payload === "object" && event.payload ? event.payload : {};
+  const out = [];
+  for (const src of [
+    event?.to,
+    event?.recipient,
+    event?.recipients,
+    event?.targetAgent,
+    event?.targetAgentId,
+    payload.to,
+    payload.recipient,
+    payload.recipients,
+    payload.targetAgent,
+    payload.targetAgentId,
+  ]) {
+    addRecipientValue(out, src);
+  }
+  return out;
+}
+
+// Mirrors listener.js eventMatchesAgent: broadcast flag, broadcast tokens,
+// untargeted (no recipients) => match, or a directed match.
+function matchesAgent(event, selfLower) {
+  const payload = event && typeof event.payload === "object" && event.payload ? event.payload : {};
+  if (event?.broadcast === true || payload.broadcast === true) return true;
+  const recipients = recipientsOf(event);
+  if (recipients.length === 0) return true;
+  return recipients.some((r) => BROADCAST_RECIPIENTS.has(r) || r === selfLower);
+}
+
+function defaultFormatMessage(event, agentId) {
+  const author = agentIdOf(event) || "unknown";
+  const text = event?.payload?.message ?? event?.message ?? "";
+  const body = typeof text === "string" ? text : "";
+  const head = `Senti wake for ${agentId}: new message from ${author}.`;
+  const combined = body ? `${head}\n\n${body}` : head;
+  return combined.length > MAX_WAKE_MESSAGE_CHARS ? combined.slice(0, MAX_WAKE_MESSAGE_CHARS) : combined;
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.agentId   the local agent this daemon wakes (e.g. "claude-mythos")
+ * @param {string} opts.host      host adapter name (e.g. "claude")
+ * @param {string} opts.sessionId resume session id passed to the host adapter
+ * @param {Set<string>} [opts.wakeEventTypes]
+ * @param {(event:object, agentId:string) => string} [opts.formatMessage]
+ * @returns {(event:object) => ({host:string, sessionId:string, message:string}|null)}
+ */
+export function createResolveTarget({
+  agentId,
+  host,
+  sessionId,
+  wakeEventTypes = DEFAULT_WAKE_EVENT_TYPES,
+  formatMessage = defaultFormatMessage,
+} = {}) {
+  const selfId = requireNonEmptyString(agentId, "agentId");
+  const hostName = requireNonEmptyString(host, "host");
+  const resumeId = requireNonEmptyString(sessionId, "sessionId");
+  const selfLower = normalizeComparableId(selfId);
+
+  return function resolveTarget(event) {
+    // Only wake on real message events; acks/reactions/views/system are skips.
+    const type = eventTypeOf(event);
+    if (!type || !wakeEventTypes.has(type)) return null;
+
+    // No self-wake: never wake the agent on its own message. Normalize both
+    // sides (handles @-prefix / casing / punctuation) so the loop-guard can't
+    // be slipped by a non-canonical author id.
+    const author = agentIdOf(event);
+    if (author && normalizeComparableId(author) === selfLower) return null;
+
+    // Routing: directed-to-me / broadcast / untargeted-room wakes us; a message
+    // aimed at a different specific agent is intentionally unroutable.
+    if (!matchesAgent(event, selfLower)) return null;
+
+    return { host: hostName, sessionId: resumeId, message: formatMessage(event, selfId) };
+  };
+}
+
+export default createResolveTarget;

package/src/session/wake/sentid.js

@@ -0,0 +1,103 @@
+// sentid runtime entrypoint — assembles the Wake-Up Bus (L2) into a daemon.
+//
+// Wires the merged pieces into one local-agent waker:
+//   registry(host adapters) + resolveTarget(routing) + dispatcher(at-least-once
+//   + DLQ + RESUME cursor) + pump(live fetch -> dispatch -> persist).
+// A sentid instance serves ONE local agent (agentId) and wakes it (host +
+// resumeSessionId) when the session stream has a message for it.
+//
+// The real event source is pollSessionEvents (sync.js), but it is LAZY-imported
+// inside the default poll adapter so this module stays unit-testable: importing
+// sync.js at module load would drag the heavy auth/`open` graph in. Tests inject
+// `pollImpl` (and fake adapters) and the lazy import never fires.
+
+import { createWakeRegistry } from "./registry.js";
+import { createResolveTarget } from "./resolve-target.js";
+import { createWakeDispatcher } from "./dispatcher.js";
+import { createWakePump } from "./pump.js";
+import claudeWakeAdapter from "./claude.js";
+import codexWakeAdapter from "./codex.js";
+
+function requireNonEmptyString(value, label) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new TypeError(`sentid: ${label} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+// Adapt pollSessionEvents(sessionId, {since, targetPath}) -> the pump's
+// pollEvents(sessionId, {afterCursor}) -> { events, cursor } contract. A failed
+// poll (ok:false: circuit open / auth / network) yields no events, which the
+// pump treats as idle and retries on the next tick — never a thrown crash.
+function makePollEvents(pollImpl, targetPath) {
+  let poll = pollImpl;
+  return async (sessionId, { afterCursor = null } = {}) => {
+    if (!poll) {
+      ({ pollSessionEvents: poll } = await import("../sync.js"));
+    }
+    const result = (await poll(sessionId, { since: afterCursor, targetPath })) || {};
+    return {
+      events: Array.isArray(result.events) ? result.events : [],
+      cursor: typeof result.cursor === "string" ? result.cursor : afterCursor,
+    };
+  };
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.sessionId        Senti session to watch
+ * @param {string} opts.agentId          local agent this daemon wakes (e.g. "claude-mythos")
+ * @param {string} opts.host             host adapter name (e.g. "claude")
+ * @param {string} opts.resumeSessionId  host session id to resume on wake
+ * @param {Array} [opts.adapters]        defaults to [claudeWakeAdapter, codexWakeAdapter]
+ * @param {string} [opts.targetPath]
+ * @param {number} [opts.maxAttempts]    dispatcher retry budget before DLQ
+ * @param {number} [opts.idleMs]         pump idle backoff
+ * @param {Function} [opts.deadLetter]   durable DLQ sink
+ * @param {Function} [opts.logger]
+ * @param {Function} [opts.pollImpl]     injected poller (default: lazy pollSessionEvents)
+ * @param {object} [opts.wakeDeps]       deps forwarded to adapter.wake() (e.g. execFileImpl)
+ */
+export function createSentid({
+  sessionId,
+  agentId,
+  host,
+  resumeSessionId,
+  adapters = [claudeWakeAdapter, codexWakeAdapter],
+  targetPath,
+  maxAttempts,
+  idleMs,
+  deadLetter,
+  logger,
+  pollImpl,
+  wakeDeps = {},
+} = {}) {
+  const sid = requireNonEmptyString(sessionId, "sessionId");
+  const localAgent = requireNonEmptyString(agentId, "agentId");
+  const hostName = requireNonEmptyString(host, "host");
+  const resumeId = requireNonEmptyString(resumeSessionId, "resumeSessionId");
+
+  const registry = createWakeRegistry(adapters);
+  if (!registry.has(hostName)) {
+    throw new Error(`sentid: no adapter registered for host "${hostName}" (have: ${registry.hosts().join(", ") || "none"})`);
+  }
+
+  const resolveTarget = createResolveTarget({ agentId: localAgent, host: hostName, sessionId: resumeId });
+  const dispatcher = createWakeDispatcher({ registry, resolveTarget, maxAttempts, deadLetter, logger });
+  const pollEvents = makePollEvents(pollImpl, targetPath);
+  const pump = createWakePump({ sessionId: sid, dispatcher, pollEvents, targetPath, idleMs, logger });
+
+  return {
+    sessionId: sid,
+    agentId: localAgent,
+    host: hostName,
+    registry,
+    dispatcher,
+    pump,
+    start: (o = {}) => pump.start({ ...o, deps: wakeDeps }),
+    tickOnce: (o = {}) => pump.tickOnce({ ...o, deps: wakeDeps }),
+    getCursor: () => dispatcher.getCursor(),
+  };
+}
+
+export default createSentid;