@getfamiliar/shared 0.1.2

package/build/testing/MockAgentRunBus.d.ts

@@ -0,0 +1,52 @@
+import type { AgentRunPatch, AgentRunRow, NewAgentRun } from "../AgentRun.js";
+import type { MockBusStore } from "./MockBusStore.js";
+/**
+ * Listener for {@link MockAgentRunBus.subscribe}. Fires synchronously
+ * after every state-affecting write so test code can advance the
+ * Scheduler in lock-step with mutations.
+ */
+export type MockAgentRunBusListener = (row: AgentRunRow) => void;
+/**
+ * In-memory {@link AgentRunBus} replacement for unit tests. Stores
+ * agentruns in a {@link MockBusStore} so it can recompute the parent
+ * event's terminal state when a row settles — the same coupling the
+ * production schema's `EVENT_TERMINAL_UPDATE_SQL` enforces.
+ *
+ * Listeners (subscribed via {@link subscribe}) fire synchronously
+ * after every state-affecting write, replacing postgres NOTIFY for
+ * test purposes.
+ *
+ * The class is intentionally not typed as `implements AgentRunBus`:
+ * the production class carries private postgres fields that block
+ * structural compat. The Scheduler (and any other consumer wanting
+ * test-friendliness) should accept a structural subset of the bus —
+ * e.g. `Pick<AgentRunBus, 'add' | 'update' | …>` — which this class
+ * satisfies by shape.
+ */
+export declare class MockAgentRunBus {
+    private readonly store;
+    private readonly listeners;
+    constructor(store: MockBusStore);
+    /** No-op — kept for shape compatibility with the production bus. */
+    installSchema(): Promise<void>;
+    add(run: NewAgentRun): Promise<AgentRunRow>;
+    update(id: string, patch: AgentRunPatch): Promise<void>;
+    settle(id: string, toState: "done" | "failed", outcome?: {
+        readonly result?: unknown;
+        readonly resultText?: string | null;
+        readonly error?: string | null;
+    }): Promise<void>;
+    getById(id: string): Promise<AgentRunRow | undefined>;
+    listEligible(): Promise<readonly AgentRunRow[]>;
+    areAllStartedChildrenSettled(parentId: string): Promise<boolean>;
+    listSince(since: Date): Promise<AgentRunRow[]>;
+    listByEventId(eventId: string): Promise<readonly AgentRunRow[]>;
+    postpone(id: string, runAfter: Date, errorText: string | null): Promise<void>;
+    /**
+     * Test-only: subscribe to row-change notifications. Replaces
+     * postgres NOTIFY for test code. Returns an unsubscriber.
+     */
+    subscribe(listener: MockAgentRunBusListener): () => void;
+    private fire;
+    private recomputeEventTerminal;
+}

package/build/testing/MockAgentRunBus.js

