@getfamiliar/shared 0.1.2

package/build/EventBus.js

@@ -0,0 +1,482 @@
+import { EVENTS_NEW_CHANNEL, SCHEMA_SQL } from "./Schema.js";
+/**
+ * Thrown by {@link EventBus.add} when an event's `idempotencyKey`
+ * collides with one already in the `events` table (Postgres unique
+ * violation `23505` on `events_idempotency_key_key`).
+ *
+ * The error is deliberately typed rather than swallowed: an emitter
+ * that re-derives the same key on a re-walk (the ms365 mail delta poll,
+ * the calendar poll, chat compaction, …) is expected to `catch` this
+ * and treat the collision as a no-op — the event already exists. Other
+ * emitters that should never collide let it propagate as a real fault.
+ */
+export class DuplicateIdempotencyKeyError extends Error {
+    /** The colliding idempotency key, for logging by the catching emitter. */
+    idempotencyKey;
+    /**
+     * @param idempotencyKey - The key that already existed in `events`.
+     */
+    constructor(idempotencyKey) {
+        super(`event with idempotency key "${idempotencyKey}" already exists`);
+        this.name = "DuplicateIdempotencyKeyError";
+        this.idempotencyKey = idempotencyKey;
+    }
+}
+/**
+ * True when `err` is the Postgres unique-constraint violation raised by
+ * inserting a duplicate `events.idempotency_key`. Mirrors the detection
+ * idiom previously hand-rolled in `ChatCompactor`/`WhatsAppDaemon`:
+ * pg error code `23505`, narrowed to the idempotency-key constraint so
+ * an unrelated unique violation isn't misclassified.
+ *
+ * @param err - The error thrown by the INSERT.
+ * @returns Whether it is the idempotency-key duplicate violation.
+ */
+function isIdempotencyKeyViolation(err) {
+    if (!(err instanceof Error)) {
+        return false;
+    }
+    const code = err.code;
+    if (code !== "23505") {
+        return false;
+    }
+    const constraint = err.constraint;
+    if (constraint) {
+        return constraint === "events_idempotency_key_key";
+    }
+    return err.message.includes("idempotency_key");
+}
+/**
+ * Domain client for the `events` table that backs the host ↔ container bus.
+ *
+ * Uses an injected {@link PostgresConnection} for pool + LISTEN access;
+ * does not own connection lifecycle. Several `EventBus` instances can
+ * share a connection, and the connection can be reused by other domain
+ * clients (e.g. {@link AgentRunBus}) without opening more sockets.
+ *
+ * Listens on `events_new` for wake-ups — the channel that fires on
+ * INSERT into `events`. State updates (which fire on `events_state`)
+ * are not consumed here; host plugins that need to wait for an event to
+ * settle should subscribe to that channel directly via
+ * {@link PostgresConnection.listen}.
+ *
+ * `waitForNext()` does an initial query before sleeping on the listen
+ * channel, so events that already existed when the call started are
+ * picked up immediately.
+ *
+ * The bus is *not* a multi-consumer queue: two waiters may observe the
+ * same event. Caller is responsible for transitioning state via
+ * {@link update} after handling.
+ */
+export class EventBus {
+    connection;
+    log;
+    notifyWaiters = [];
+    listenInstalled = false;
+    listenHandler = (payload) => {
+        this.log?.debug({ channel: EVENTS_NEW_CHANNEL, payload }, "NOTIFY events_new");
+        const waiters = this.notifyWaiters.splice(0);
+        for (const wake of waiters) {
+            wake();
+        }
+    };
+    /**
+     * @param connection - Shared pg pool / LISTEN handle.
+     * @param log - Optional logger; when set, NOTIFY arrivals are
+     *   debug-logged. Omitted on the host-side bus that runs inside
+     *   one-shot CLI commands so they stay quiet by default.
+     */
+    constructor(connection, log) {
+        this.connection = connection;
+        this.log = log;
+    }
+    /**
+     * Apply the events + agentruns schema (idempotent). Safe to call on
+     * every daemon start. The same SQL bundle is consumed by
+     * {@link AgentRunBus.installSchema}, so calling either is sufficient.
+     */
+    async installSchema() {
+        await this.connection.getPool().query(SCHEMA_SQL);
+    }
+    /**
+     * Insert a new event and return the persisted row.
+     *
+     * Transactional: when `event.isChat === true`, a `chatmessages`
+     * row (role `'user'`) carrying the same `prompt` text is inserted
+     * in the same transaction. Both NOTIFY triggers fire post-COMMIT,
+     * so listeners always observe consistent state.
+     *
+     * Validation: `prompt` must be a non-empty string after trimming —
+     * for any event, chat or not. The single check exists at this
+     * boundary so plugins that bypass the type system (untyped JS,
+     * unsafe casts) still surface the bug at emit time instead of
+     * leaving the AgentRunner with an empty messages array.
+     *
+     * `beforeCommit` runs **inside the transaction** after the event
+     * row (and any chat mirror) is inserted but before COMMIT. Use it
+     * for filesystem side-effects that must be atomic with the INSERT
+     * from the watcher's perspective — most importantly, staging
+     * `event.files` under `<scratchDir>/<row.id>/` so the container
+     * never observes an event without its scratch files in place.
+     * Throwing from `beforeCommit` rolls the INSERT back; cleaning up
+     * any partial filesystem state is the callback's responsibility.
+     *
+     * @throws {DuplicateIdempotencyKeyError} If `idempotencyKey` collides
+     *   with an existing event. Emitters that re-derive stable keys on a
+     *   re-walk are expected to catch this and treat it as a no-op.
+     * @throws If `topic` does not match `\w+(:\w+)*`, if `prompt` is
+     *   missing or whitespace-only, or if `beforeCommit` throws.
+     */
+    async add(event, beforeCommit) {
+        if (typeof event.prompt !== "string" || event.prompt.trim().length === 0) {
+            throw new Error("EventBus.add: every event requires a non-empty `prompt` (the agent-visible text)");
+        }
+        const isChat = event.isChat === true;
+        const prompt = event.prompt;
+        const client = await this.connection.getPool().connect();
+        try {
+            await client.query("BEGIN");
+            const result = await client.query(`INSERT INTO events
+                   (topic, payload, priority, state, idempotency_key,
+                    is_chat, preferred_chat_channel_id, prompt, privileged,
+                    start_handler, output_chat_on_failure)
+                 VALUES ($1, $2::jsonb, $3, $4, $5, $6, $7, $8, $9, $10, $11)
+                 RETURNING *`, [
+                event.topic,
+                JSON.stringify(event.payload ?? {}),
+                event.priority ?? 50,
+                event.state ?? "pending",
+                event.idempotencyKey ?? null,
+                isChat,
+                event.preferredChatChannelId ?? null,
+                prompt,
+                event.privileged ?? false,
+                event.startHandler ?? null,
+                event.outputChatOnFailure ?? false,
+            ]);
+            const row = mapRow(result.rows[0]);
+            // Atomic user-chatmessage insert. Two modes:
+            //   - `userChatMessage` set: insert that text verbatim,
+            //     irrespective of isChat. Used by plugins (cli-chat
+            //     direct calls) that want a chatmessage text different
+            //     from `prompt`.
+            //   - else `isChat: true`: insert `prompt` (back-compat
+            //     with chat-event emitters that don't know about the
+            //     new field).
+            //
+            // Doing the INSERT here, inside the same transaction as the
+            // event INSERT, ensures the FK row-lock is released before
+            // NOTIFY events_new fires post-commit — otherwise the
+            // input-event watcher's `FOR UPDATE SKIP LOCKED` claim can
+            // race with the chatmessages lock and leave the event
+            // stuck `pending` forever (the NOTIFY waiter is consumed
+            // even though `claim()` returned zero rows).
+            const chatMessageText = event.userChatMessage ?? (isChat ? prompt : undefined);
+            if (chatMessageText !== undefined) {
+                await client.query(`INSERT INTO chatmessages (event_id, role, text_content)
+                     VALUES ($1, 'user', $2)`, [row.id, chatMessageText]);
+            }
+            if (beforeCommit) {
+                await beforeCommit(row);
+            }
+            await client.query("COMMIT");
+            return row;
+        }
+        catch (err) {
+            try {
+                await client.query("ROLLBACK");
+            }
+            catch {
+                // best-effort rollback; preserve original error
+            }
+            // Translate the raw pg unique violation into a typed error so
+            // emitters that legitimately re-derive the same idempotency
+            // key (delta-poll re-walks, chat compaction races) can catch
+            // it by type instead of string-matching the pg message.
+            if (event.idempotencyKey && isIdempotencyKeyViolation(err)) {
+                throw new DuplicateIdempotencyKeyError(event.idempotencyKey);
+            }
+            throw err;
+        }
+        finally {
+            client.release();
+        }
+    }
+    /**
+     * Fetch one event by id. Returns `undefined` if not found. Mirrors
+     * {@link import("./StepResultBus").StepResultBus.getById} so
+     * notification consumers can promote a payload-only id into a full
+     * typed row without a hand-written query.
+     */
+    async getById(id) {
+        const result = await this.connection
+            .getPool()
+            .query(`SELECT * FROM events WHERE id = $1`, [id]);
+        return result.rows.length > 0 ? mapRow(result.rows[0]) : undefined;
+    }
+    /**
+     * Fetch all event rows whose `updated_at` is `>= since`, ordered by
+     * `(updated_at, id)`. Used by the polling-based report layer to
+     * pick up new inserts and state transitions without subscribing to
+     * NOTIFY. Returns an empty array when nothing changed since the
+     * anchor.
+     */
+    async listSince(since) {
+        const result = await this.connection.getPool().query(`SELECT * FROM events
+                 WHERE updated_at >= $1
+                 ORDER BY updated_at, id`, [since]);
+        return result.rows.map(mapRow);
+    }
+    /**
+     * Fetch the most recently created N event rows, newest first. Used by
+     * `./cli.sh events list` to surface recent bus activity for operators
+     * looking for an event id to inspect with `events report <id>`.
+     *
+     * @param limit Maximum number of rows to return. Must be a positive integer.
+     * @returns Up to `limit` event rows ordered by descending `(created_at, id)`.
+     */
+    async listLatest(limit) {
+        const result = await this.connection.getPool().query(`SELECT * FROM events
+                 ORDER BY created_at DESC, id DESC
+                 LIMIT $1`, [limit]);
+        return result.rows.map(mapRow);
+    }
+    /**
+     * Fetch the most recently created N event rows whose topic, start_handler,
+     * prompt, or payload (cast to text) case-insensitively contains `needle`.
+     * Used by `./cli.sh events list <search>` so the operator can grep the
+     * recent bus without piping through `grep`.
+     *
+     * Substring match via `ILIKE '%needle%'`; the needle is escaped for the
+     * SQL `LIKE` metacharacters `%`, `_`, and `\`. No index is added — at
+     * interactive scale a sequential scan is fine.
+     *
+     * @param limit Maximum number of rows to return. Must be a positive integer.
+     * @param needle Case-insensitive substring to search for.
+     * @returns Up to `limit` matching event rows ordered by descending `(created_at, id)`.
+     */
+    async searchLatest(limit, needle) {
+        const pattern = `%${needle.replace(/[\\%_]/g, (c) => `\\${c}`)}%`;
+        const result = await this.connection.getPool().query(`SELECT * FROM events
+                 WHERE topic                          ILIKE $2
+                    OR coalesce(start_handler, '')    ILIKE $2
+                    OR coalesce(prompt, '')           ILIKE $2
+                    OR payload::text                  ILIKE $2
+                 ORDER BY created_at DESC, id DESC
+                 LIMIT $1`, [limit, pattern]);
+        return result.rows.map(mapRow);
+    }
+    /**
+     * Latest N event rows matching every supplied filter. Drives the
+     * agent-facing `event_list` reflection tool, which lets the agent
+     * narrow by state, date window, and free-text needle simultaneously
+     * — combinations the older {@link listLatest} / {@link searchLatest}
+     * pair can't express. Both of those stay as the CLI's call sites.
+     *
+     * Substring match (when `search` is set) is the same ILIKE-against-
+     * `(topic, start_handler, prompt, payload::text)` predicate
+     * {@link searchLatest} uses. `dateFrom` is inclusive, `dateTo` is
+     * exclusive (`created_at >= $from AND created_at < $to`), so the
+     * agent can pass two midnights to get a single local day without
+     * worrying about the boundary instant.
+     */
+    async listFiltered(filter) {
+        const conditions = [];
+        const values = [];
+        let n = 1;
+        if (filter.search !== undefined && filter.search.length > 0) {
+            const pattern = `%${filter.search.replace(/[\\%_]/g, (c) => `\\${c}`)}%`;
+            conditions.push(`(topic ILIKE $${n} OR coalesce(start_handler, '') ILIKE $${n} ` +
+                `OR coalesce(prompt, '') ILIKE $${n} OR payload::text ILIKE $${n})`);
+            values.push(pattern);
+            n++;
+        }
+        if (filter.state !== undefined) {
+            conditions.push(`state = $${n++}`);
+            values.push(filter.state);
+        }
+        if (filter.dateFrom !== undefined) {
+            conditions.push(`created_at >= $${n++}`);
+            values.push(filter.dateFrom);
+        }
+        if (filter.dateTo !== undefined) {
+            conditions.push(`created_at < $${n++}`);
+            values.push(filter.dateTo);
+        }
+        const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+        values.push(filter.limit);
+        const limitParam = `$${n}`;
+        const result = await this.connection.getPool().query(`SELECT * FROM events
+             ${where}
+             ORDER BY created_at DESC, id DESC
+             LIMIT ${limitParam}`, values);
+        return result.rows.map(mapRow);
+    }
+    /**
+     * Patch one or more fields on an existing event by id. Always bumps
+     * `updated_at`. No-op if `patch` contains no recognized fields.
+     */
+    async update(id, patch) {
+        const sets = ["updated_at = now()"];
+        const values = [];
+        let n = 1;
+        if (patch.state !== undefined) {
+            sets.push(`state = $${n++}`);
+            values.push(patch.state);
+        }
+        if (patch.payload !== undefined) {
+            sets.push(`payload = $${n++}::jsonb`);
+            values.push(JSON.stringify(patch.payload));
+        }
+        if (patch.priority !== undefined) {
+            sets.push(`priority = $${n++}`);
+            values.push(patch.priority);
+        }
+        if (patch.preferredChatChannelId !== undefined) {
+            sets.push(`preferred_chat_channel_id = $${n++}`);
+            values.push(patch.preferredChatChannelId);
+        }
+        values.push(id);
+        const idParam = `$${n}`;
+        await this.connection
+            .getPool()
+            .query(`UPDATE events SET ${sets.join(", ")} WHERE id = ${idParam}`, values);
+    }
+    /**
+     * Block until an event matching `filter` is in the table. Returns
+     * the highest-priority such event (FIFO within priority). Subscribes
+     * to `LISTEN events_new` on first call so subsequent waits sleep
+     * until a NOTIFY arrives instead of polling.
+     *
+     * **Read-only**: does not mutate the row. For multi-consumer queues,
+     * use {@link waitAndClaim} instead, which atomically transitions the
+     * row's state on read.
+     *
+     * @param filter - Topic / state filter; default `{ states: ["pending"] }`.
+     * @param signal - Optional AbortSignal to cancel the wait.
+     * @throws If aborted via `signal`.
+     */
+    async waitForNext(filter = {}, signal) {
+        await this.ensureListening();
+        for (;;) {
+            if (signal?.aborted) {
+                throw new Error("waitForNext aborted");
+            }
+            const row = await this.queryOne(filter);
+            if (row) {
+                return row;
+            }
+            await this.waitForNotification(signal);
+        }
+    }
+    /**
+     * Atomically transition the highest-priority event in `fromState` to
+     * `toState` and return the updated row. Race-safe across multiple
+     * concurrent workers via `FOR UPDATE SKIP LOCKED`.
+     *
+     * Returns `undefined` if no row is in `fromState`. Non-blocking — for
+     * blocking semantics, use {@link waitAndClaim}.
+     */
+    async claim(fromState, toState) {
+        const result = await this.connection.getPool().query(`UPDATE events
+             SET state = $1, updated_at = now()
+             WHERE id = (
+               SELECT id FROM events
+               WHERE state = $2
+               ORDER BY priority DESC, id ASC
+               FOR UPDATE SKIP LOCKED
+               LIMIT 1
+             )
+             RETURNING *`, [toState, fromState]);
+        return result.rows.length > 0 ? mapRow(result.rows[0]) : undefined;
+    }
+    /**
+     * Block until an event in `fromState` is available, then atomically
+     * claim it (transition to `toState`) and return it. Combines
+     * {@link claim} with the LISTEN/NOTIFY wait loop used by
+     * {@link waitForNext}.
+     *
+     * @throws If aborted via `signal`.
+     */
+    async waitAndClaim(fromState, toState, signal) {
+        await this.ensureListening();
+        for (;;) {
+            if (signal?.aborted) {
+                throw new Error("waitAndClaim aborted");
+            }
+            const row = await this.claim(fromState, toState);
+            if (row) {
+                return row;
+            }
+            await this.waitForNotification(signal);
+        }
+    }
+    /** Subscribe this bus's wake-handler to {@link EVENTS_NEW_CHANNEL}. */
+    async ensureListening() {
+        if (this.listenInstalled) {
+            return;
+        }
+        this.listenInstalled = true;
+        await this.connection.listen(EVENTS_NEW_CHANNEL, this.listenHandler);
+    }
+    /** Resolve as soon as the next NOTIFY arrives or `signal` aborts. */
+    waitForNotification(signal) {
+        return new Promise((resolve, reject) => {
+            const wake = () => {
+                if (signal) {
+                    signal.removeEventListener("abort", onAbort);
+                }
+                resolve();
+            };
+            const onAbort = () => {
+                this.notifyWaiters = this.notifyWaiters.filter((w) => w !== wake);
+                reject(new Error("waitForNext aborted"));
+            };
+            this.notifyWaiters.push(wake);
+            if (signal) {
+                signal.addEventListener("abort", onAbort, { once: true });
+            }
+        });
+    }
+    /** Single SELECT for the highest-priority matching pending event. */
+    async queryOne(filter) {
+        const states = filter.states ?? ["pending"];
+        const conditions = ["state = ANY($1)"];
+        const values = [states];
+        let n = 2;
+        if (filter.topics && filter.topics.length > 0) {
+            conditions.push(`topic = ANY($${n++})`);
+            values.push(filter.topics);
+        }
+        const result = await this.connection.getPool().query(`SELECT * FROM events
+             WHERE ${conditions.join(" AND ")}
+             ORDER BY priority DESC, id ASC
+             LIMIT 1`, values);
+        return result.rows.length > 0 ? mapRow(result.rows[0]) : undefined;
+    }
+}
+/**
+ * Convert a snake_case raw row into the camelCase {@link EventRow}.
+ *
+ * The DB column is `text` with no CHECK constraint on the value, so
+ * `raw.state` is trusted to be a known {@link EventState} (we control
+ * every writer).
+ */
+function mapRow(raw) {
+    return {
+        id: raw.id,
+        topic: raw.topic,
+        priority: raw.priority,
+        state: raw.state,
+        payload: raw.payload,
+        idempotencyKey: raw.idempotency_key,
+        isChat: raw.is_chat,
+        preferredChatChannelId: raw.preferred_chat_channel_id,
+        prompt: raw.prompt ?? "",
+        startHandler: raw.start_handler,
+        privileged: raw.privileged,
+        outputChatOnFailure: raw.output_chat_on_failure,
+        createdAt: raw.created_at,
+        updatedAt: raw.updated_at,
+    };
+}

