@getfamiliar/shared 0.1.2

package/build/Event.d.ts

@@ -0,0 +1,280 @@
+/**
+ * Lifecycle states for an `events` row.
+ *
+ * Events are the immutable record of "the world said this happened".
+ * They no longer participate in any worker state machine themselves —
+ * the actual work runs in `agentruns` rows that reference the event.
+ *
+ * Transitions:
+ *
+ * - `pending`: row inserted by a host plugin via {@link EventBus.add}.
+ * - `running`: the container's input-event watcher has spawned the root
+ *   agentrun for this event.
+ * - `done` / `failed`: set reactively when the last `pending` /
+ *   `running` agentrun for this event settles. `failed` wins if any
+ *   agentrun for the event has failed.
+ */
+export type EventState = "pending" | "running" | "done" | "failed";
+/**
+ * Standard priority tiers for events. Higher = processed first.
+ * Producers should pick one of these rather than passing a bare number,
+ * unless they have a specific reason. The SQL default for `events.priority`
+ * is 50, matching `EVENT_PRIORITY.ASYNC`.
+ */
+export declare const EVENT_PRIORITY: {
+    /** Direct user chat (telegram, cli-chat). Preempts async work. */
+    readonly CHAT: 100;
+    /** Asynchronous external input — mail, group chat. Matches the SQL default. */
+    readonly ASYNC: 50;
+    /** Cron-driven background work. Yields to chat and async. */
+    readonly BACKGROUND: 10;
+};
+/**
+ * Shape of a row in the `events` table after JSON-decoding from postgres.
+ * The numeric `id` is kept as a string because postgres `bigint` exceeds
+ * JavaScript's safe integer range.
+ */
+export interface EventRow {
+    /**
+     * Database primary key. `bigserial` is returned as a string because
+     * postgres `bigint` exceeds JavaScript's safe integer range.
+     */
+    readonly id: string;
+    /**
+     * Event topic, matching `\w+(:\w+)*` (e.g. `mail`, `chat:whatsapp`,
+     * `chat:telegram:group:reaction`). Each `:`-separated segment maps
+     * to a folder when the container resolves the handler markdown.
+     */
+    readonly topic: string;
+    /**
+     * Higher = processed first within a queue. FIFO within priority.
+     * Default 50. Inherited by all agentruns spawned for this event.
+     */
+    readonly priority: number;
+    /** Lifecycle state — see {@link EventState}. */
+    readonly state: EventState;
+    /**
+     * Event-specific data; arbitrary JSON. Schema is owned by the
+     * producing plugin / topic, not by the bus.
+     */
+    readonly payload: unknown;
+    /**
+     * Globally unique key for dedup. `null` when the producer didn't
+     * supply one (then no dedup happens).
+     */
+    readonly idempotencyKey: string | null;
+    /**
+     * Whether this event is a chat message from the user. When `true`,
+     * `EventBus.add` mirrors `prompt` into `chatmessages` (role
+     * `'user'`) in the same transaction as the event INSERT, so the
+     * agent picks the message up via chat history rather than via the
+     * agentrun's `prompt` field.
+     */
+    readonly isChat: boolean;
+    /**
+     * Channel the assistant should reply on (e.g. `"cli"`, `"telegram"`).
+     * Stamped host-side at emit time, falling back to
+     * `DEFAULT_CHAT_CHANNEL_ID`. The container never reads this field;
+     * routing happens via JOIN in the chatmessages trigger and in
+     * `ChatMessageBus`. May be `null` for non-chat events whose source
+     * plugin didn't set a default routing target.
+     */
+    readonly preferredChatChannelId: string | null;
+    /**
+     * The event's primary user-visible text, written by the emitter.
+     * Always populated:
+     *
+     * - For chat events (`isChat=true`): the user's chat message. Also
+     *   mirrored into `chatmessages.text_content` (role `'user'`) by
+     *   `EventBus.add`, which is the channel the AgentRunner consumes.
+     * - For non-chat events: a first-person framing of what happened
+     *   ("A new mail from Anna arrived: …"). The EventWatcher copies
+     *   it into the root agentrun's `prompt` so the AgentRunner can
+     *   append it as the trailing user message.
+     */
+    readonly prompt: string;
+    /**
+     * Override for the root agentrun's handler. `null` means the
+     * input-event watcher uses `'index'` (i.e. resolves
+     * `<topic>/index.md`). Set by the emitter via
+     * {@link NewEvent.startHandler}; never mutated after insert.
+     */
+    readonly startHandler: string | null;
+    /**
+     * `true` when this event was emitted by a trusted user-input source
+     * (the operator at the local terminal via cli-chat, the operator on
+     * Telegram). Stamped at emit time, never mutated. Propagated verbatim
+     * to the root agentrun and to every child agentrun spawned via
+     * `schedule_subagent` / `start_subagent`, so future system tools can gate
+     * risky reads / writes
+     * (editing SOUL.md, etc.) on whether the run descends from a trusted
+     * input. `false` for everything else (mail, webhooks, cron-driven
+     * workflows).
+     */
+    readonly privileged: boolean;
+    /**
+     * When `true` and the event terminates in `failed`, the host writes
+     * a `role='assistant'` chatmessage `"Something went wrong processing
+     * the chat message: <error>"` to this event before signalling settle.
+     * Lets chat plugins surface failures through the ordinary chat
+     * subscription path without each needing its own catch-block
+     * rendering. No-op on `done`.
+     */
+    readonly outputChatOnFailure: boolean;
+    /** Insert timestamp — postgres `now()` at INSERT. */
+    readonly createdAt: Date;
+    /** Last `update()` timestamp — bumped to `now()` on every update. */
+    readonly updatedAt: Date;
+}
+/**
+ * One auxiliary file to attach to an event at emit time. The host writes
+ * each file under `<scratchDir>/<eventId>/<name>` inside the same
+ * transaction that inserts the event row, so the container watcher only
+ * ever observes events whose files are already on disk at
+ * `/scratch/<event-id>/<name>` inside both the agent and every MCP
+ * container.
+ *
+ * Two arms:
+ * - `contents` — Buffer the host writes directly. Use when bytes are
+ *   already in memory (e.g. just decoded from a base64 MCP response).
+ * - `sourcePath` — absolute host path to a file the plugin has already
+ *   written to disk. The host **moves** the file into the scratch dir
+ *   (`fs.rename`, falling back to copy+unlink across filesystems); the
+ *   plugin gives up ownership. Use for large files the plugin doesn't
+ *   want to re-buffer in memory.
+ *
+ * `name` is a basename. Path separators and `..` segments are rejected
+ * at emit; on collision within the same emit, the second file overwrites
+ * the first (caller's responsibility to keep names unique).
+ */
+export type EventFile = {
+    readonly name: string;
+    readonly contents: Buffer;
+} | {
+    readonly name: string;
+    readonly sourcePath: string;
+};
+/**
+ * Input shape for {@link EventBus.add}.
+ *
+ * `prompt` carries the event's primary user-visible text — for chat
+ * events it's the user's message; for everything else it's a
+ * first-person framing of what happened ("A new mail from Anna
+ * arrived: …"). `EventBus.add` validates that the value is non-empty
+ * after trimming, so plugins that bypass the type system still surface
+ * the bug at emit time instead of leaving the AgentRunner with an
+ * empty messages array.
+ *
+ * `payload` is optional structured supplementary data (Telegram
+ * `update_id`, WhatsApp `group_jid`, etc.) — it never carries the
+ * agent-visible text directly any more.
+ *
+ * `isChat` is just a flag. When `true`, `EventBus.add` mirrors
+ * `prompt` into the `chatmessages` table so the AgentRunner picks the
+ * message up via chat history; the agentrun's own `prompt` field
+ * stays null for chat events to avoid double-counting the trailing
+ * turn. The flag does not change the input shape — both arms have
+ * identical fields — so this stays a single interface rather than a
+ * discriminated union.
+ */
+export interface NewEvent {
+    readonly topic: string;
+    /**
+     * Primary user-visible text. Required, non-empty after trimming.
+     * See {@link NewEvent} for how it's persisted on each arm.
+     */
+    readonly prompt: string;
+    /** Optional structured supplementary data; arbitrary JSON. */
+    readonly payload?: unknown;
+    /** Higher = processed first; default 50. */
+    readonly priority?: number;
+    /** Initial state; default `"pending"`. */
+    readonly state?: EventState;
+    /** Globally unique key for dedup; null = no dedup. */
+    readonly idempotencyKey?: string;
+    /**
+     * Whether this event is a chat message from the user. Default
+     * `false`. See {@link NewEvent} for the persistence consequences.
+     */
+    readonly isChat?: boolean;
+    /**
+     * Channel id the assistant should reply on. Plugins typically set
+     * this to their own channel name (e.g. `"cli"`). When omitted, the
+     * host's `HostContextImpl.emit` stamps `DEFAULT_CHAT_CHANNEL_ID`.
+     *
+     * If the producer is not a chat plugin, this should be `null` or omitted.
+     */
+    readonly preferredChatChannelId?: string | null;
+    /**
+     * Whether this event originates from a trusted user-input source.
+     * Default `false` — the SQL column default covers omission. See
+     * {@link EventRow.privileged} for the trust-model rationale.
+     */
+    readonly privileged?: boolean;
+    /**
+     * When `true` and the event terminates in `failed`, the host writes
+     * a `role='assistant'` chatmessage carrying the failure text to this
+     * event before `handle.settled` rejects. Default `false` — the SQL
+     * column default covers omission. Chat plugins (cli-chat, telegram)
+     * set this to `true` so users see failures through the same chat
+     * subscription path that delivers normal replies. See
+     * {@link EventRow.outputChatOnFailure}.
+     */
+    readonly outputChatOnFailure?: boolean;
+    /**
+     * When set, EventBus.add inserts a `role='user'` chatmessage with
+     * this text in the same transaction as the event INSERT.
+     *
+     * Atomicity matters: a post-emit chatmessages INSERT acquires an
+     * FK row-lock on the events row that conflicts with the input-event
+     * watcher's `FOR UPDATE SKIP LOCKED` claim. If the watcher races
+     * the chatmessage write, `SKIP LOCKED` skips the row and — because
+     * the events_new NOTIFY has already been consumed — the event sits
+     * pending forever. Doing the chatmessage INSERT inside the same
+     * transaction closes the window: the FK lock is released before
+     * NOTIFY events_new fires post-commit.
+     *
+     * Use this for plugin emitters that want a chatmessage text
+     * different from `prompt` (e.g. cli-chat persists the slash-
+     * prefixed `/topic/handler …` line while the handler sees only
+     * the trailing prompt text). When unset and `isChat: true`, the
+     * existing path inserts `prompt` itself.
+     */
+    readonly userChatMessage?: string;
+    /**
+     * Override which handler markdown the root agentrun runs. When
+     * omitted, the input-event watcher uses `'index'` (i.e. resolves
+     * `<topic>/index.md`). Useful when an emitter wants to skip the
+     * triage `index.md` and invoke a specific handler directly.
+     *
+     * Pass the basename without `.md` (e.g. `'analyze'` resolves to
+     * `<topic>/analyze.md`). The agentrun fails loud at handler-load
+     * time if no such file exists — there is no shape validation
+     * here, mirroring how `topic` is only regex-checked, not
+     * existence-checked, at emit time.
+     */
+    readonly startHandler?: string;
+    /**
+     * Auxiliary files to stage at `/scratch/<event-id>/<name>` for this
+     * event. Visible to the agent and to every MCP container under the
+     * same absolute path. Staging happens atomically with the event
+     * INSERT (inside the same transaction), so the container watcher
+     * never sees an event whose files aren't yet on disk. See {@link
+     * EventFile} for the two payload shapes.
+     */
+    readonly files?: readonly EventFile[];
+}
+/** Patch shape for {@link EventBus.update}. */
+export interface EventPatch {
+    readonly state?: EventState;
+    readonly payload?: unknown;
+    readonly priority?: number;
+    readonly preferredChatChannelId?: string | null;
+}
+/** Filter for {@link EventBus.waitForNext}. */
+export interface EventFilter {
+    /** If set, only events whose topic is in this list will match. */
+    readonly topics?: readonly string[];
+    /** If set, only events in one of these states match (default `["pending"]`). */
+    readonly states?: readonly EventState[];
+}

