@getfamiliar/shared 0.1.2

package/build/AgentRun.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Lifecycle states for an `agentruns` row.
+ *
+ * Each agentrun is a single agent invocation that responds to (or
+ * descends from) an `events` row. Transitions:
+ *
+ * - `pending`: ready to be picked by the {@link AgentrunScheduler}.
+ *   Either fresh (no in-memory runner) or a paused runner that has
+ *   been re-pended after its `start_subagent` children all settled.
+ * - `running`: actively executing JS / making model calls. The
+ *   Scheduler holds an in-memory entry for this row.
+ * - `waiting`: parked inside a `start_subagent` tool callback. The
+ *   in-memory runner is still alive but its `agent.generate()` is
+ *   awaiting the subagent. Moves back to `pending` once every
+ *   `calltype='started'` child of this row has settled.
+ * - `done` / `failed`: terminal. Set by {@link AgentRunBus.settle},
+ *   which also recomputes the parent event's terminal state in the
+ *   same transaction.
+ */
+export type AgentRunState = "pending" | "running" | "waiting" | "done" | "failed";
+/**
+ * How a child agentrun was spawned. `null` for root agentruns (those
+ * created by the input-event watcher in response to an event). See
+ * the matching SQL CHECK in `Schema.ts`.
+ */
+export type AgentRunCallType = "scheduled" | "started";
+/**
+ * Shape of a row in the `agentruns` table after JSON-decoding from
+ * postgres. `id`, `eventId`, and `parentAgentrunId` are kept as strings
+ * because postgres `bigint` exceeds JavaScript's safe integer range.
+ */
+export interface AgentRunRow {
+    /** Database primary key (bigint as string). */
+    readonly id: string;
+    /** FK to {@link EventRow.id} — the root event this tree responds to. */
+    readonly eventId: string;
+    /**
+     * FK to another {@link AgentRunRow.id}, or `null` for the root
+     * agentrun of an event. Forms the response tree.
+     */
+    readonly parentAgentrunId: string | null;
+    /**
+     * Topic copied from the originating event at queue time. Combined
+     * with {@link handler} to resolve a workspace markdown file.
+     */
+    readonly topic: string;
+    /**
+     * Basename of the handler file in the workspace (e.g. `index`,
+     * `analyze`). Resolution rules — for topic `chat:whatsapp` and
+     * handler `analyze`:
+     *   1. `workspace/chat/whatsapp/analyze.md`
+     *   2. fallback `workspace/chat/analyze.md`
+     */
+    readonly handler: string;
+    /**
+     * Resolved model id actually used for this run, of the form
+     * `<provider>/<modelId>` (e.g. `featherless/zai-org/GLM-5.1`).
+     * Distinct from the handler's *declared* model in markdown:
+     * carries the resolved provider prefix even when the handler
+     * left it bare. `null` for any agentrun that never reached the
+     * `agent.generate()` call (handler-load failures, etc.).
+     * Stamped by AgentRunner immediately after model resolution and
+     * never mutated afterwards.
+     */
+    readonly model: string | null;
+    /**
+     * Higher = processed first within a queue. Inherited from the
+     * originating event at spawn; constant per row for now.
+     */
+    readonly priority: number;
+    /** Lifecycle state — see {@link AgentRunState}. */
+    readonly state: AgentRunState;
+    /** Optional prompt seed supplied by the queueing caller. */
+    readonly prompt: string | null;
+    /**
+     * Resolved system prompt the agent ran under (SOUL.md +
+     * CONTEXT.md + handler body + tool list). Populated by
+     * AgentRunner only when `core.logSystemPrompt` is enabled;
+     * otherwise `null`. Read by the report layer's
+     * `renderAgentrunStart` when `withDetails` is on.
+     */
+    readonly systemPrompt: string | null;
+    /**
+     * Verbatim model-message array assembled for the first
+     * `agent.generate()` call (prior history plus the run's leading
+     * user turn). Populated by AgentRunner only when
+     * `inference.captureInitialMessageHistory` is enabled; otherwise
+     * `null`. Surfaced by the report layer's `-vv` view. Kept `unknown`
+     * (like {@link payload}) rather than coupled to the SDK
+     * `ModelMessage` type.
+     */
+    readonly initialMessages: unknown;
+    /** Spawn-time inputs from the calling agent (or the root event). */
+    readonly payload: unknown;
+    /** Structured terminal output (arbitrary JSON) when the run reaches `done` / `failed`. */
+    readonly result: unknown;
+    /**
+     * The agent's final text output. Populated by the agentrun watcher
+     * on success. Distinct from {@link result} so callers (notably
+     * `HostContext.events.emit`'s await-and-return path) have a
+     * typed, dedicated text channel without rummaging in JSON.
+     */
+    readonly resultText: string | null;
+    /** Error message when state is `failed`. */
+    readonly error: string | null;
+    /**
+     * Inherited from the originating event (root agentrun) or the parent
+     * agentrun (children spawned via `schedule_subagent` / `start_subagent`).
+     * `true` when the run descends from a trusted user-input source;
+     * `false` otherwise. Tools that gate risky behavior on the call
+     * site's trust level read this flag rather than rummaging through
+     * the event payload.
+     */
+    readonly privileged: boolean;
+    /**
+     * How this agentrun was spawned. `null` for root agentruns;
+     * `'scheduled'` for children spawned by `schedule_subagent` without a
+     * future `when` (fire-and-forget immediate dispatch); `'started'`
+     * for children of `start_subagent` (parent parks in `waiting` until
+     * this row settles).
+     */
+    readonly calltype: AgentRunCallType | null;
+    /**
+     * Number of retry attempts already made. Bumped each time
+     * `AgentRunner` postpones the row due to a retryable inference
+     * error. Compared against the per-handler `maxRetries` cap on
+     * each subsequent attempt; once `retry_count >= cap` the run
+     * settles `failed` instead of being postponed again.
+     */
+    readonly retryCount: number;
+    /**
+     * Earliest moment the agentrun watcher is allowed to re-claim
+     * this row. `null` means "claim immediately" (default for fresh
+     * inserts). A future timestamp parks the row so other agentruns
+     * — potentially using different models — can use the watcher
+     * slot in the meantime.
+     */
+    readonly notBefore: Date | null;
+    /** Insert timestamp — postgres `now()` at INSERT. */
+    readonly createdAt: Date;
+    /** Last update timestamp — bumped to `now()` on every update. */
+    readonly updatedAt: Date;
+}
+/** Input shape for {@link AgentRunBus.add}. */
+export interface NewAgentRun {
+    /** FK to the root event. Required. */
+    readonly eventId: string;
+    /** FK to the parent agentrun, or omitted/null for the root agentrun. */
+    readonly parentAgentrunId?: string | null;
+    /** Topic copied from the event. Required. */
+    readonly topic: string;
+    /** Handler basename (e.g. `index`). Required. */
+    readonly handler: string;
+    /** Defaults to 50; usually inherited from the event. */
+    readonly priority?: number;
+    /** Initial state; default `"pending"`. */
+    readonly state?: AgentRunState;
+    /** Optional prompt seed. */
+    readonly prompt?: string | null;
+    /** Optional spawn-time payload. */
+    readonly payload?: unknown;
+    /**
+     * Trust flag. Default `false` — the SQL column default covers
+     * omission. Callers usually copy the value from the originating
+     * event (root agentrun) or parent agentrun (children).
+     */
+    readonly privileged?: boolean;
+    /**
+     * How this agentrun was spawned. Omitted / `null` for root rows
+     * inserted by the input-event watcher. Set to `'scheduled'` or
+     * `'started'` by the tool that spawned the child.
+     */
+    readonly calltype?: AgentRunCallType | null;
+}
+/** Patch shape for {@link AgentRunBus.update}. */
+export interface AgentRunPatch {
+    readonly state?: AgentRunState;
+    readonly payload?: unknown;
+    readonly result?: unknown;
+    readonly resultText?: string | null;
+    readonly error?: string | null;
+    readonly priority?: number;
+    readonly model?: string | null;
+    readonly systemPrompt?: string | null;
+    readonly initialMessages?: unknown;
+    readonly calltype?: AgentRunCallType | null;
+}