@@ -0,0 +1,175 @@
+/**
+ * In-memory {@link AgentRunBus} replacement for unit tests. Stores
+ * agentruns in a {@link MockBusStore} so it can recompute the parent
+ * event's terminal state when a row settles — the same coupling the
+ * production schema's `EVENT_TERMINAL_UPDATE_SQL` enforces.
+ *
+ * Listeners (subscribed via {@link subscribe}) fire synchronously
+ * after every state-affecting write, replacing postgres NOTIFY for
+ * test purposes.
+ *
+ * The class is intentionally not typed as `implements AgentRunBus`:
+ * the production class carries private postgres fields that block
+ * structural compat. The Scheduler (and any other consumer wanting
+ * test-friendliness) should accept a structural subset of the bus —
+ * e.g. `Pick<AgentRunBus, 'add' | 'update' | …>` — which this class
+ * satisfies by shape.
+ */
+export class MockAgentRunBus {
+    store;
+    listeners = [];
+    constructor(store) {
+        this.store = store;
+    }
+    /** No-op — kept for shape compatibility with the production bus. */
+    async installSchema() {
+        // intentionally empty
+    }
+    async add(run) {
+        const id = String(this.store.nextAgentrunId++);
+        const now = new Date();
+        const row = {
+            id,
+            eventId: run.eventId,
+            parentAgentrunId: run.parentAgentrunId ?? null,
+            topic: run.topic,
+            handler: run.handler,
+            priority: run.priority ?? 50,
+            state: run.state ?? "pending",
+            prompt: run.prompt ?? null,
+            payload: run.payload ?? {},
+            result: null,
+            resultText: null,
+            error: null,
+            privileged: run.privileged ?? false,
+            calltype: (run.calltype ?? null),
+            retryCount: 0,
+            notBefore: null,
+            model: null,
+            systemPrompt: null,
+            initialMessages: null,
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.store.agentruns.set(id, row);
+        this.fire(row);
+        return row;
+    }
+    async update(id, patch) {
+        const row = this.store.agentruns.get(id);
+        if (!row) {
+            throw new Error(`Agentrun ${id} not found`);
+        }
+        const next = {
+            ...row,
+            state: patch.state ?? row.state,
+            payload: patch.payload === undefined ? row.payload : patch.payload,
+            result: patch.result === undefined ? row.result : patch.result,
+            resultText: patch.resultText === undefined ? row.resultText : patch.resultText,
+            error: patch.error === undefined ? row.error : patch.error,
+            priority: patch.priority ?? row.priority,
+            model: patch.model === undefined ? row.model : patch.model,
+            systemPrompt: patch.systemPrompt === undefined ? row.systemPrompt : patch.systemPrompt,
+            initialMessages: patch.initialMessages === undefined ? row.initialMessages : patch.initialMessages,
+            calltype: patch.calltype === undefined ? row.calltype : patch.calltype,
+            updatedAt: new Date(),
+        };
+        this.store.agentruns.set(id, next);
+        this.fire(next);
+    }
+    async settle(id, toState, outcome = {}) {
+        const row = this.store.agentruns.get(id);
+        if (!row) {
+            throw new Error(`Agentrun ${id} not found`);
+        }
+        const next = {
+            ...row,
+            state: toState,
+            result: outcome.result === undefined ? row.result : outcome.result,
+            resultText: outcome.resultText === undefined ? row.resultText : outcome.resultText,
+            error: outcome.error === undefined ? row.error : outcome.error,
+            updatedAt: new Date(),
+        };
+        this.store.agentruns.set(id, next);
+        // Mirror EVENT_TERMINAL_UPDATE_SQL: the event's terminal state
+        // mirrors the root agentrun's terminal state. Settling a
+        // non-root agentrun is a no-op for the event.
+        this.recomputeEventTerminal(row, toState);
+        this.fire(next);
+    }
+    async getById(id) {
+        return this.store.agentruns.get(id);
+    }
+    async listEligible() {
+        const now = Date.now();
+        return [...this.store.agentruns.values()]
+            .filter((r) => r.state === "pending" && (r.notBefore === null || r.notBefore.getTime() <= now))
+            .sort((a, b) => b.priority - a.priority || Number(a.id) - Number(b.id));
+    }
+    async areAllStartedChildrenSettled(parentId) {
+        for (const row of this.store.agentruns.values()) {
+            if (row.parentAgentrunId === parentId &&
+                row.calltype === "started" &&
+                row.state !== "done" &&
+                row.state !== "failed") {
+                return false;
+            }
+        }
+        return true;
+    }
+    async listSince(since) {
+        return [...this.store.agentruns.values()]
+            .filter((r) => r.updatedAt.getTime() >= since.getTime())
+            .sort((a, b) => a.updatedAt.getTime() - b.updatedAt.getTime() || Number(a.id) - Number(b.id));
+    }
+    async listByEventId(eventId) {
+        return [...this.store.agentruns.values()]
+            .filter((r) => r.eventId === eventId)
+            .sort((a, b) => Number(a.id) - Number(b.id));
+    }
+    async postpone(id, runAfter, errorText) {
+        const row = this.store.agentruns.get(id);
+        if (!row) {
+            throw new Error(`Agentrun ${id} not found`);
+        }
+        const next = {
+            ...row,
+            state: "pending",
+            retryCount: row.retryCount + 1,
+            notBefore: runAfter,
+            error: errorText,
+            updatedAt: new Date(),
+        };
+        this.store.agentruns.set(id, next);
+        this.fire(next);
+    }
+    /**
+     * Test-only: subscribe to row-change notifications. Replaces
+     * postgres NOTIFY for test code. Returns an unsubscriber.
+     */
+    subscribe(listener) {
+        this.listeners.push(listener);
+        return () => {
+            const idx = this.listeners.indexOf(listener);
+            if (idx >= 0) {
+                this.listeners.splice(idx, 1);
+            }
+        };
+    }
+    fire(row) {
+        for (const l of this.listeners) {
+            l(row);
+        }
+    }
+    recomputeEventTerminal(settledRow, settledState) {
+        if (settledRow.parentAgentrunId !== null) {
+            return;
+        }
+        const event = this.store.events.get(settledRow.eventId);
+        if (!event || event.state !== "running") {
+            return;
+        }
+        const next = { ...event, state: settledState, updatedAt: new Date() };
+        this.store.events.set(settledRow.eventId, next);
+    }
+}

package/build/testing/MockBusStore.d.ts

@@ -0,0 +1,22 @@
+import type { AgentRunRow } from "../AgentRun.js";
+import type { EventRow } from "../Event.js";
+/**
+ * Shared in-memory backing store for {@link MockAgentRunBus} and
+ * {@link MockEventBus}. Lets `settle()` on the agentrun bus recompute
+ * the parent event's terminal state — the cross-table coupling the
+ * production schema enforces via {@link EVENT_TERMINAL_UPDATE_SQL} —
+ * without separate processes or a real postgres.
+ *
+ * Construct one store per test and pass it into both bus mocks.
+ * `nextEventId` / `nextAgentrunId` mirror postgres's `bigserial`,
+ * yielding deterministic ids `"1"`, `"2"`, … in the order rows are
+ * inserted.
+ */
+export declare class MockBusStore {
+    readonly events: Map<string, EventRow>;
+    readonly agentruns: Map<string, AgentRunRow>;
+    nextEventId: number;
+    nextAgentrunId: number;
+    /** All agentruns whose parent_agentrun_id matches `parentId`. */
+    childrenOf(parentId: string): AgentRunRow[];
+}

package/build/testing/MockBusStore.js

@@ -0,0 +1,22 @@
+/**
+ * Shared in-memory backing store for {@link MockAgentRunBus} and
+ * {@link MockEventBus}. Lets `settle()` on the agentrun bus recompute
+ * the parent event's terminal state — the cross-table coupling the
+ * production schema enforces via {@link EVENT_TERMINAL_UPDATE_SQL} —
+ * without separate processes or a real postgres.
+ *
+ * Construct one store per test and pass it into both bus mocks.
+ * `nextEventId` / `nextAgentrunId` mirror postgres's `bigserial`,
+ * yielding deterministic ids `"1"`, `"2"`, … in the order rows are
+ * inserted.
+ */
+export class MockBusStore {
+    events = new Map();
+    agentruns = new Map();
+    nextEventId = 1;
+    nextAgentrunId = 1;
+    /** All agentruns whose parent_agentrun_id matches `parentId`. */
+    childrenOf(parentId) {
+        return [...this.agentruns.values()].filter((r) => r.parentAgentrunId === parentId);
+    }
+}

package/build/testing/MockEventBus.d.ts

@@ -0,0 +1,20 @@
+import type { EventPatch, EventRow, NewEvent } from "../Event.js";
+import type { MockBusStore } from "./MockBusStore.js";
+/**
+ * In-memory {@link EventBus} replacement for unit tests. The Scheduler
+ * tests need only a tiny slice of the surface — `getById`, occasional
+ * `update`, and an `add` helper to seed events. Anything beyond that
+ * is not needed yet and intentionally absent.
+ *
+ * Stored in a shared {@link MockBusStore} so `MockAgentRunBus.settle`
+ * can recompute the parent event's terminal state on the same data.
+ */
+export declare class MockEventBus {
+    private readonly store;
+    constructor(store: MockBusStore);
+    /** No-op — kept for shape compatibility with the production bus. */
+    installSchema(): Promise<void>;
+    add(event: NewEvent): Promise<EventRow>;
+    getById(id: string): Promise<EventRow | undefined>;
+    update(id: string, patch: EventPatch): Promise<void>;
+}

package/build/testing/MockEventBus.js

@@ -0,0 +1,57 @@
+/**
+ * In-memory {@link EventBus} replacement for unit tests. The Scheduler
+ * tests need only a tiny slice of the surface — `getById`, occasional
+ * `update`, and an `add` helper to seed events. Anything beyond that
+ * is not needed yet and intentionally absent.
+ *
+ * Stored in a shared {@link MockBusStore} so `MockAgentRunBus.settle`
+ * can recompute the parent event's terminal state on the same data.
+ */
+export class MockEventBus {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    /** No-op — kept for shape compatibility with the production bus. */
+    async installSchema() {
+        // intentionally empty
+    }
+    async add(event) {
+        const id = String(this.store.nextEventId++);
+        const now = new Date();
+        const row = {
+            id,
+            topic: event.topic,
+            priority: event.priority ?? 50,
+            state: "pending",
+            payload: event.payload ?? {},
+            idempotencyKey: event.idempotencyKey ?? null,
+            isChat: event.isChat === true,
+            preferredChatChannelId: event.preferredChatChannelId ?? null,
+            prompt: event.prompt ?? null,
+            startHandler: event.startHandler ?? null,
+            privileged: event.privileged === true,
+            outputChatOnFailure: event.outputChatOnFailure === true,
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.store.events.set(id, row);
+        return row;
+    }
+    async getById(id) {
+        return this.store.events.get(id);
+    }
+    async update(id, patch) {
+        const row = this.store.events.get(id);
+        if (!row) {
+            throw new Error(`Event ${id} not found`);
+        }
+        const next = {
+            ...row,
+            state: patch.state ?? row.state,
+            payload: patch.payload === undefined ? row.payload : patch.payload,
+            updatedAt: new Date(),
+        };
+        this.store.events.set(id, next);
+    }
+}

package/build/testing/MockLogger.d.ts

@@ -0,0 +1,52 @@
+import type { Logger, LogLevel } from "../logging/Logger.js";
+/**
+ * One captured log call. `obj` is whatever the caller passed as the
+ * structured payload (an object or `undefined` for plain-message
+ * variants); `msg` is the rendered message string.
+ */
+export interface MockLogEntry {
+    readonly level: LogLevel;
+    readonly msg: string;
+    readonly obj: object | undefined;
+    /**
+     * Accumulated child-logger bindings. A root logger has no bindings;
+     * a child via `.child({ component: 'x' })` adds `{ component: 'x' }`.
+     */
+    readonly bindings: ReadonlyArray<Record<string, unknown>>;
+}
+/**
+ * In-memory {@link Logger} that records every call into a flat
+ * {@link entries} array, suitable for assertions in unit tests.
+ *
+ * Children share the same backing entries array and accumulate
+ * bindings — so `logger.child({ a: 1 }).child({ b: 2 }).info('hi')`
+ * records `{ bindings: [{a:1}, {b:2}], msg: 'hi', ... }`.
+ *
+ * Lives in `shared/` because every package that depends on
+ * `@getfamiliar/shared` already has the `Logger` interface visible,
+ * and the same mock works for host- and container-side tests.
+ */
+export declare class MockLogger implements Logger {
+    /** Every call observed by this logger (and its children). */
+    readonly entries: MockLogEntry[];
+    private readonly bindings;
+    constructor(bindings?: ReadonlyArray<Record<string, unknown>>);
+    debug(obj: object, msg?: string): void;
+    debug(msg: string): void;
+    info(obj: object, msg?: string): void;
+    info(msg: string): void;
+    warn(obj: object, msg?: string): void;
+    warn(msg: string): void;
+    error(obj: object, msg?: string): void;
+    error(msg: string): void;
+    child(bindings: Record<string, unknown>): Logger;
+    /**
+     * Convenience query: does an entry at `level` with a message
+     * matching `match` exist? `match` is either a substring or a
+     * RegExp.
+     */
+    hasEntry(level: LogLevel, match: string | RegExp): boolean;
+    /** Drop all recorded entries. Useful between assertions. */
+    clear(): void;
+    private record;
+}

package/build/testing/MockLogger.js

@@ -0,0 +1,65 @@
+/**
+ * In-memory {@link Logger} that records every call into a flat
+ * {@link entries} array, suitable for assertions in unit tests.
+ *
+ * Children share the same backing entries array and accumulate
+ * bindings — so `logger.child({ a: 1 }).child({ b: 2 }).info('hi')`
+ * records `{ bindings: [{a:1}, {b:2}], msg: 'hi', ... }`.
+ *
+ * Lives in `shared/` because every package that depends on
+ * `@getfamiliar/shared` already has the `Logger` interface visible,
+ * and the same mock works for host- and container-side tests.
+ */
+export class MockLogger {
+    /** Every call observed by this logger (and its children). */
+    entries = [];
+    bindings;
+    constructor(bindings = []) {
+        this.bindings = bindings;
+    }
+    debug(a, b) {
+        this.record("debug", a, b);
+    }
+    info(a, b) {
+        this.record("info", a, b);
+    }
+    warn(a, b) {
+        this.record("warn", a, b);
+    }
+    error(a, b) {
+        this.record("error", a, b);
+    }
+    child(bindings) {
+        const child = new MockLogger([...this.bindings, bindings]);
+        // Share the entries array so parent observations see child
+        // writes too — matches `pino.child` semantics from the test's
+        // POV.
+        child.entries = this.entries;
+        return child;
+    }
+    /**
+     * Convenience query: does an entry at `level` with a message
+     * matching `match` exist? `match` is either a substring or a
+     * RegExp.
+     */
+    hasEntry(level, match) {
+        return this.entries.some((e) => e.level === level &&
+            (typeof match === "string" ? e.msg.includes(match) : match.test(e.msg)));
+    }
+    /** Drop all recorded entries. Useful between assertions. */
+    clear() {
+        this.entries.length = 0;
+    }
+    record(level, a, b) {
+        if (typeof a === "string") {
+            this.entries.push({ level, msg: a, obj: undefined, bindings: this.bindings });
+            return;
+        }
+        this.entries.push({
+            level,
+            msg: b ?? "",
+            obj: a,
+            bindings: this.bindings,
+        });
+    }
+}

package/build/testing/index.d.ts

@@ -0,0 +1,4 @@
+export { MockAgentRunBus, type MockAgentRunBusListener } from "./MockAgentRunBus.js";
+export { MockBusStore } from "./MockBusStore.js";
+export { MockEventBus } from "./MockEventBus.js";
+export { type MockLogEntry, MockLogger } from "./MockLogger.js";

package/build/testing/index.js

@@ -0,0 +1,4 @@
+export { MockAgentRunBus } from "./MockAgentRunBus.js";
+export { MockBusStore } from "./MockBusStore.js";
+export { MockEventBus } from "./MockEventBus.js";
+export { MockLogger } from "./MockLogger.js";

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@getfamiliar/shared",
+  "type": "module",
+  "version": "0.1.2",
+  "description": "Familiar — shared types and bus-state client between host and container.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "default": "./build/index.js"
+    },
+    "./testing": {
+      "types": "./build/testing/index.d.ts",
+      "default": "./build/testing/index.js"
+    }
+  },
+  "files": [
+    "build"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsc",
+    "format": "biome format --write --config-path .. src/",
+    "format:check": "biome format --config-path .. src/",
+    "lint": "biome lint --config-path .. src/",
+    "check": "biome check --config-path .. src/",
+    "test": "tsx --test 'src/**/*.test.ts'"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "chalk": "^5.4.1",
+    "citty": "^0.1.6",
+    "cli-highlight": "^2.1.11",
+    "cli-table3": "^0.6.5",
+    "croner": "^10.0.1",
+    "friendly-node-cron": "^1.5.0",
+    "luxon": "^3.7.2",
+    "marked": "^15.0.12",
+    "pg": "^8.13.1",
+    "pino": "^9.14.0",
+    "supports-hyperlinks": "^3.2.0",
+    "wrap-ansi": "^9.0.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.12",
+    "@types/luxon": "^3.7.1",
+    "@types/node": "^25.6.0",
+    "@types/pg": "^8.11.10",
+    "typescript": "^6.0.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/getfamiliar/familiar.git",
+    "directory": "shared"
+  }
+}