package/build/Event.js

@@ -0,0 +1,14 @@
+/**
+ * Standard priority tiers for events. Higher = processed first.
+ * Producers should pick one of these rather than passing a bare number,
+ * unless they have a specific reason. The SQL default for `events.priority`
+ * is 50, matching `EVENT_PRIORITY.ASYNC`.
+ */
+export const EVENT_PRIORITY = {
+    /** Direct user chat (telegram, cli-chat). Preempts async work. */
+    CHAT: 100,
+    /** Asynchronous external input — mail, group chat. Matches the SQL default. */
+    ASYNC: 50,
+    /** Cron-driven background work. Yields to chat and async. */
+    BACKGROUND: 10,
+};

package/build/EventBus.d.ts

@@ -0,0 +1,198 @@
+import type { EventFilter, EventPatch, EventRow, EventState, NewEvent } from "./Event.js";
+import type { Logger } from "./logging/Logger.js";
+import type { PostgresConnection } from "./PostgresConnection.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 declare class DuplicateIdempotencyKeyError extends Error {
+    /** The colliding idempotency key, for logging by the catching emitter. */
+    readonly idempotencyKey: string;
+    /**
+     * @param idempotencyKey - The key that already existed in `events`.
+     */
+    constructor(idempotencyKey: string);
+}
+/**
+ * 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 declare class EventBus {
+    private readonly connection;
+    private readonly log;
+    private notifyWaiters;
+    private listenInstalled;
+    private readonly listenHandler;
+    /**
+     * @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: PostgresConnection, log?: Logger);
+    /**
+     * 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.
+     */
+    installSchema(): Promise<void>;
+    /**
+     * 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.
+     */
+    add(event: NewEvent, beforeCommit?: (row: EventRow) => Promise<void>): Promise<EventRow>;
+    /**
+     * 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.
+     */
+    getById(id: string): Promise<EventRow | 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.
+     */
+    listSince(since: Date): Promise<EventRow[]>;
+    /**
+     * 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)`.
+     */
+    listLatest(limit: number): Promise<EventRow[]>;
+    /**
+     * 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)`.
+     */
+    searchLatest(limit: number, needle: string): Promise<EventRow[]>;
+    /**
+     * 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.
+     */
+    listFiltered(filter: {
+        readonly limit: number;
+        readonly search?: string;
+        readonly state?: EventState;
+        readonly dateFrom?: Date;
+        readonly dateTo?: Date;
+    }): Promise<EventRow[]>;
+    /**
+     * Patch one or more fields on an existing event by id. Always bumps
+     * `updated_at`. No-op if `patch` contains no recognized fields.
+     */
+    update(id: string, patch: EventPatch): Promise<void>;
+    /**
+     * 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`.
+     */
+    waitForNext(filter?: EventFilter, signal?: AbortSignal): Promise<EventRow>;
+    /**
+     * 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}.
+     */
+    claim(fromState: EventState, toState: EventState): Promise<EventRow | 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`.
+     */
+    waitAndClaim(fromState: EventState, toState: EventState, signal?: AbortSignal): Promise<EventRow>;
+    /** Subscribe this bus's wake-handler to {@link EVENTS_NEW_CHANNEL}. */
+    private ensureListening;
+    /** Resolve as soon as the next NOTIFY arrives or `signal` aborts. */
+    private waitForNotification;
+    /** Single SELECT for the highest-priority matching pending event. */
+    private queryOne;
+}