@getfamiliar/shared 0.1.2

package/build/Plugin.js

@@ -0,0 +1,29 @@
+/**
+ * Thrown by `ctx.events.emit().settled` when the host daemon stops
+ * (or crashes) while a one-shot CLI command was waiting for the event
+ * to reach a terminal state. Catch and exit cleanly — there is no
+ * postgres on the other side to recover state from.
+ */
+export class DaemonStoppedError extends Error {
+    constructor(message = "Host daemon stopped") {
+        super(message);
+        this.name = "DaemonStoppedError";
+    }
+}
+/**
+ * Identity function used by plugins to declare their manifest:
+ *
+ * ```ts
+ * export default definePlugin({
+ *   id: "cli-chat",
+ *   host: { commands: (ctx) => [sendCommand(ctx)] },
+ * });
+ * ```
+ *
+ * Exists purely so TypeScript narrows literal types correctly without
+ * the caller writing a `satisfies PluginManifest` clause. Same pattern
+ * as Vite's `defineConfig` / Astro's `defineConfig`.
+ */
+export function definePlugin(plugin) {
+    return plugin;
+}

package/build/PostgresConnection.d.ts

@@ -0,0 +1,75 @@
+import { type Pool } from "pg";
+/**
+ * Hardcoded user / database / network coordinates for the dev bus-state
+ * DB. Both ends of the bus import these so they don't drift.
+ *
+ * - {@link POSTGRES_HOST} is both the docker container `--name` (used by
+ *   `PostgresContainer` on the host) and the DNS name the agent
+ *   container resolves over `familiar-net`.
+ * - {@link POSTGRES_PORT} is the in-container postgres port — the
+ *   *internal* side of the host's loopback `-p` mapping, and the port
+ *   the agent container connects to over `familiar-net`.
+ *
+ * The password is *not* a constant — it lives in `.env`
+ * (`POSTGRES_PASSWORD`) and is passed explicitly to
+ * `PostgresConnection`.
+ */
+export declare const POSTGRES_HOST = "familiar-postgres";
+export declare const POSTGRES_PORT = 5432;
+export declare const POSTGRES_USER = "familiar";
+export declare const POSTGRES_DB = "familiar";
+/** Connection coordinates for a postgres database. */
+export interface PostgresConnectionConfig {
+    readonly host: string;
+    readonly port: number;
+    readonly user: string;
+    readonly password: string;
+    readonly database: string;
+}
+/** Callback fired when a NOTIFY arrives on a subscribed channel. */
+export type NotificationHandler = (payload: string) => void;
+/**
+ * Wraps a postgres pool plus an optional dedicated `LISTEN` client.
+ *
+ * - `getPool()` lazily builds a normal connection pool for queries.
+ * - `listen()`/`unlisten()` lazily open a single long-lived client
+ *   dedicated to receiving asynchronous NOTIFYs. Multiple consumers can
+ *   subscribe to the same channel; each registered handler is invoked
+ *   for every notification on that channel.
+ *
+ * Domain classes (e.g. `EventBus`) take a `PostgresConnection` rather
+ * than connection coordinates so they can share one pool / one listen
+ * client across the process.
+ */
+export declare class PostgresConnection {
+    private readonly poolConfig;
+    private pool;
+    private listenClient;
+    private listenClientReady;
+    private readonly handlersByChannel;
+    constructor(config: PostgresConnectionConfig);
+    /** Lazily build (and reuse) the connection pool for normal queries. */
+    getPool(): Pool;
+    /**
+     * Subscribe to a postgres NOTIFY channel. The dedicated LISTEN
+     * connection is opened on first call. Multiple handlers per channel
+     * are supported; the same handler can be registered only once.
+     *
+     * @param channel - SQL identifier for the channel. Must already be
+     *   safe to interpolate (validated to avoid injection).
+     * @param handler - Callback invoked with each notification's payload.
+     */
+    listen(channel: string, handler: NotificationHandler): Promise<void>;
+    /**
+     * Remove a previously registered handler. Issues `UNLISTEN` once the
+     * last handler for a channel is removed.
+     */
+    unlisten(channel: string, handler: NotificationHandler): Promise<void>;
+    /** End the pool and the LISTEN client. Idempotent. */
+    close(): Promise<void>;
+    /**
+     * Ensure the dedicated LISTEN client is connected and dispatch
+     * notifications to all registered handlers for the channel.
+     */
+    private ensureListenClient;
+}