package/build/HandlerCatalog.d.ts

@@ -0,0 +1,75 @@
+/**
+ * One handler entry surfaced by {@link HandlerCatalog.list}.
+ *
+ * Encodes the same notion as the container's `HandlerFile`: a topic
+ * (one or more `:`-separated segments) plus a basename. `slashPath`
+ * is the user-facing form the cli-chat prompt accepts as a direct
+ * handler call (e.g. `/grocery/fruits/order`).
+ */
+export interface HandlerPath {
+    /** Colon-separated topic, e.g. `chat:telegram`. */
+    readonly topic: string;
+    /** Handler basename without `.md`, e.g. `index`, `analyze`. */
+    readonly handler: string;
+    /** Absolute path on disk of the handler file. */
+    readonly absolutePath: string;
+    /** Workspace-relative posix path, e.g. `chat/telegram/index.md`. */
+    readonly relativePath: string;
+    /** User-facing slash form, e.g. `/chat/telegram/index`. */
+    readonly slashPath: string;
+}
+/**
+ * Read-only view over the `workspace/` directory's handler files.
+ *
+ * Mirrors the resolution semantics implemented by
+ * `container/src/HandlerFile.ts` so host-side code (CLI, cron
+ * scheduler introspection, tab-completion) can answer "does this
+ * handler exist?" and "list every handler" without depending on
+ * container internals or reimplementing the topic-walk inheritance.
+ *
+ * The catalog is stateless on the disk — every method re-scans —
+ * so live workspace edits are reflected without a daemon restart.
+ * At REPL frequencies this is cheap; if a hot path later needs
+ * caching it can wrap an instance.
+ */
+export declare class HandlerCatalog {
+    private readonly workspaceDir;
+    private readonly writablePathGlobs;
+    /**
+     * @param workspaceDir Absolute path of the `workspace/` directory.
+     * @param writablePathGlobs `core.writablePaths` globs (e.g. `wiki/**`).
+     *   Files under these are writable by non-privileged runs and are
+     *   therefore never handlers — they are excluded from {@link list}
+     *   and {@link resolve} so they are never proposed or resolved as a
+     *   handler. Mirrors the container's `HandlerFile.load` guard.
+     */
+    constructor(workspaceDir: string, writablePathGlobs?: readonly string[]);
+    /**
+     * Walk `workspace/` and return one {@link HandlerPath} per
+     * candidate handler file. Excludes the global-context files at
+     * the workspace root (`SOUL.md`, `CONTEXT.md`)
+     * and the `skills/` subtree. Every other `.md` file under a topic
+     * directory is included, even if it's a knowledge file (e.g.
+     * `people/anna.md`) — `HandlerCatalog` does not police what is or
+     * isn't a "proper" handler; that's a handler-loading concern.
+     *
+     * Sorted by `slashPath` for stable display ordering in
+     * tab-completion. Returns an empty array when the workspace
+     * directory does not exist.
+     */
+    list(): Promise<readonly HandlerPath[]>;
+    /**
+     * Resolve a handler call: given a topic (e.g. `chat:telegram`)
+     * and a basename (e.g. `index`), return the absolute path of the
+     * deepest existing handler file, mirroring the container's
+     * inheritance walk.
+     *
+     * For topic `a:b:c` and basename `x` the resolution tries, in
+     * order: `a/b/c/x.md`, `a/b/x.md`, `a/x.md`. Returns the first
+     * existing path or `null` if none exist. The deepest existing
+     * file is what `HandlerFile.load` would treat as the leaf — for
+     * cli-chat existence checks, that's exactly the question we
+     * want answered.
+     */
+    resolve(topic: string, handler: string): Promise<string | null>;
+}