@getfamiliar/shared 0.1.2

package/build/ChatMessageBus.js

@@ -0,0 +1,257 @@
+import { CHATMESSAGES_NEW_CHANNEL } from "./Schema.js";
+/**
+ * Domain client for the `chatmessages` table.
+ *
+ * Three responsibilities:
+ *
+ * 1. Persistence of assistant replies (`insertAssistantMessage`). User
+ *    messages are persisted by `EventBus.add` directly when the event
+ *    has `isChat=true`, so they don't have a public method here.
+ * 2. History retrieval for the agent (`fetchHistoryForEvent`). Returns
+ *    every message on the same channel as the given event, oldest
+ *    first. The container's `ChatManager` wraps this for the LLM.
+ * 3. At-least-once channel delivery (`subscribe`). New subscribers
+ *    replay all undelivered matching rows on registration; live rows
+ *    arrive via the `chatmessages_new` NOTIFY channel. A handler
+ *    returning `true` marks the row delivered; multiple matching
+ *    listeners is fine — the UPDATE is idempotent.
+ *
+ * The bus has no notion of channel-binding: callers pass `eventId` or
+ * the full filter on each call. Channel routing happens via JOIN to
+ * `events.preferred_chat_channel_id`, NOT a denormalized column on
+ * `chatmessages`.
+ */
+export class ChatMessageBus {
+    connection;
+    log;
+    constructor(connection, log) {
+        this.connection = connection;
+        this.log = log;
+    }
+    /**
+     * Insert one assistant reply. Returns the persisted row. Used by
+     * the container's `send_chat` tool via `ChatManager`.
+     */
+    async insertAssistantMessage(eventId, textContent) {
+        return this.insert({ eventId, role: "assistant", textContent });
+    }
+    /**
+     * Insert a row of any role. The atomic-with-event INSERT path used
+     * by `EventBus.add` for user messages bypasses this method (it
+     * issues the INSERT inside its own transaction); this is provided
+     * for tests and for callers that already hold their own
+     * transaction.
+     */
+    async insert(input) {
+        const result = await this.connection.getPool().query(`INSERT INTO chatmessages (event_id, role, text_content)
+             VALUES ($1, $2, $3)
+             RETURNING *`, [input.eventId, input.role, input.textContent]);
+        return mapRow(result.rows[0]);
+    }
+    /** Fetch one row by id. Returns `undefined` if not found. */
+    async getById(id) {
+        const result = await this.connection
+            .getPool()
+            .query(`SELECT * FROM chatmessages WHERE id = $1`, [id]);
+        return result.rows.length > 0 ? mapRow(result.rows[0]) : undefined;
+    }
+    /**
+     * Return every chat message on the same channel as the given event,
+     * oldest first. The channel is resolved via the join
+     *   `chatmessages.event_id → events.preferred_chat_channel_id`,
+     * which lets the container request "the conversation this agentrun
+     * is part of" without ever naming a channel itself.
+     *
+     * If the parent event has no `preferred_chat_channel_id`, only
+     * messages tied to that exact event are returned (no cross-event
+     * thread to attach to).
+     */
+    async fetchHistoryForEvent(eventId) {
+        const result = await this.connection.getPool().query(`WITH anchor AS (
+               SELECT preferred_chat_channel_id AS channel
+               FROM events WHERE id = $1
+             )
+             SELECT cm.*
+             FROM chatmessages cm
+             JOIN events e ON e.id = cm.event_id
+             CROSS JOIN anchor
+             WHERE (
+               anchor.channel IS NOT NULL
+                 AND e.preferred_chat_channel_id = anchor.channel
+             ) OR (
+               anchor.channel IS NULL
+                 AND cm.event_id = $1
+             )
+             ORDER BY cm.created_at ASC, cm.id ASC`, [eventId]);
+        return result.rows.map(mapRow);
+    }
+    /**
+     * Subscribe to chat messages matching `filter`. Returns an
+     * unsubscribe function.
+     *
+     * Delivery semantics:
+     *
+     * - LISTEN is attached BEFORE the replay SELECT, so any row inserted
+     *   between SELECT and attach won't be missed. NOTIFY-driven
+     *   delivery is still gated by `delivered_at IS NULL`, so the same
+     *   row is never delivered twice via this subscription.
+     * - The replay SELECT returns every undelivered matching row in
+     *   `created_at` order; each is awaited through the handler.
+     * - When the handler returns `true`, the bus runs
+     *   `UPDATE chatmessages SET delivered_at = now() WHERE id = $1
+     *    AND delivered_at IS NULL` — a no-op if a concurrent subscriber
+     *   has already marked it.
+     * - Handler errors are caught and logged so one bad subscriber
+     *   doesn't break others.
+     *
+     * Multiple matching subscribers will each see the row; the first
+     * to return `true` "wins" the delivery write. This is idempotent
+     * and matches the at-least-once contract: handlers must tolerate
+     * being called for an already-displayed message.
+     */
+    async subscribe(filter, handler) {
+        const seenLive = new Set();
+        const dispatch = async (message) => {
+            if (!matchesFilter(message, filter)) {
+                return;
+            }
+            if (message.deliveredAt !== null) {
+                return;
+            }
+            try {
+                const ok = await handler(message);
+                if (ok) {
+                    await this.markDelivered(message.id);
+                }
+            }
+            catch (err) {
+                console.error(`ChatMessageBus subscribe handler error for id=${message.id}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        };
+        const listenHandler = (payload) => {
+            this.log?.debug({ channel: CHATMESSAGES_NEW_CHANNEL, payload }, "NOTIFY chatmessages_new");
+            void this.dispatchNotification(payload, filter, seenLive, dispatch);
+        };
+        await this.connection.listen(CHATMESSAGES_NEW_CHANNEL, listenHandler);
+        try {
+            const undelivered = await this.fetchUndelivered(filter);
+            for (const row of undelivered) {
+                seenLive.add(row.id);
+                await dispatch(row);
+            }
+        }
+        catch (err) {
+            await this.connection.unlisten(CHATMESSAGES_NEW_CHANNEL, listenHandler);
+            throw err;
+        }
+        let disposed = false;
+        return async () => {
+            if (disposed) {
+                return;
+            }
+            disposed = true;
+            await this.connection.unlisten(CHATMESSAGES_NEW_CHANNEL, listenHandler);
+        };
+    }
+    /**
+     * Parse a NOTIFY payload, prefilter on the prefix, fetch the row,
+     * and hand it to the dispatcher. The `seenLive` set deduplicates
+     * against the replay SELECT so a row picked up by both paths is
+     * delivered exactly once per subscription.
+     */
+    async dispatchNotification(payload, filter, seenLive, dispatch) {
+        const parsed = parseNotifyPayload(payload);
+        if (!parsed) {
+            return;
+        }
+        if (filter.channelId !== undefined && parsed.channelId !== filter.channelId) {
+            return;
+        }
+        if (filter.role !== undefined && parsed.role !== filter.role) {
+            return;
+        }
+        if (seenLive.has(parsed.id)) {
+            return;
+        }
+        seenLive.add(parsed.id);
+        try {
+            const row = await this.getById(parsed.id);
+            if (!row) {
+                return;
+            }
+            await dispatch(row);
+        }
+        catch (err) {
+            console.error(`ChatMessageBus notification dispatch error for id=${parsed.id}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * SELECT all undelivered rows that match `filter`, oldest first.
+     * Channel filter joins to `events.preferred_chat_channel_id`.
+     */
+    async fetchUndelivered(filter) {
+        const conditions = ["cm.delivered_at IS NULL"];
+        const values = [];
+        let n = 1;
+        if (filter.channelId !== undefined) {
+            conditions.push(`e.preferred_chat_channel_id = $${n++}`);
+            values.push(filter.channelId);
+        }
+        if (filter.role !== undefined) {
+            conditions.push(`cm.role = $${n++}`);
+            values.push(filter.role);
+        }
+        const sql = `SELECT cm.*
+                     FROM chatmessages cm
+                     JOIN events e ON e.id = cm.event_id
+                     WHERE ${conditions.join(" AND ")}
+                     ORDER BY cm.created_at ASC, cm.id ASC`;
+        const result = await this.connection.getPool().query(sql, values);
+        return result.rows.map(mapRow);
+    }
+    /** Conditional UPDATE to set delivered_at; no-op if already set. */
+    async markDelivered(id) {
+        await this.connection.getPool().query(`UPDATE chatmessages SET delivered_at = now()
+                 WHERE id = $1 AND delivered_at IS NULL`, [id]);
+    }
+}
+/** Convert a snake_case raw row into the camelCase {@link ChatMessage}. */
+function mapRow(raw) {
+    return {
+        id: raw.id,
+        eventId: raw.event_id,
+        role: raw.role,
+        textContent: raw.text_content,
+        createdAt: raw.created_at,
+        deliveredAt: raw.delivered_at,
+    };
+}
+/**
+ * Parse the `<channel_id>:<role>:<id>` NOTIFY payload. Returns
+ * `undefined` if the shape is unexpected. The channel id may be empty
+ * (when the parent event had no `preferred_chat_channel_id`); we keep
+ * it as the empty string in that case.
+ */
+function parseNotifyPayload(payload) {
+    const firstColon = payload.indexOf(":");
+    if (firstColon < 0) {
+        return undefined;
+    }
+    const lastColon = payload.lastIndexOf(":");
+    if (lastColon === firstColon) {
+        return undefined;
+    }
+    const channelId = payload.slice(0, firstColon);
+    const role = payload.slice(firstColon + 1, lastColon);
+    const id = payload.slice(lastColon + 1);
+    if (role !== "user" && role !== "assistant") {
+        return undefined;
+    }
+    return { channelId, role, id };
+}
+function matchesFilter(message, filter) {
+    if (filter.role !== undefined && message.role !== filter.role) {
+        return false;
+    }
+    return true;
+}

package/build/Config.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Plugin-agnostic configuration surface exposed by the host.
+ *
+ * Plugins reach configuration through `HostContext.config` rather than
+ * touching `process.env` or reading the YAML file themselves. The
+ * service intentionally has no plugin-specific types; everything is
+ * keyed by dotted path strings (e.g. `"core.postgresPassword"`,
+ * `"telegram.botToken"`) and validated to a primitive shape at the
+ * call site.
+ *
+ * Required-vs-optional semantics live in the call signature, not in
+ * the schema: omitting `defaultValue` makes the read throw on missing
+ * or wrong-shaped data, while supplying one widens the return type to
+ * include the default (so plugins can pass `null` for fields they
+ * tolerate being absent).
+ *
+ * The platform-level minimum (the keys without which the daemon can't
+ * start) is enforced by a separate `ConfigLinter` on the host side at
+ * boot. Plugin-side keys are not policed by the platform — plugins own
+ * the validation of their own subtrees.
+ */
+export interface ConfigService {
+    /**
+     * Read a string under a dotted path. Throws when the key is
+     * missing, the resolved value is not a string, or the string is
+     * empty.
+     */
+    getString(key: string): string;
+    /**
+     * String read with an opt-out default. The return type widens to
+     * `string | T` so callers can pass `null` for optional fields and
+     * branch on absence without losing type safety.
+     */
+    getString<T>(key: string, defaultValue: T): string | T;
+    /** Number read; same throw-on-missing semantics as {@link getString}. */
+    getNumber(key: string): number;
+    /** Number read with default; same widening semantics as {@link getString}. */
+    getNumber<T>(key: string, defaultValue: T): number | T;
+    /**
+     * Boolean read. Throws when the key is missing or the resolved
+     * value is not a boolean. YAML's native `true` / `false` parse to
+     * booleans, so a stanza like `inference.captureModelHttpRequestBodies: true` reads
+     * back as `true` here.
+     */
+    getBool(key: string): boolean;
+    /** Boolean read with default; widening as above. */
+    getBool<T>(key: string, defaultValue: T): boolean | T;
+    /**
+     * Array read. Element types are not validated — the caller checks
+     * shape if it cares (e.g. `.filter((x): x is string => typeof x === "string")`).
+     * Throws when the key is missing or the resolved value is not an
+     * array.
+     */
+    getArray(key: string): readonly unknown[];
+    /** Array read with default; widening as above. */
+    getArray<T>(key: string, defaultValue: T): readonly unknown[] | T;
+    /**
+     * Read a "string or list of strings" config value as a normalized
+     * `string[]`. A bare string becomes a one-element list; an array is
+     * filtered down to its non-empty string members; anything else (or
+     * a missing key) falls back to `defaultValue`. Lets the operator
+     * write either `key: foo/**` or `key: ["foo/**", "bar/*"]` and have
+     * both read back the same way.
+     *
+     * Distinct from {@link getArray}, which returns the default (losing
+     * the value) when the config holds a bare string rather than an
+     * array.
+     */
+    getStringList(key: string, defaultValue: readonly string[]): readonly string[];
+    /**
+     * Set a single dotted-path key and persist atomically (write
+     * temp + rename). Creates intermediate maps as needed.
+     *
+     * `value` may be any YAML-serializable primitive, array, or plain
+     * object. The implementation re-reads from disk before patching
+     * so concurrent writes from another process don't get clobbered
+     * silently.
+     *
+     * @throws If the value cannot be serialized as YAML, or if the
+     *   atomic write fails.
+     */
+    set(key: string, value: unknown): Promise<void>;
+}

package/build/Config.js

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

package/build/ContainerTool.d.ts

@@ -0,0 +1,34 @@
+import type { ToolLevel } from "./ToolLevel.js";
+/**
+ * Metadata for one container-side built-in tool (`send_chat`, `fs_*`,
+ * `bash`, …), as the agent container reports it to the host on startup.
+ *
+ * Container built-ins are constructed per-agentrun *inside* the
+ * container and never pass through any host-side registry, so the host
+ * cannot read them directly. Instead the container enumerates them once
+ * at startup (`ToolsFactory.catalog()`) and POSTs this projection to the
+ * bastion's `/container-tools/` endpoint; the host keeps the latest
+ * report in an in-memory registry that the `tools list` CLI reads. This
+ * is the single source of truth — there is no hand-maintained host-side
+ * copy to drift out of sync.
+ */
+export interface ContainerToolInfo {
+    /** Agent-facing tool name / registration key (e.g. `fs_read`). */
+    readonly name: string;
+    /** Human-readable description, verbatim from the tool's builder. */
+    readonly description: string;
+    /** Raw JSON Schema for the tool's arguments. */
+    readonly inputSchema: object;
+    /**
+     * Curated groups this built-in joins (mirrors
+     * `CONTAINER_TOOL_GROUPS` in the container), e.g. `["core", "fs"]`
+     * for `fs_read` or `["bash"]` for `bash`.
+     */
+    readonly groups: readonly string[];
+    /**
+     * Security classification (mirrors `CONTAINER_TOOL_LEVELS` in the
+     * container). See {@link ToolLevel}; `default` unless the built-in
+     * is listed there.
+     */
+    readonly level: ToolLevel;
+}

package/build/ContainerTool.js

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

package/build/CronExpression.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Result of {@link parseCron} when the input was accepted by either
+ * the friendly-node-cron grammar or by Croner directly.
+ */
+export interface ParsedCron {
+    /** Verbatim string from the handler's frontmatter. */
+    readonly verbatim: string;
+    /** Cron expression Croner runs (friendly output, or the verbatim). */
+    readonly expression: string;
+    /** Which path accepted the input. */
+    readonly source: "friendly" | "raw";
+}
+/**
+ * Parse a cron expression. friendly-node-cron is tried first because
+ * its grammar (`every monday at 8 am`) is a strict superset of cron in
+ * the directions we care about: it never silently mis-parses a cron
+ * expression. When friendly returns `null` (no human-pattern match) we
+ * validate the verbatim against Croner.
+ *
+ * The verbatim string is first run through {@link normalizeFriendly}
+ * to insert an implicit "at" between a day token (`every day`, `every
+ * monday`, `every weekday`, …) and a leading time digit. Without that
+ * rewrite, friendly-node-cron either returns null for inputs like
+ * `every day 4:00am` *or* — worse — silently mis-parses `every monday
+ * 4:00am` to midnight (`0 0 0 * * 1`) because it accepts the day token
+ * but doesn't see the hour. Idempotent: applying the rewrite to an
+ * already-well-formed expression is a no-op.
+ *
+ * Lives in `shared/` so both the host's `CronjobScheduler` (handler-
+ * frontmatter cron) and plugin pollers (e.g. ms365's calendar refresh
+ * cron) reach the same parsing contract.
+ *
+ * @returns `null` when neither path produces a runnable schedule.
+ */
+export declare function parseCron(verbatim: string): ParsedCron | null;
+/**
+ * Insert a missing `at` between a day token and a leading digit so
+ * friendly-node-cron sees a shape it understands.
+ *
+ * The rewrite triggers on:
+ *
+ * - `everyday <digit>` → `everyday at <digit>`
+ * - `every <word> <digit>` → `every <word> at <digit>` (catches
+ *   `every day 4:00am`, `every monday 4:00am`, `every weekday 4:00am`,
+ *   `every weekend 4:00am`, etc.)
+ *
+ * `every 5 minutes` and `every 2 hours` are unaffected because the
+ * token after `every` consumes the digit so the trailing `\d` check
+ * doesn't match.
+ *
+ * Exported for unit tests; not in the public index.
+ */
+export declare function normalizeFriendly(input: string): string;

package/build/CronExpression.js

@@ -0,0 +1,77 @@
+import { Cron } from "croner";
+import friendly from "friendly-node-cron";
+/**
+ * Parse a cron expression. friendly-node-cron is tried first because
+ * its grammar (`every monday at 8 am`) is a strict superset of cron in
+ * the directions we care about: it never silently mis-parses a cron
+ * expression. When friendly returns `null` (no human-pattern match) we
+ * validate the verbatim against Croner.
+ *
+ * The verbatim string is first run through {@link normalizeFriendly}
+ * to insert an implicit "at" between a day token (`every day`, `every
+ * monday`, `every weekday`, …) and a leading time digit. Without that
+ * rewrite, friendly-node-cron either returns null for inputs like
+ * `every day 4:00am` *or* — worse — silently mis-parses `every monday
+ * 4:00am` to midnight (`0 0 0 * * 1`) because it accepts the day token
+ * but doesn't see the hour. Idempotent: applying the rewrite to an
+ * already-well-formed expression is a no-op.
+ *
+ * Lives in `shared/` so both the host's `CronjobScheduler` (handler-
+ * frontmatter cron) and plugin pollers (e.g. ms365's calendar refresh
+ * cron) reach the same parsing contract.
+ *
+ * @returns `null` when neither path produces a runnable schedule.
+ */
+export function parseCron(verbatim) {
+    const friendlyResult = tryFriendly(verbatim);
+    if (friendlyResult !== null) {
+        if (isValidExpression(friendlyResult)) {
+            return { verbatim, expression: friendlyResult, source: "friendly" };
+        }
+    }
+    if (isValidExpression(verbatim)) {
+        return { verbatim, expression: verbatim, source: "raw" };
+    }
+    return null;
+}
+function tryFriendly(verbatim) {
+    const normalized = normalizeFriendly(verbatim);
+    try {
+        const out = friendly(normalized);
+        return typeof out === "string" && out.length > 0 ? out : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Insert a missing `at` between a day token and a leading digit so
+ * friendly-node-cron sees a shape it understands.
+ *
+ * The rewrite triggers on:
+ *
+ * - `everyday <digit>` → `everyday at <digit>`
+ * - `every <word> <digit>` → `every <word> at <digit>` (catches
+ *   `every day 4:00am`, `every monday 4:00am`, `every weekday 4:00am`,
+ *   `every weekend 4:00am`, etc.)
+ *
+ * `every 5 minutes` and `every 2 hours` are unaffected because the
+ * token after `every` consumes the digit so the trailing `\d` check
+ * doesn't match.
+ *
+ * Exported for unit tests; not in the public index.
+ */
+export function normalizeFriendly(input) {
+    return input.replace(/^(\s*(?:everyday|every\s+\w+))\s+(\d)/i, "$1 at $2");
+}
+/** True iff Croner can construct a (paused) schedule from `expression`. */
+function isValidExpression(expression) {
+    try {
+        const job = new Cron(expression, { paused: true }, () => { });
+        job.stop();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}