package/build/PostgresConnection.js

@@ -0,0 +1,162 @@
+import { default as pg } from "pg";
+const { Pool: PgPool, Client: PgClient } = pg;
+/**
+ * Hardcoded user / database / network coordinates for the dev bus-state
+ * DB. Both ends of the bus import these so they don't drift.
+ *
+ * - {@link POSTGRES_HOST} is both the docker container `--name` (used by
+ *   `PostgresContainer` on the host) and the DNS name the agent
+ *   container resolves over `familiar-net`.
+ * - {@link POSTGRES_PORT} is the in-container postgres port — the
+ *   *internal* side of the host's loopback `-p` mapping, and the port
+ *   the agent container connects to over `familiar-net`.
+ *
+ * The password is *not* a constant — it lives in `.env`
+ * (`POSTGRES_PASSWORD`) and is passed explicitly to
+ * `PostgresConnection`.
+ */
+export const POSTGRES_HOST = "familiar-postgres";
+export const POSTGRES_PORT = 5432;
+export const POSTGRES_USER = "familiar";
+export const POSTGRES_DB = "familiar";
+/**
+ * Wraps a postgres pool plus an optional dedicated `LISTEN` client.
+ *
+ * - `getPool()` lazily builds a normal connection pool for queries.
+ * - `listen()`/`unlisten()` lazily open a single long-lived client
+ *   dedicated to receiving asynchronous NOTIFYs. Multiple consumers can
+ *   subscribe to the same channel; each registered handler is invoked
+ *   for every notification on that channel.
+ *
+ * Domain classes (e.g. `EventBus`) take a `PostgresConnection` rather
+ * than connection coordinates so they can share one pool / one listen
+ * client across the process.
+ */
+export class PostgresConnection {
+    poolConfig;
+    pool;
+    listenClient;
+    listenClientReady;
+    handlersByChannel = new Map();
+    constructor(config) {
+        this.poolConfig = {
+            host: config.host,
+            port: config.port,
+            user: config.user,
+            password: config.password,
+            database: config.database,
+        };
+    }
+    /** Lazily build (and reuse) the connection pool for normal queries. */
+    getPool() {
+        if (!this.pool) {
+            this.pool = new PgPool(this.poolConfig);
+        }
+        return this.pool;
+    }
+    /**
+     * Subscribe to a postgres NOTIFY channel. The dedicated LISTEN
+     * connection is opened on first call. Multiple handlers per channel
+     * are supported; the same handler can be registered only once.
+     *
+     * @param channel - SQL identifier for the channel. Must already be
+     *   safe to interpolate (validated to avoid injection).
+     * @param handler - Callback invoked with each notification's payload.
+     */
+    async listen(channel, handler) {
+        validateChannelName(channel);
+        const client = await this.ensureListenClient();
+        let handlers = this.handlersByChannel.get(channel);
+        const isFirstSubscriber = !handlers;
+        if (!handlers) {
+            handlers = new Set();
+            this.handlersByChannel.set(channel, handlers);
+        }
+        handlers.add(handler);
+        if (isFirstSubscriber) {
+            await client.query(`LISTEN ${channel}`);
+        }
+    }
+    /**
+     * Remove a previously registered handler. Issues `UNLISTEN` once the
+     * last handler for a channel is removed.
+     */
+    async unlisten(channel, handler) {
+        validateChannelName(channel);
+        const handlers = this.handlersByChannel.get(channel);
+        if (!handlers) {
+            return;
+        }
+        handlers.delete(handler);
+        if (handlers.size === 0) {
+            this.handlersByChannel.delete(channel);
+            if (this.listenClient) {
+                await this.listenClient.query(`UNLISTEN ${channel}`);
+            }
+        }
+    }
+    /** End the pool and the LISTEN client. Idempotent. */
+    async close() {
+        this.handlersByChannel.clear();
+        if (this.listenClient) {
+            try {
+                await this.listenClient.end();
+            }
+            catch {
+                // best-effort
+            }
+            this.listenClient = undefined;
+            this.listenClientReady = undefined;
+        }
+        if (this.pool) {
+            await this.pool.end();
+            this.pool = undefined;
+        }
+    }
+    /**
+     * Ensure the dedicated LISTEN client is connected and dispatch
+     * notifications to all registered handlers for the channel.
+     */
+    async ensureListenClient() {
+        if (!this.listenClientReady) {
+            this.listenClientReady = (async () => {
+                const client = new PgClient(this.poolConfig);
+                await client.connect();
+                client.on("notification", (msg) => {
+                    if (!msg.channel) {
+                        return;
+                    }
+                    const handlers = this.handlersByChannel.get(msg.channel);
+                    if (!handlers) {
+                        return;
+                    }
+                    for (const handler of handlers) {
+                        try {
+                            handler(msg.payload ?? "");
+                        }
+                        catch (err) {
+                            console.error(`PostgresConnection notification handler error: ${err instanceof Error ? err.message : String(err)}`);
+                        }
+                    }
+                });
+                client.on("error", (err) => {
+                    console.error(`PostgresConnection listen client error: ${err.message}`);
+                });
+                this.listenClient = client;
+                return client;
+            })();
+        }
+        return this.listenClientReady;
+    }
+}
+const CHANNEL_NAME_RE = /^[a-z_][a-z0-9_]*$/i;
+/**
+ * Reject channel names that aren't safe to interpolate into a `LISTEN`
+ * statement. Postgres identifiers can be quoted, but for simplicity we
+ * restrict to plain `[a-z_][a-z0-9_]*`.
+ */
+function validateChannelName(channel) {
+    if (!CHANNEL_NAME_RE.test(channel)) {
+        throw new Error(`Invalid channel name: ${channel}`);
+    }
+}

