@retinue/agentkit 0.1.0

package/dist/adapters/postgres/usage-limits.js

@@ -0,0 +1,136 @@
+/**
+ * PostgreSQL `UsageLimitStore` — admin-configured spend limits (#175).
+ *
+ * `principal_id IS NULL` is the tenant default; a non-null row overrides it for one person. One table rather than
+ * two, because "the default" and "an override" are the same kind of fact — and resolution is then a single query
+ * ordered by specificity rather than two queries and a merge in application code.
+ *
+ * Every limit column is nullable and NULL means **unbounded**, not zero. That direction matches `QuotaLimits` and
+ * is the whole reason it is stated twice: a misconfigured quota that blocks everything is an outage, and one that
+ * blocks nothing is a bill the rollups make visible. An outage is only visible to the customer it happens to.
+ */
+import { parseWindowKey, windowKey } from "../../persistence/index.js";
+const iso = (v) => (v instanceof Date ? v.toISOString() : new Date(v).toISOString());
+const num = (v) => (v === null ? undefined : Number(v));
+const toLimit = (r) => ({
+    tenantId: r.tenant_id,
+    ...(r.principal_id === null ? {} : { principalId: r.principal_id }),
+    ...(r.model_id === null ? {} : { modelId: r.model_id }),
+    /**
+      * A row whose key this version cannot parse is **not** silently treated as some default window — it throws,
+      * naming the value. The alternative is enforcing an allowance over a span nobody configured, in whichever
+      * direction the fallback happened to point.
+      */
+    window: (() => {
+        const parsed = parseWindowKey(r.window_key);
+        if (parsed === null)
+            throw new Error(`usage_limits row has an unrecognised window key ${JSON.stringify(r.window_key)}`);
+        return parsed;
+    })(),
+    // Spread conditionally rather than assigning `undefined`, so an absent limit is absent from the object and
+    // `"costMinorUnits" in limit` answers "is this bounded" without a second convention.
+    ...(num(r.cost_minor_units) === undefined ? {} : { costMinorUnits: num(r.cost_minor_units) }),
+    ...(num(r.input_tokens) === undefined ? {} : { inputTokens: num(r.input_tokens) }),
+    ...(num(r.output_tokens) === undefined ? {} : { outputTokens: num(r.output_tokens) }),
+    ...(r.warn_at === null ? {} : { warnAt: r.warn_at }),
+    updatedAt: iso(r.updated_at),
+    ...(r.updated_by === null ? {} : { updatedBy: r.updated_by }),
+});
+const COLUMNS = `tenant_id, principal_id, model_id, window_key, cost_minor_units, input_tokens,
+                 output_tokens, warn_at, updated_at, updated_by`;
+export const createPostgresUsageLimitStore = (sql) => ({
+    async put({ tenantId, limit }) {
+        /**
+          * One statement, one conflict target — #182.
+          *
+          * This branched on grain, because uniqueness was two *partial* unique indexes (a NULL cannot participate in
+          * a normal unique constraint) and `ON CONFLICT` has to name the matching one. Adding the model dimension
+          * would have made that four indexes and a 2x2 branch — four chances to name the wrong one, and naming the
+          * wrong one is how #177's `error: dup` reached a user.
+          *
+          * Migration 0025 replaced them with a single expression index over `COALESCE(col, '')`, so both nullable
+          * dimensions normalise into one key. The `::text` casts are load-bearing: the target has to match the
+          * index's expression exactly, or Postgres cannot find it and the upsert fails at runtime.
+          */
+        const rows = await sql.query(`INSERT INTO usage_limits
+         (tenant_id, principal_id, model_id, window_key, cost_minor_units, input_tokens, output_tokens, warn_at,
+          updated_at, updated_by)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, now(), $9)
+       ON CONFLICT (tenant_id, COALESCE(principal_id, ''::text), COALESCE(model_id, ''::text), window_key)
+       DO UPDATE SET
+         cost_minor_units = EXCLUDED.cost_minor_units,
+         input_tokens = EXCLUDED.input_tokens,
+         output_tokens = EXCLUDED.output_tokens,
+         warn_at = EXCLUDED.warn_at,
+         updated_at = EXCLUDED.updated_at,
+         updated_by = EXCLUDED.updated_by
+       RETURNING ${COLUMNS}`, [
+            tenantId,
+            limit.principalId ?? null,
+            limit.modelId ?? null,
+            windowKey(limit.window),
+            // `?? null` and not `?? 0`: an omitted limit is unbounded. Writing 0 would refuse every run, which is
+            // the outage direction.
+            limit.costMinorUnits ?? null,
+            limit.inputTokens ?? null,
+            limit.outputTokens ?? null,
+            limit.warnAt ?? null,
+            limit.updatedBy ?? null,
+        ]);
+        return toLimit(rows[0]);
+    },
+    async resolve({ tenantId, principalId, modelId, window }) {
+        /**
+         * Most specific wins, decided by the database rather than by the caller.
+         *
+         * `ORDER BY principal_id NULLS LAST` puts the principal's own row first when it exists and falls back to the
+         * tenant default otherwise. One query, one round trip, and — the actual point — one implementation: "most
+         * specific wins" is a rule, and a rule implemented at two call sites is a rule with two behaviours.
+         */
+        const rows = await sql.query(`SELECT ${COLUMNS} FROM usage_limits
+        WHERE tenant_id = $1 AND window_key = $2
+          AND (principal_id IS NULL OR principal_id = $3::text)
+          -- IS NOT DISTINCT FROM, so asking for the unscoped limit finds the unscoped row, not nothing.
+          AND model_id IS NOT DISTINCT FROM $4::text
+        ORDER BY principal_id NULLS LAST
+        LIMIT 1`, [tenantId, windowKey(window), principalId ?? null, modelId ?? null]);
+        return rows[0] === undefined ? null : toLimit(rows[0]);
+    },
+    async applicable({ tenantId, principalId, modelId }) {
+        /**
+         * Every limit in force, one per `(window, model)` scope — #182.
+         *
+         * `DISTINCT ON` with the scope as its key and `principal_id NULLS LAST` in the ordering is the whole rule:
+         * for each scope Postgres keeps the first row, and the ordering puts the principal's own row first when it
+         * exists. Override within a scope, coexist across scopes, in one query rather than a read-then-choose that
+         * could see a limit change between the two halves.
+         *
+         * `model_id IS NULL OR model_id = $3` and *not* `IS NOT DISTINCT FROM`: an unscoped row applies to every
+         * model, so it must come back whatever the current model is. A model-scoped row applies only to its own
+         * model, and when `$3` is NULL that comparison is never true — which is the intended answer, because an
+         * unknown model cannot be checked against a per-model allowance.
+         */
+        const rows = await sql.query(`SELECT DISTINCT ON (COALESCE(model_id, ''), window_key) ${COLUMNS}
+         FROM usage_limits
+        WHERE tenant_id = $1
+          AND (principal_id IS NULL OR principal_id = $2::text)
+          AND (model_id IS NULL OR model_id = $3::text)
+        ORDER BY COALESCE(model_id, ''), window_key, principal_id NULLS LAST`, [tenantId, principalId ?? null, modelId ?? null]);
+        return rows.map(toLimit);
+    },
+    async list({ tenantId }) {
+        const rows = await sql.query(
+        // The tenant default first, then principals alphabetically — a stable order, so an admin screen does not
+        // reshuffle between refreshes.
+        `SELECT ${COLUMNS} FROM usage_limits WHERE tenant_id = $1
+        ORDER BY principal_id NULLS FIRST, model_id NULLS FIRST, window_key`, [tenantId]);
+        return rows.map(toLimit);
+    },
+    async remove({ tenantId, principalId, modelId, window }) {
+        // `IS NOT DISTINCT FROM`, so a NULL parameter removes the tenant default rather than matching nothing.
+        await sql.query(`DELETE FROM usage_limits
+        WHERE tenant_id = $1 AND window_key = $2 AND principal_id IS NOT DISTINCT FROM $3::text
+          AND model_id IS NOT DISTINCT FROM $4::text`, [tenantId, windowKey(window), principalId ?? null, modelId ?? null]);
+    },
+});
+//# sourceMappingURL=usage-limits.js.map