package/build/AgentRun.js

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

package/build/AgentRunBus.d.ts

@@ -0,0 +1,147 @@
+import type { AgentRunPatch, AgentRunRow, NewAgentRun } from "./AgentRun.js";
+import type { Logger } from "./logging/Logger.js";
+import type { PostgresConnection } from "./PostgresConnection.js";
+/**
+ * Disposer returned by {@link AgentRunBus.listen}. Calling it
+ * unsubscribes the handler from the underlying NOTIFY channel.
+ * Idempotent: calling more than once is safe.
+ */
+export type AgentRunUnsubscribe = () => Promise<void>;
+/**
+ * Domain client for the `agentruns` table — the assistant's response
+ * tree. Each row is one agent invocation that responds to (or descends
+ * from) an `events` row.
+ *
+ * Uses an injected {@link PostgresConnection} for pool + LISTEN access;
+ * does not own connection lifecycle.
+ *
+ * The bus is purely a CRUD surface — no claim queue, no in-process
+ * blocking primitive. The {@link import("@getfamiliar/container").AgentrunScheduler}
+ * is the sole authority on which row runs next and is guaranteed
+ * singleton inside the container, so a postgres-side claim queue
+ * (`FOR UPDATE SKIP LOCKED`) would be overkill. The Scheduler reads
+ * eligible pending rows via {@link listEligible} and writes lifecycle
+ * transitions via {@link update} / {@link settle} / {@link postpone}.
+ *
+ * The terminal write goes through {@link settle}, which transitions the
+ * agentrun to `done` / `failed` *and* recomputes the parent event's
+ * terminal state in the same transaction. That keeps the event
+ * terminal logic invariant-free — no counter to corrupt — at the cost
+ * of one extra query per terminal write.
+ */
+export declare class AgentRunBus {
+    private readonly connection;
+    private readonly log;
+    constructor(connection: PostgresConnection, log?: Logger);
+    /**
+     * Apply the events + agentruns schema (idempotent). The same SQL
+     * bundle is consumed by {@link EventBus.installSchema}, so calling
+     * either is sufficient on daemon start.
+     */
+    installSchema(): Promise<void>;
+    /**
+     * Insert a new agentrun and return the persisted row.
+     *
+     * @throws If the underlying FK / check constraints reject the row
+     *   (unknown `eventId`, malformed `topic`, invalid `calltype`).
+     */
+    add(run: NewAgentRun): Promise<AgentRunRow>;
+    /**
+     * Patch one or more fields on an existing agentrun by id. Always
+     * bumps `updated_at`. **Do not** use this to write a terminal state
+     * — use {@link settle} instead so the parent event's terminal state
+     * is recomputed in the same transaction.
+     */
+    update(id: string, patch: AgentRunPatch): Promise<void>;
+    /**
+     * Terminal write for an agentrun. Transitions the row to `done` or
+     * `failed`, optionally recording `result` / `resultText` / `error`,
+     * and recomputes the parent event's terminal state in the **same
+     * transaction**.
+     *
+     * The reactive event update is intentionally not a counter: it
+     * relies on the `agentruns(event_id)` index to check whether any
+     * sibling agentruns are still pending or running.
+     */
+    settle(id: string, toState: "done" | "failed", outcome?: {
+        readonly result?: unknown;
+        readonly resultText?: string | null;
+        readonly error?: string | null;
+    }): Promise<void>;
+    /**
+     * Fetch one agentrun by id, or `undefined` when missing.
+     */
+    getById(id: string): Promise<AgentRunRow | undefined>;
+    /**
+     * Fetch every agentrun in `state='pending'` whose `not_before` window
+     * has opened, in dispatch order (`priority desc, id asc`). The
+     * {@link AgentrunScheduler} calls this once per scheduling pass.
+     *
+     * Returns an empty array when nothing is ready. The Scheduler then
+     * waits on its NOTIFY subscription or a parked `not_before` timer
+     * before re-checking.
+     */
+    listEligible(): Promise<readonly AgentRunRow[]>;
+    /**
+     * `true` when every `calltype='started'` child of `parentId` is in
+     * a terminal state (`done` / `failed`). Used by the Scheduler
+     * after a started child settles, to decide whether the parent can
+     * leave `waiting` and go back to `pending`.
+     *
+     * Returns `true` when there are no started children at all (the
+     * trivially-vacuous case); the Scheduler still owns the "should
+     * we actually re-pend this parent?" decision and only invokes
+     * this method when at least one started child has just settled.
+     */
+    areAllStartedChildrenSettled(parentId: string): Promise<boolean>;
+    /**
+     * Fetch all agentrun rows whose `updated_at` is `>= since`, ordered
+     * by `(updated_at, id)`. Used by the polling-based report layer to
+     * pick up new agentruns and state transitions without NOTIFY.
+     */
+    listSince(since: Date): Promise<AgentRunRow[]>;
+    /**
+     * Fetch all agentruns belonging to one event, ordered by id.
+     * Used by the report layer to aggregate token totals and runtime
+     * across an event's full agentrun tree at finalization time.
+     */
+    listByEventId(eventId: string): Promise<readonly AgentRunRow[]>;
+    /**
+     * Postpone an agentrun after a retryable inference error.
+     * Returns the row to `pending`, bumps `retry_count`, sets
+     * `not_before` to the supplied timestamp, and records the latest
+     * attempt's error text. The existing `agentruns_changed` UPDATE
+     * trigger fires on the state write so a NOTIFY-subscribed
+     * Scheduler wakes up — it just won't include the row in
+     * {@link listEligible} until `not_before` passes.
+     *
+     * Throws if the row is missing (mirrors {@link settle}).
+     */
+    postpone(id: string, runAfter: Date, errorText: string | null): Promise<void>;
+    /**
+     * Subscribe to {@link AGENTRUNS_CHANNEL}. The notification payload
+     * (`<event_id>:<id>`) is parsed, the row is fetched by id, and
+     * `handler` is invoked with it. Fires on both INSERT and state
+     * UPDATE — callers that only care about one transition must filter
+     * on `row.state` themselves.
+     *
+     * Errors thrown by `handler` are caught and logged so one bad
+     * subscriber doesn't break others on the same channel.
+     *
+     * Returns a disposer; call it to unlisten. Idempotent.
+     *
+     * The {@link AgentrunScheduler} subscribes via
+     * {@link PostgresConnection.listen} directly (it only needs a
+     * "something changed" wake hint, not full row fetches); this
+     * helper exists for host-side consumers like
+     * `HostContext.events.emit`'s `onAgentRun` callback.
+     */
+    listen(handler: (row: AgentRunRow) => void | Promise<void>): Promise<AgentRunUnsubscribe>;
+    /**
+     * Inner notification dispatcher for {@link listen}. Parses the
+     * channel payload (`<event_id>:<id>`), fetches the row by id, and
+     * invokes the handler — catching and logging any error from the
+     * handler itself.
+     */
+    private dispatchNotification;
+}