package/build/ScheduledSubagent.d.ts

@@ -0,0 +1,49 @@
+/**
+ * A persisted row in `scheduled_subagents` — one future one-off wake-up
+ * the agent has asked the host to fire. Only produced when the agent
+ * called `schedule_subagent` with a future `when`; without `when`, the
+ * tool inserts a child agentrun directly instead and never touches
+ * this table. Lifecycle:
+ *
+ * 1. Container's `schedule_subagent` tool upserts (on `key`) a row with
+ *    `fireAt` in UTC, copying the calling agentrun's `priority` and
+ *    `privileged` flag.
+ * 2. Host's `ScheduledSubagentScheduler` reacts to the
+ *    `scheduled_subagents_changed` NOTIFY and installs a Croner job for
+ *    `fireAt` with `maxRuns: 1`.
+ * 3. When the job fires, the host atomically claims-and-deletes the
+ *    row, then emits a fresh event with the row's topic / handler /
+ *    prompt / payload / priority / privileged.
+ *
+ * `prompt` is optional at the table level so the agent can schedule
+ * "the handler knows what to do" wake-ups; the firing path supplies
+ * a generic default (`Scheduled subagent fired`) before calling
+ * `EventBus.add`, which requires a non-empty prompt.
+ */
+export interface ScheduledSubagentRow {
+    /** Agent-supplied unique id. UPSERT target. */
+    readonly key: string;
+    /** UTC ISO-8601 firing time (e.g. `2026-05-21T13:00:00Z`). */
+    readonly fireAt: string;
+    readonly topic: string;
+    readonly handler: string;
+    readonly prompt: string | null;
+    readonly payload: unknown;
+    readonly priority: number;
+    readonly privileged: boolean;
+    readonly createdAt: Date;
+}
+/**
+ * Insert shape for {@link ScheduledSubagentBus.upsert}. Mirrors
+ * {@link ScheduledSubagentRow} minus `createdAt` (filled by the DB).
+ */
+export interface NewScheduledSubagent {
+    readonly key: string;
+    readonly fireAt: string;
+    readonly topic: string;
+    readonly handler: string;
+    readonly prompt?: string | null;
+    readonly payload?: unknown;
+    readonly priority?: number;
+    readonly privileged?: boolean;
+}

package/build/ScheduledSubagent.js

@@ -0,0 +1 @@
+export {};

package/build/ScheduledSubagentBus.d.ts