package/dist/adapters/postgres/usage.d.ts

@@ -0,0 +1,15 @@
+import type { IdempotencyStore } from "../../idempotency/index.js";
+import type { UsageStore } from "../../persistence/index.js";
+import type { SqlExecutor } from "./sql.js";
+export declare const createPostgresUsageStore: (sql: SqlExecutor) => UsageStore;
+/**
+ * The replay guard. `firstSeen` is `false` on a hit, matching the reference adapter and the type's own
+ * docstring — *"True on the first execution; false when the stored result is returned"* — because a
+ * stored value means the call already ran.
+ *
+ * No expiry column: `put` takes no TTL and the port has no prune method, so nothing could populate
+ * one, and an always-NULL `expires_at` would read as a retention policy that does not exist. Pruning
+ * is an operational query over `created_at`; see the open question on #100 for the policy.
+ */
+export declare const createPostgresIdempotencyStore: (sql: SqlExecutor) => IdempotencyStore;
+//# sourceMappingURL=usage.d.ts.map

package/dist/adapters/postgres/usage.js

@@ -0,0 +1,226 @@
+import { usageDedupeKey } from "../../usage/index.js";
+const iso = (v) => (v instanceof Date ? v.toISOString() : new Date(v).toISOString());
+/** `bigint` and `numeric` come back as strings from node-postgres; `integer` as a number. */
+const int = (v) => (v === null || v === undefined ? 0 : Number(v));
+const json = (value) => (typeof value === "string" ? JSON.parse(value) : value);
+const toEvent = (r) => ({
+    id: r.id,
+    tenantId: r.tenant_id,
+    // #175. Omitted when null: a record from before the column existed has an unknown principal, and that is a
+    // fact rather than something to fill in.
+    ...(r.principal_id === null || r.principal_id === undefined
+        ? {}
+        : { principalId: r.principal_id }),
+    runId: r.run_id,
+    ...(r.conversation_id === null ? {} : { conversationId: r.conversation_id }),
+    ...(r.step_id === null ? {} : { stepId: r.step_id }),
+    ...(r.tool_call_id === null ? {} : { toolCallId: r.tool_call_id }),
+    modelId: r.model_id,
+    inputTokens: int(r.input_tokens),
+    outputTokens: int(r.output_tokens),
+    cachedInputTokens: int(r.cached_input_tokens),
+    ...(r.reasoning_tokens === null ? {} : { reasoningTokens: int(r.reasoning_tokens) }),
+    // Null stays absent: "not counted" and "none" are different facts about a row (#185).
+    ...(r.image_count === null || r.image_count === undefined ? {} : { imageCount: int(r.image_count) }),
+    ...(r.audio_seconds === null || r.audio_seconds === undefined ? {} : { audioSeconds: int(r.audio_seconds) }),
+    costMinorUnits: int(r.cost_minor_units),
+    currency: r.currency,
+    occurredAt: iso(r.occurred_at),
+});
+const USAGE_COLUMNS = `id, tenant_id, principal_id, run_id, conversation_id, step_id, tool_call_id, model_id,
+         input_tokens, output_tokens, cached_input_tokens, reasoning_tokens,
+         image_count, audio_seconds,
+         cost_minor_units, currency, occurred_at`;
+export const createPostgresUsageStore = (sql) => ({
+    async append({ tenantId, event }) {
+        // The conflict target is the dedupe key, not the id: a recovered run may re-record the same step
+        // under a fresh event id, and that must still be a no-op. Keying only on id would let it through.
+        await sql.query(`INSERT INTO usage_records
+         (tenant_id, id, dedupe_key, principal_id, run_id, conversation_id, step_id, tool_call_id, model_id,
+          input_tokens, output_tokens, cached_input_tokens, reasoning_tokens,
+          image_count, audio_seconds,
+          cost_minor_units, currency, occurred_at)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18::timestamptz)
+       ON CONFLICT (tenant_id, dedupe_key) DO NOTHING`, [
+            tenantId,
+            event.id,
+            usageDedupeKey(event),
+            event.principalId ?? null,
+            event.runId,
+            event.conversationId ?? null,
+            event.stepId ?? null,
+            event.toolCallId ?? null,
+            event.modelId,
+            event.inputTokens,
+            event.outputTokens,
+            event.cachedInputTokens,
+            event.reasoningTokens ?? null,
+            event.imageCount ?? null,
+            event.audioSeconds ?? null,
+            event.costMinorUnits,
+            event.currency,
+            event.occurredAt,
+        ]);
+    },
+    async listByRun({ tenantId, runId, limit, cursor }) {
+        // Keyset paging on (occurred_at, id) — the same shape as messages (#96) and for the same reason:
+        // an OFFSET would skip or repeat rows when a concurrent append lands mid-page, and usage appends
+        // continuously while a run is executing.
+        const rows = await sql.query(`WITH anchor AS (
+         SELECT occurred_at, id FROM usage_records WHERE tenant_id = $1 AND id = $3
+       )
+       SELECT ${USAGE_COLUMNS}, occurred_at AS cursor_occurred_at
+         FROM usage_records
+        WHERE tenant_id = $1
+          AND run_id = $2
+          AND ($3::text IS NULL
+               OR (occurred_at, id) > ((SELECT occurred_at FROM anchor), (SELECT id FROM anchor)))
+        ORDER BY occurred_at, id
+        LIMIT $4`, [tenantId, runId, cursor ?? null, limit + 1]);
+        const hasMore = rows.length > limit;
+        const items = (hasMore ? rows.slice(0, limit) : rows).map(toEvent);
+        const last = items[items.length - 1];
+        const page = hasMore && last ? { items, nextCursor: last.id } : { items };
+        return page;
+    },
+    async breakdown({ tenantId, from, to, by, limit }) {
+        /**
+         * The grouping column is chosen from a closed union, never interpolated from user input — every arm is a
+         * literal in this file.
+         *
+         * `principal` is `COALESCE(principal_id, '')` for the same reason `conversation` is: rows written before the
+         * column existed have NULL, and a NULL group key would be dropped by the client rather than shown as
+         * "unattributed" — which is what it honestly is.
+         */
+        const column = by === "model"
+            ? "model_id"
+            : by === "principal"
+                ? "COALESCE(principal_id, '')"
+                : "COALESCE(conversation_id, '')";
+        const rows = await sql.query(`SELECT ${column} AS key,
+              COALESCE(SUM(input_tokens), 0)                  AS input_tokens,
+              COALESCE(SUM(output_tokens), 0)                 AS output_tokens,
+              COALESCE(SUM(cached_input_tokens), 0)           AS cached_input_tokens,
+              COALESCE(SUM(COALESCE(reasoning_tokens, 0)), 0) AS reasoning_tokens,
+              COALESCE(SUM(cost_minor_units), 0)             AS cost_minor_units,
+              COUNT(*)                                       AS event_count
+         FROM usage_records
+        WHERE tenant_id = $1
+          -- Half-open, like every other range here, so adjacent periods tile without a boundary event
+          -- appearing in both.
+          AND occurred_at >= $2::timestamptz AND occurred_at < $3::timestamptz
+        GROUP BY 1
+        -- Largest cost first so a LIMIT drops what matters least; key breaks the tie so the order is stable
+        -- and a rendered breakdown does not reshuffle between refreshes.
+        ORDER BY cost_minor_units DESC, key
+        LIMIT $4`, [tenantId, from, to, limit]);
+        return rows.map((r) => ({
+            key: r.key,
+            totals: {
+                inputTokens: int(r.input_tokens),
+                outputTokens: int(r.output_tokens),
+                cachedInputTokens: int(r.cached_input_tokens),
+                reasoningTokens: int(r.reasoning_tokens),
+                costMinorUnits: int(r.cost_minor_units),
+                eventCount: int(r.event_count),
+            },
+        }));
+    },
+    async totalsBetween({ tenantId, from, to, principalId, modelId }) {
+        /**
+         * One query for the totals **and** the earliest timestamp — #181.
+         *
+         * Two queries could disagree: a record arriving between them would be in one and not the other, and the
+         * refusal message would then name a reset time derived from a set of records different to the total it
+         * refused on.
+         *
+         * Aggregated in the database, like `totals`, because this runs at admission on every message.
+         *
+         * The optional filters are `($n IS NULL OR col = $n)` rather than a built-up WHERE clause: the parameter
+         * list stays fixed, so there is one query plan and no string assembly anywhere near user input. Note the
+         * asymmetry that matters — an absent `principalId` means **every** principal, not the rows whose principal
+         * is NULL, which is why this is a guard on the parameter and not `col IS NULL`.
+         */
+        const rows = await sql.query(`SELECT COALESCE(SUM(input_tokens), 0)                  AS input_tokens,
+              COALESCE(SUM(output_tokens), 0)                 AS output_tokens,
+              COALESCE(SUM(cached_input_tokens), 0)           AS cached_input_tokens,
+              COALESCE(SUM(COALESCE(reasoning_tokens, 0)), 0) AS reasoning_tokens,
+              COALESCE(SUM(cost_minor_units), 0)              AS cost_minor_units,
+              COUNT(*)                                        AS event_count,
+              -- Not COALESCEd: null is the answer when the window is empty, and a substituted date would be a
+              -- reset time for a window nothing was spent in.
+              MIN(occurred_at)                                AS earliest_at
+         FROM usage_records
+        WHERE tenant_id = $1
+          -- Half-open, so adjacent windows tile without a boundary event counting twice.
+          AND occurred_at >= $2::timestamptz AND occurred_at < $3::timestamptz
+          AND ($4::text IS NULL OR principal_id = $4::text)
+          AND ($5::text IS NULL OR model_id = $5::text)`, [tenantId, from, to, principalId ?? null, modelId ?? null]);
+        const row = rows[0];
+        const totals = {
+            inputTokens: int(row?.input_tokens),
+            outputTokens: int(row?.output_tokens),
+            cachedInputTokens: int(row?.cached_input_tokens),
+            reasoningTokens: int(row?.reasoning_tokens),
+            costMinorUnits: int(row?.cost_minor_units),
+            eventCount: int(row?.event_count),
+        };
+        const earliest = row?.earliest_at ?? null;
+        return {
+            totals,
+            // Normalised to the same ISO form every other timestamp in this codebase uses. `pg` hands back a `Date`
+            // for `timestamptz`, and a `Date` compared against an ISO string is a comparison that silently fails.
+            earliestAt: earliest === null ? null : new Date(earliest).toISOString(),
+        };
+    },
+    async totals({ tenantId, runId, conversationId }) {
+        // Aggregated in the database rather than by fetching every row: totals feed `reserve()`, which
+        // runs before each provider call, and a run can accumulate thousands of usage records.
+        const rows = await sql.query(`SELECT COALESCE(SUM(input_tokens), 0)        AS input_tokens,
+              COALESCE(SUM(output_tokens), 0)       AS output_tokens,
+              COALESCE(SUM(cached_input_tokens), 0) AS cached_input_tokens,
+              COALESCE(SUM(reasoning_tokens), 0)    AS reasoning_tokens,
+              COALESCE(SUM(cost_minor_units), 0)    AS cost_minor_units,
+              COUNT(*)                              AS event_count
+         FROM usage_records
+        WHERE tenant_id = $1
+          AND ($2::text IS NULL OR run_id = $2::text)
+          AND ($3::text IS NULL OR conversation_id = $3::text)`, [tenantId, runId ?? null, conversationId ?? null]);
+        const row = rows[0];
+        const totals = {
+            inputTokens: int(row?.input_tokens),
+            outputTokens: int(row?.output_tokens),
+            cachedInputTokens: int(row?.cached_input_tokens),
+            reasoningTokens: int(row?.reasoning_tokens),
+            costMinorUnits: int(row?.cost_minor_units),
+            eventCount: int(row?.event_count),
+        };
+        return totals;
+    },
+});
+/**
+ * The replay guard. `firstSeen` is `false` on a hit, matching the reference adapter and the type's own
+ * docstring — *"True on the first execution; false when the stored result is returned"* — because a
+ * stored value means the call already ran.
+ *
+ * No expiry column: `put` takes no TTL and the port has no prune method, so nothing could populate
+ * one, and an always-NULL `expires_at` would read as a retention policy that does not exist. Pruning
+ * is an operational query over `created_at`; see the open question on #100 for the policy.
+ */
+export const createPostgresIdempotencyStore = (sql) => ({
+    async get({ tenantId, key }) {
+        const rows = await sql.query(`SELECT result FROM idempotency_keys WHERE tenant_id = $1 AND key = $2`, [tenantId, key]);
+        const row = rows[0];
+        if (!row)
+            return null;
+        return { key, firstSeen: false, result: json(row.result) };
+    },
+    async put({ tenantId, key, result }) {
+        // Last write wins on a repeat, matching the reference adapter's `Map.set`. The first result is
+        // what callers read back, because a caller that already got a stored result does not call `put`.
+        await sql.query(`INSERT INTO idempotency_keys (tenant_id, key, result, created_at)
+       VALUES ($1, $2, $3::jsonb, now())
+       ON CONFLICT (tenant_id, key) DO UPDATE SET result = excluded.result`, [tenantId, key, JSON.stringify(result ?? null)]);
+    },
+});
+//# sourceMappingURL=usage.js.map

package/dist/adapters/redis/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Redis adapters that are not the queue.
+ *
+ * `adapters/bullmq` owns the queue and its lock; this directory is for the other things Redis is the natural fit
+ * for. Kept separate so a deployment reading the tree can see that "we use Redis for the queue" and "we use Redis
+ * for realtime" are two decisions, not one.
+ */
+export * from "./realtime.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/redis/index.js

@@ -0,0 +1,9 @@
+/**
+ * Redis adapters that are not the queue.
+ *
+ * `adapters/bullmq` owns the queue and its lock; this directory is for the other things Redis is the natural fit
+ * for. Kept separate so a deployment reading the tree can see that "we use Redis for the queue" and "we use Redis
+ * for realtime" are two decisions, not one.
+ */
+export * from "./realtime.js";
+//# sourceMappingURL=index.js.map

package/dist/adapters/redis/realtime.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Redis pub/sub realtime — the cross-process half that was missing (#161).
+ *
+ * Everything needed for streaming already existed: a durable event log, resumable SSE frames, the projection
+ * fold, and both ports. What did not exist was a `RealtimePublisher`/`LiveEventSource` pair that works when the
+ * publisher and the subscriber are **different processes** — which they always are, since the whole point of the
+ * durable runtime is that the API host and the worker share only Postgres and the queue.
+ *
+ * The consequence was that no client ever saw a token while a run was in progress. The in-memory bus connects a
+ * publisher and a subscriber inside one process, and the worker CLI published to a hard-coded no-op; so the SSE
+ * endpoint replayed the durable log and then waited forever on a channel nothing wrote to. It looked like a
+ * working system with no streaming rather than a broken one.
+ *
+ * **Why pub/sub is the right primitive here, despite being at-most-once.** The durable log is the source of
+ * truth and the stream resumes from a sequence, so a dropped live message costs *latency*, not correctness — a
+ * reconnect fills the gap. The live channel only has to be fast. Reaching for a Redis Stream instead would buy
+ * replay this design already has, at the cost of trimming policy and consumer-group bookkeeping.
+ *
+ * Redis is already a required configuration value and already carries the queue, so this adds no dependency and
+ * no new operational surface.
+ */
+import type { RealtimePublisher } from "../../core/events.js";
+import type { LiveEventSource } from "../../runtime/streaming.js";
+/**
+ * The publish side, narrowed to one method.
+ *
+ * An interface rather than an `ioredis` import so this file stays testable without a server and the package does
+ * not gain a hard dependency for a feature a deployment may not use — the same reasoning the Supabase adapter
+ * gives for its broadcaster.
+ */
+export interface RedisPublishClient {
+    publish(channel: string, message: string): Promise<number> | number;
+}
+/**
+ * The subscribe side.
+ *
+ * **A subscriber connection cannot issue other commands**, which is why this is a separate interface from
+ * `RedisPublishClient` rather than one client doing both: in Redis, a connection in subscriber mode rejects
+ * everything except further subscribe/unsubscribe. A single shared client would work until the first publish
+ * from the same process and then fail confusingly.
+ */
+export interface RedisSubscribeClient {
+    subscribe(channel: string): Promise<unknown>;
+    unsubscribe(channel: string): Promise<unknown>;
+    on(event: "message", listener: (channel: string, message: string) => void): unknown;
+    off?(event: "message", listener: (channel: string, message: string) => void): unknown;
+}
+/** Namespaced, so run events cannot collide with BullMQ's own keys or another app's channels. */
+export declare const realtimeChannel: (channel: string) => string;
+export declare const createRedisRealtimePublisher: (client: RedisPublishClient) => RealtimePublisher;
+export type RedisLiveEventSourceOptions = {
+    /**
+     * How many events one subscriber may buffer before the oldest are dropped.
+     *
+     * A bound, because a subscriber that stops reading must not grow this process's memory — #144's `slow-consumer`
+     * mode is exactly that scenario. Dropping is safe: the durable log is the source of truth, so a client that
+     * fell behind reconnects and resumes from its sequence. An unbounded queue would trade a correctness-preserving
+     * gap for an out-of-memory kill.
+     */
+    readonly maxBuffered?: number;
+    /** Reported when a payload fails validation or the buffer overflows, so neither is silent. */
+    readonly onDropped?: (reason: "invalid-payload" | "buffer-overflow", channel: string) => void;
+};
+export declare const DEFAULT_MAX_BUFFERED = 512;
+/**
+ * The receive side.
+ *
+ * The contract that matters is inherited from `LiveEventSource`: **buffering must begin at `subscribe()` time**,
+ * before the caller's first `next()`. `openRunEventStream` subscribes and *then* reads the durable log, and that
+ * ordering is the only thing stopping an event published during catch-up from being lost. So the Redis
+ * subscription and the listener are established synchronously inside `subscribe`, not lazily in the generator.
+ */
+export declare const createRedisLiveEventSource: (client: RedisSubscribeClient, options?: RedisLiveEventSourceOptions) => LiveEventSource;
+//# sourceMappingURL=realtime.d.ts.map

package/dist/adapters/redis/realtime.js

@@ -0,0 +1,112 @@
+/**
+ * Redis pub/sub realtime — the cross-process half that was missing (#161).
+ *
+ * Everything needed for streaming already existed: a durable event log, resumable SSE frames, the projection
+ * fold, and both ports. What did not exist was a `RealtimePublisher`/`LiveEventSource` pair that works when the
+ * publisher and the subscriber are **different processes** — which they always are, since the whole point of the
+ * durable runtime is that the API host and the worker share only Postgres and the queue.
+ *
+ * The consequence was that no client ever saw a token while a run was in progress. The in-memory bus connects a
+ * publisher and a subscriber inside one process, and the worker CLI published to a hard-coded no-op; so the SSE
+ * endpoint replayed the durable log and then waited forever on a channel nothing wrote to. It looked like a
+ * working system with no streaming rather than a broken one.
+ *
+ * **Why pub/sub is the right primitive here, despite being at-most-once.** The durable log is the source of
+ * truth and the stream resumes from a sequence, so a dropped live message costs *latency*, not correctness — a
+ * reconnect fills the gap. The live channel only has to be fast. Reaching for a Redis Stream instead would buy
+ * replay this design already has, at the cost of trimming policy and consumer-group bookkeeping.
+ *
+ * Redis is already a required configuration value and already carries the queue, so this adds no dependency and
+ * no new operational surface.
+ */
+import { parseRunEvent } from "../../core/validation.js";
+/** Namespaced, so run events cannot collide with BullMQ's own keys or another app's channels. */
+export const realtimeChannel = (channel) => `agentkit:events:${channel}`;
+export const createRedisRealtimePublisher = (client) => ({
+    async publish(channel, event) {
+        // Failure is deliberately *not* swallowed here. The worker decides what a failed publish means; silently
+        // dropping it inside the adapter would make a misconfigured Redis indistinguishable from a quiet run, which
+        // is precisely the bug this file exists to fix.
+        await client.publish(realtimeChannel(channel), JSON.stringify(event));
+    },
+});
+export const DEFAULT_MAX_BUFFERED = 512;
+/**
+ * The receive side.
+ *
+ * The contract that matters is inherited from `LiveEventSource`: **buffering must begin at `subscribe()` time**,
+ * before the caller's first `next()`. `openRunEventStream` subscribes and *then* reads the durable log, and that
+ * ordering is the only thing stopping an event published during catch-up from being lost. So the Redis
+ * subscription and the listener are established synchronously inside `subscribe`, not lazily in the generator.
+ */
+export const createRedisLiveEventSource = (client, options = {}) => {
+    const maxBuffered = options.maxBuffered ?? DEFAULT_MAX_BUFFERED;
+    return {
+        subscribe(channel) {
+            const topic = realtimeChannel(channel);
+            const queue = [];
+            let wake = null;
+            let closed = false;
+            const listener = (incoming, message) => {
+                if (incoming !== topic || closed)
+                    return;
+                let event;
+                try {
+                    // A pub/sub payload is network input. `openRunEventStream` feeds whatever the live source yields
+                    // straight into the projection fold, so an unvalidated message would put corrupt — or attacker-shaped —
+                    // data into a run's state. Parsed and dropped on failure rather than trusted for arriving on the right
+                    // channel, exactly as the Supabase adapter does.
+                    event = parseRunEvent(JSON.parse(message));
+                }
+                catch {
+                    options.onDropped?.("invalid-payload", channel);
+                    return;
+                }
+                if (queue.length >= maxBuffered) {
+                    // Oldest first: the newest events are the ones a live view needs, and a client that fell behind is
+                    // going to reconnect and replay from its sequence anyway.
+                    queue.shift();
+                    options.onDropped?.("buffer-overflow", channel);
+                }
+                queue.push(event);
+                wake?.();
+            };
+            // Established here, synchronously — see the note above. `subscribe` is awaited inside the generator's first
+            // pull, but the *listener* is attached now, so a message arriving between this line and the first `next()`
+            // is queued rather than missed.
+            client.on("message", listener);
+            const subscribed = Promise.resolve(client.subscribe(topic)).catch(() => undefined);
+            return {
+                async *[Symbol.asyncIterator]() {
+                    await subscribed;
+                    try {
+                        for (;;) {
+                            while (queue.length > 0) {
+                                const event = queue.shift();
+                                if (event !== undefined)
+                                    yield event;
+                            }
+                            if (closed)
+                                return;
+                            await new Promise((resolve) => {
+                                wake = () => {
+                                    wake = null;
+                                    resolve();
+                                };
+                            });
+                        }
+                    }
+                    finally {
+                        // Unsubscribing on *any* exit — return, throw, or the consumer breaking out of its loop — because a
+                        // leaked subscription is a listener that keeps buffering for a client that has gone. One per abandoned
+                        // SSE connection is how a host runs out of memory a day later.
+                        closed = true;
+                        client.off?.("message", listener);
+                        await Promise.resolve(client.unsubscribe(topic)).catch(() => undefined);
+                    }
+                },
+            };
+        },
+    };
+};
+//# sourceMappingURL=realtime.js.map