@@ -0,0 +1,94 @@
+import type { Logger } from "./logging/Logger.js";
+import type { PostgresConnection } from "./PostgresConnection.js";
+import type { NewScheduledSubagent, ScheduledSubagentRow } from "./ScheduledSubagent.js";
+/** Disposer returned by {@link ScheduledSubagentBus.listen}. */
+export type ScheduledSubagentUnsubscribe = () => Promise<void>;
+/** Notification operation extracted from a NOTIFY payload. */
+export type ScheduledSubagentOp = "u" | "d";
+/** Parsed notification handed to {@link ScheduledSubagentBus.listen} subscribers. */
+export interface ScheduledSubagentNotification {
+    readonly key: string;
+    readonly op: ScheduledSubagentOp;
+}
+/**
+ * Domain client for the `scheduled_subagents` table — agent-requested
+ * one-off wake-ups. Used by both sides of the bus:
+ *
+ * - Container: the `schedule_subagent` / `unschedule_subagent` /
+ *   `get_scheduled_subagents` tools call {@link upsert} / {@link deleteByKey}
+ *   / {@link listInRange}.
+ * - Host: the `ScheduledSubagentScheduler` calls {@link listFuture} at
+ *   startup, listens via {@link listen} for live changes, and uses
+ *   {@link claimAndDeleteForFiring} to consume a row at fire time.
+ *
+ * All times are stored and returned as UTC ISO-8601 strings; the
+ * caller is responsible for projecting into the user's
+ * `core.timezone` for agent-facing surfaces.
+ */
+export declare class ScheduledSubagentBus {
+    private readonly connection;
+    private readonly log;
+    constructor(connection: PostgresConnection, log?: Logger);
+    /**
+     * Apply the bus-state schema (idempotent). Same SQL bundle as
+     * {@link import("./EventBus").EventBus.installSchema}, so calling
+     * any of the three install methods is sufficient on daemon start.
+     */
+    installSchema(): Promise<void>;
+    /**
+     * Insert a scheduled subagent or replace the existing row with the
+     * same `key`. Returns the persisted row.
+     *
+     * Atomic UPSERT semantics: if the agent re-schedules a key, the
+     * old row is overwritten in one statement so the host scheduler
+     * sees exactly one NOTIFY and installs exactly one job.
+     *
+     * @throws If `topic` does not match `\w+(:\w+)*` (CHECK constraint).
+     */
+    upsert(row: NewScheduledSubagent): Promise<ScheduledSubagentRow>;
+    /**
+     * Remove a row by key. Returns `true` when a row was removed,
+     * `false` when no row existed for the key.
+     */
+    deleteByKey(key: string): Promise<boolean>;
+    /** Fetch a row by key, or `undefined` when missing. */
+    getByKey(key: string): Promise<ScheduledSubagentRow | undefined>;
+    /**
+     * Atomic claim-and-delete for the firing path: DELETE the row by
+     * key and return it (or `undefined` if it was already gone — the
+     * agent may have unscheduled the key in the window between the
+     * Croner trigger and this query).
+     */
+    claimAndDeleteForFiring(key: string): Promise<ScheduledSubagentRow | undefined>;
+    /**
+     * List every row whose `fire_at` falls inside `[fromUtc, toUtc)`,
+     * ordered by `fire_at ASC`. Range is half-open so a `day` query
+     * built from {@link import("./Timezone").dayBoundsInZone} returns
+     * exactly the rows belonging to that day in the caller's zone.
+     */
+    listInRange(fromUtc: string, toUtc: string): Promise<ScheduledSubagentRow[]>;
+    /**
+     * Load every row whose `fire_at` is at or after `nowUtc`. Used by
+     * the host scheduler on daemon startup to re-install Croner jobs
+     * for every still-future scheduled subagent.
+     */
+    listFuture(nowUtc: string): Promise<ScheduledSubagentRow[]>;
+    /**
+     * Delete every row whose `fire_at` is strictly before `nowUtc`.
+     * Returns the number of rows removed. Used by the host scheduler
+     * at startup to silently drop missed wake-ups (matches missed-cron
+     * behavior).
+     */
+    deletePastDue(nowUtc: string): Promise<number>;
+    /**
+     * Subscribe to {@link SCHEDULED_SUBAGENTS_CHANNEL}. Parses the
+     * NOTIFY payload (`<key>:<op>`) and invokes `handler` with the
+     * parsed shape. Errors thrown by `handler` are logged and
+     * swallowed so one bad subscriber doesn't break others on the
+     * same channel.
+     *
+     * Returns a disposer; calling it unlistens. Idempotent.
+     */
+    listen(handler: (notification: ScheduledSubagentNotification) => void | Promise<void>): Promise<ScheduledSubagentUnsubscribe>;
+    private dispatch;
+}

package/build/ScheduledSubagentBus.js

@@ -0,0 +1,187 @@
+import { SCHEDULED_SUBAGENTS_CHANNEL, SCHEMA_SQL } from "./Schema.js";
+/**
+ * Domain client for the `scheduled_subagents` table — agent-requested
+ * one-off wake-ups. Used by both sides of the bus:
+ *
+ * - Container: the `schedule_subagent` / `unschedule_subagent` /
+ *   `get_scheduled_subagents` tools call {@link upsert} / {@link deleteByKey}
+ *   / {@link listInRange}.
+ * - Host: the `ScheduledSubagentScheduler` calls {@link listFuture} at
+ *   startup, listens via {@link listen} for live changes, and uses
+ *   {@link claimAndDeleteForFiring} to consume a row at fire time.
+ *
+ * All times are stored and returned as UTC ISO-8601 strings; the
+ * caller is responsible for projecting into the user's
+ * `core.timezone` for agent-facing surfaces.
+ */
+export class ScheduledSubagentBus {
+    connection;
+    log;
+    constructor(connection, log) {
+        this.connection = connection;
+        this.log = log;
+    }
+    /**
+     * Apply the bus-state schema (idempotent). Same SQL bundle as
+     * {@link import("./EventBus").EventBus.installSchema}, so calling
+     * any of the three install methods is sufficient on daemon start.
+     */
+    async installSchema() {
+        await this.connection.getPool().query(SCHEMA_SQL);
+    }
+    /**
+     * Insert a scheduled subagent or replace the existing row with the
+     * same `key`. Returns the persisted row.
+     *
+     * Atomic UPSERT semantics: if the agent re-schedules a key, the
+     * old row is overwritten in one statement so the host scheduler
+     * sees exactly one NOTIFY and installs exactly one job.
+     *
+     * @throws If `topic` does not match `\w+(:\w+)*` (CHECK constraint).
+     */
+    async upsert(row) {
+        const result = await this.connection.getPool().query(`INSERT INTO scheduled_subagents
+                (key, fire_at, topic, handler, prompt, payload, priority, privileged)
+             VALUES ($1, $2, $3, $4, $5, $6::jsonb, $7, $8)
+             ON CONFLICT (key) DO UPDATE SET
+                fire_at = EXCLUDED.fire_at,
+                topic = EXCLUDED.topic,
+                handler = EXCLUDED.handler,
+                prompt = EXCLUDED.prompt,
+                payload = EXCLUDED.payload,
+                priority = EXCLUDED.priority,
+                privileged = EXCLUDED.privileged
+             RETURNING *`, [
+            row.key,
+            row.fireAt,
+            row.topic,
+            row.handler,
+            row.prompt ?? null,
+            JSON.stringify(row.payload ?? {}),
+            row.priority ?? 50,
+            row.privileged ?? false,
+        ]);
+        return mapRow(result.rows[0]);
+    }
+    /**
+     * Remove a row by key. Returns `true` when a row was removed,
+     * `false` when no row existed for the key.
+     */
+    async deleteByKey(key) {
+        const result = await this.connection
+            .getPool()
+            .query(`DELETE FROM scheduled_subagents WHERE key = $1`, [key]);
+        return (result.rowCount ?? 0) > 0;
+    }
+    /** Fetch a row by key, or `undefined` when missing. */
+    async getByKey(key) {
+        const result = await this.connection
+            .getPool()
+            .query(`SELECT * FROM scheduled_subagents WHERE key = $1`, [key]);
+        return result.rows.length > 0 ? mapRow(result.rows[0]) : undefined;
+    }
+    /**
+     * Atomic claim-and-delete for the firing path: DELETE the row by
+     * key and return it (or `undefined` if it was already gone — the
+     * agent may have unscheduled the key in the window between the
+     * Croner trigger and this query).
+     */
+    async claimAndDeleteForFiring(key) {
+        const result = await this.connection
+            .getPool()
+            .query(`DELETE FROM scheduled_subagents WHERE key = $1 RETURNING *`, [key]);
+        return result.rows.length > 0 ? mapRow(result.rows[0]) : undefined;
+    }
+    /**
+     * List every row whose `fire_at` falls inside `[fromUtc, toUtc)`,
+     * ordered by `fire_at ASC`. Range is half-open so a `day` query
+     * built from {@link import("./Timezone").dayBoundsInZone} returns
+     * exactly the rows belonging to that day in the caller's zone.
+     */
+    async listInRange(fromUtc, toUtc) {
+        const result = await this.connection.getPool().query(`SELECT * FROM scheduled_subagents
+             WHERE fire_at >= $1 AND fire_at < $2
+             ORDER BY fire_at ASC`, [fromUtc, toUtc]);
+        return result.rows.map(mapRow);
+    }
+    /**
+     * Load every row whose `fire_at` is at or after `nowUtc`. Used by
+     * the host scheduler on daemon startup to re-install Croner jobs
+     * for every still-future scheduled subagent.
+     */
+    async listFuture(nowUtc) {
+        const result = await this.connection.getPool().query(`SELECT * FROM scheduled_subagents
+             WHERE fire_at >= $1
+             ORDER BY fire_at ASC`, [nowUtc]);
+        return result.rows.map(mapRow);
+    }
+    /**
+     * Delete every row whose `fire_at` is strictly before `nowUtc`.
+     * Returns the number of rows removed. Used by the host scheduler
+     * at startup to silently drop missed wake-ups (matches missed-cron
+     * behavior).
+     */
+    async deletePastDue(nowUtc) {
+        const result = await this.connection
+            .getPool()
+            .query(`DELETE FROM scheduled_subagents WHERE fire_at < $1`, [nowUtc]);
+        return result.rowCount ?? 0;
+    }
+    /**
+     * Subscribe to {@link SCHEDULED_SUBAGENTS_CHANNEL}. Parses the
+     * NOTIFY payload (`<key>:<op>`) and invokes `handler` with the
+     * parsed shape. Errors thrown by `handler` are logged and
+     * swallowed so one bad subscriber doesn't break others on the
+     * same channel.
+     *
+     * Returns a disposer; calling it unlistens. Idempotent.
+     */
+    async listen(handler) {
+        const wrapper = (payload) => {
+            this.log?.debug({ channel: SCHEDULED_SUBAGENTS_CHANNEL, payload }, "NOTIFY scheduled_subagents_changed");
+            void this.dispatch(payload, handler);
+        };
+        await this.connection.listen(SCHEDULED_SUBAGENTS_CHANNEL, wrapper);
+        let disposed = false;
+        return async () => {
+            if (disposed) {
+                return;
+            }
+            disposed = true;
+            await this.connection.unlisten(SCHEDULED_SUBAGENTS_CHANNEL, wrapper);
+        };
+    }
+    async dispatch(payload, handler) {
+        const colon = payload.lastIndexOf(":");
+        if (colon < 0) {
+            this.log?.warn({ payload }, "ScheduledSubagentBus: malformed NOTIFY payload (no colon)");
+            return;
+        }
+        const key = payload.slice(0, colon);
+        const op = payload.slice(colon + 1);
+        if (op !== "u" && op !== "d") {
+            this.log?.warn({ payload, op }, "ScheduledSubagentBus: unknown op in NOTIFY payload");
+            return;
+        }
+        try {
+            await handler({ key, op });
+        }
+        catch (err) {
+            this.log?.error({ key, op, err: err instanceof Error ? err.message : String(err) }, "ScheduledSubagentBus listen handler error");
+        }
+    }
+}
+/** Convert a snake_case raw row into the camelCase domain shape. */
+function mapRow(raw) {
+    return {
+        key: raw.key,
+        fireAt: raw.fire_at.toISOString(),
+        topic: raw.topic,
+        handler: raw.handler,
+        prompt: raw.prompt,
+        payload: raw.payload,
+        priority: raw.priority,
+        privileged: raw.privileged,
+        createdAt: raw.created_at,
+    };
+}