@adonis-agora/agent 0.52.1 → 0.53.0

package/dist/src/lucid-token-stream-sink.js

@@ -0,0 +1,324 @@
+import { AGENT_TABLES, ensureStreamFrameTable, rowsOf } from './stores/lucid-schema.js';
+/** Default TTL (seconds) for a run's rows: 1h past its last write, the same window the Redis sink keeps. */
+const DEFAULT_TTL_SECONDS = 3600;
+/** Default gap (ms) between two reads of a run a subscriber is following. */
+const DEFAULT_POLL_INTERVAL_MS = 250;
+/** Default gap (ms) between two reads once a run has been quiet for {@link IDLE_AFTER_MS}. */
+const DEFAULT_IDLE_POLL_INTERVAL_MS = 1000;
+/** How long a run has to write nothing before its subscribers slow down to the idle interval. */
+const IDLE_AFTER_MS = 5000;
+/** Default window (ms) consecutive `text` frames are gathered over before they are written as one row. */
+const DEFAULT_FLUSH_MS = 50;
+/** Rows read per query, so a long run's replay is paged rather than loaded whole. */
+const READ_PAGE = 500;
+/** Run ids deleted per statement by {@link LucidTokenStreamSink.purgeExpired}. */
+const PURGE_CHUNK = 200;
+/** The least time between two purges an instance starts on its own (see `autoPurge`). */
+const AUTO_PURGE_EVERY_MS = 60_000;
+/** Attempts at one append before a sequence-number collision is reported instead of retried. */
+const APPEND_ATTEMPTS = 8;
+function toInt(value) {
+    if (typeof value === 'number')
+        return value;
+    if (typeof value === 'bigint')
+        return Number(value);
+    if (typeof value === 'string')
+        return Number.parseInt(value, 10) || 0;
+    return 0;
+}
+/**
+ * Did this insert lose the race for a `(run_id, seq)`? Read off the driver's own code — Postgres
+ * `23505`, SQLite `SQLITE_CONSTRAINT_*`, MySQL `ER_DUP_ENTRY`/1062, SQL Server 2627 — so nothing
+ * else (a missing table, a lost connection) is ever retried as though it were one.
+ */
+function isUniqueViolation(error) {
+    const e = error;
+    if (e === null || typeof e !== 'object')
+        return false;
+    if (e.code === '23505' || e.code === 'ER_DUP_ENTRY')
+        return true;
+    if (typeof e.code === 'string' && e.code.startsWith('SQLITE_CONSTRAINT'))
+        return true;
+    return e.errno === 1062 || e.number === 2627;
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * A multi-replica {@link TokenStreamSink} over the app's SQL database (through `@adonisjs/lucid`) —
+ * for a deployment with several replicas and NO Redis. The replica running the model turn appends
+ * each frame as a row of `agent_stream_frame`; any replica serves the run's SSE by reading the rows
+ * past its cursor, in order, until it meets the end marker. A subscriber that attaches late, or
+ * after the run ended, replays from the first row — the same guarantee the in-process and Redis
+ * sinks give.
+ *
+ * Two things differ from the Redis sink, and both are the price of having no broker:
+ *
+ *  - **Delivery is polled.** There is no publish to wake a subscriber, so a frame waits up to
+ *    `pollIntervalMs` (250 ms) before a browser sees it.
+ *  - **Text is coalesced on the way in.** Consecutive `text` frames written within `flushMs`
+ *    (50 ms) are stored as ONE `text` frame holding their concatenation. The stored rows are the
+ *    run's stream: every subscriber, on every replica, reads the same rows in the same order, so
+ *    the SSE event ids `AgentSseEncoder` counts from them — and an `after` cursor — stay exact. They
+ *    are NOT the ids the in-process sink would have produced for the same run (it numbers every
+ *    token), which only matters to a cursor carried across a change of sink.
+ *
+ * Sequence numbers are per run, start at 1 and have no gaps: each append takes `MAX(seq) + 1` for
+ * its run in the same statement that inserts it, and the `(run_id, seq)` primary key turns a
+ * collision into a retry. A run normally has ONE writer, and then no append ever collides; the
+ * retry exists for a parent whose delegated children (each forwarding into its stream, possibly
+ * from another replica) write at once. Nothing depends on ordering across runs.
+ *
+ * Text a writer is still gathering lives in the process for at most `flushMs`; a process that dies
+ * in that window loses it from the LIVE stream (the persisted message is unaffected).
+ *
+ * Wire it with `defineConfig({ sink: tokenSinks.lucid() })`.
+ */
+export class LucidTokenStreamSink {
+    db;
+    table;
+    pollIntervalMs;
+    idlePollIntervalMs;
+    flushMs;
+    ttlSeconds;
+    autoPurge;
+    autoCreateTables;
+    writes = new Map();
+    provisioned;
+    lastAutoPurge = 0;
+    constructor(db, options = {}) {
+        this.db = db;
+        const table = options.tableName ?? AGENT_TABLES.streamFrames;
+        // The name is spliced into SQL (DDL takes no bindings), so it has to be a plain identifier.
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(table)) {
+            throw new Error(`LucidTokenStreamSink: "${table}" is not a valid table name`);
+        }
+        this.table = table;
+        this.pollIntervalMs = Math.max(1, options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
+        this.idlePollIntervalMs = Math.max(this.pollIntervalMs, options.idlePollIntervalMs ?? DEFAULT_IDLE_POLL_INTERVAL_MS);
+        this.flushMs = Math.max(0, options.flushMs ?? DEFAULT_FLUSH_MS);
+        this.ttlSeconds = options.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+        this.autoPurge = options.autoPurge ?? true;
+        this.autoCreateTables = options.autoCreateTables ?? true;
+    }
+    /**
+     * Create the frame table if it is missing. The agent provider calls this once as the app starts;
+     * a sink built by hand falls back to it on first use. A no-op under `autoCreateTables: false`.
+     */
+    ensureSchema() {
+        if (!this.autoCreateTables)
+            return Promise.resolve();
+        if (this.provisioned === undefined) {
+            this.provisioned = ensureStreamFrameTable(this.db, this.table).catch((error) => {
+                this.provisioned = undefined;
+                throw error;
+            });
+        }
+        return this.provisioned;
+    }
+    runWrites(runId) {
+        let state = this.writes.get(runId);
+        if (state === undefined) {
+            state = {
+                text: null,
+                timer: undefined,
+                tail: Promise.resolve(),
+                pending: 0,
+                failure: undefined,
+            };
+            this.writes.set(runId, state);
+        }
+        return state;
+    }
+    /** Forget a run's write state once nothing is gathered, queued or left to report. */
+    release(runId, state) {
+        if (state.pending === 0 &&
+            state.text === null &&
+            state.failure === undefined &&
+            this.writes.get(runId) === state) {
+            this.writes.delete(runId);
+        }
+    }
+    /** Queue `work` behind every write already queued for the run, so rows land in call order. */
+    enqueue(runId, state, work) {
+        state.pending += 1;
+        const next = state.tail.then(work);
+        state.tail = next
+            .then(() => undefined, () => undefined)
+            .then(() => {
+            state.pending -= 1;
+            this.release(runId, state);
+        });
+        return next;
+    }
+    /** Queue the gathered text (if any) as one `text` row. */
+    flushText(runId, state) {
+        if (state.timer !== undefined) {
+            clearTimeout(state.timer);
+            state.timer = undefined;
+        }
+        if (state.text === null)
+            return Promise.resolve();
+        const frame = { t: 'text', v: state.text };
+        state.text = null;
+        return this.enqueue(runId, state, () => this.append(runId, JSON.stringify(frame)));
+    }
+    /** Raise, once, a gathered write that failed with nobody awaiting it. */
+    raiseFailure(state) {
+        const failure = state.failure;
+        if (failure !== undefined) {
+            state.failure = undefined;
+            throw failure.error;
+        }
+    }
+    /** Append one row to the run — a frame, or the end marker (`null`). */
+    async append(runId, frame) {
+        await this.ensureSchema();
+        for (let attempt = 1;; attempt += 1) {
+            try {
+                // The next number and the insert are one statement; see the class comment for why the
+                // primary key, not a lock, is what settles two writers asking at once.
+                await this.db.rawQuery(`INSERT INTO "${this.table}" ("run_id", "seq", "frame", "created_at") ` +
+                    `SELECT ?, COALESCE(MAX("seq"), 0) + 1, ?, ? FROM "${this.table}" WHERE "run_id" = ?`, [runId, frame, Date.now(), runId]);
+                return;
+            }
+            catch (error) {
+                if (attempt >= APPEND_ATTEMPTS || !isUniqueViolation(error))
+                    throw error;
+            }
+        }
+    }
+    /**
+     * The run's writer. Writers opened for the same run in one process share what they are gathering,
+     * so a delegated run's text (forwarded through a {@link childSinkWriter}) and its parent's next
+     * frame keep the order they were written in.
+     */
+    open(runId) {
+        return {
+            write: async (frame) => {
+                const state = this.runWrites(runId);
+                this.raiseFailure(state);
+                if (frame.t === 'text' && this.flushMs > 0) {
+                    state.text = (state.text ?? '') + frame.v;
+                    // Counted from the FIRST gathered token, not the last: a steady stream still reaches the
+                    // table every `flushMs`, instead of being held for as long as the model keeps talking.
+                    if (state.timer === undefined) {
+                        state.timer = setTimeout(() => {
+                            state.timer = undefined;
+                            this.flushText(runId, state).catch((error) => {
+                                state.failure = { error };
+                            });
+                        }, this.flushMs);
+                    }
+                    return;
+                }
+                const flushed = this.flushText(runId, state);
+                const appended = this.enqueue(runId, state, () => this.append(runId, JSON.stringify(frame)));
+                await Promise.all([flushed, appended]);
+            },
+            flush: async () => {
+                const state = this.runWrites(runId);
+                const flushed = this.flushText(runId, state);
+                await Promise.all([flushed, state.tail]);
+                this.raiseFailure(state);
+                this.release(runId, state);
+            },
+            end: async () => {
+                const state = this.runWrites(runId);
+                const flushed = this.flushText(runId, state);
+                const ended = this.enqueue(runId, state, () => this.append(runId, null));
+                await Promise.all([flushed, ended]);
+                this.raiseFailure(state);
+                this.release(runId, state);
+                this.purgeInBackground();
+            },
+        };
+    }
+    async *subscribe(runId) {
+        await this.ensureSchema();
+        let cursor = 0;
+        let quietSince = Date.now();
+        while (true) {
+            const rows = await this.db
+                .from(this.table)
+                .where('run_id', runId)
+                .where('seq', '>', cursor)
+                .orderBy('seq', 'asc')
+                .limit(READ_PAGE)
+                .select('seq', 'frame');
+            let ended = false;
+            for (const row of rows) {
+                cursor = toInt(row.seq);
+                if (row.frame === null || row.frame === undefined) {
+                    ended = true;
+                    continue;
+                }
+                yield JSON.parse(String(row.frame));
+            }
+            if (ended) {
+                return;
+            }
+            if (rows.length > 0) {
+                quietSince = Date.now();
+                // A full page means there may be more already written: read on without waiting.
+                if (rows.length >= READ_PAGE)
+                    continue;
+            }
+            await sleep(Date.now() - quietSince >= IDLE_AFTER_MS ? this.idlePollIntervalMs : this.pollIntervalMs);
+        }
+    }
+    async has(runId) {
+        await this.ensureSchema();
+        return (await this.db.from(this.table).where('run_id', runId).first()) !== null;
+    }
+    async close(runId) {
+        const state = this.writes.get(runId);
+        if (state !== undefined) {
+            if (state.timer !== undefined)
+                clearTimeout(state.timer);
+            state.timer = undefined;
+            state.text = null;
+            state.failure = undefined;
+            await state.tail;
+            this.writes.delete(runId);
+        }
+        await this.ensureSchema();
+        await this.db.from(this.table).where('run_id', runId).delete();
+    }
+    /**
+     * Delete every run whose last write is older than `ttlSeconds` at `now` (epoch ms) — ended runs
+     * past their replay window and runs that crashed without ending alike. Returns how many runs went.
+     * Safe to call from any replica, and from several at once. A no-op under `ttlSeconds: 0`.
+     *
+     * An instance already calls it after a run ends (at most once a minute; `autoPurge`), which keeps
+     * the table bounded on a replica that streams. Call it from a schedule as well if a quiet
+     * deployment must not keep the last hour's streams around indefinitely.
+     */
+    async purgeExpired(now = Date.now()) {
+        if (this.ttlSeconds <= 0)
+            return 0;
+        await this.ensureSchema();
+        const cutoff = now - this.ttlSeconds * 1000;
+        // Two steps rather than one `DELETE … WHERE run_id IN (SELECT … FROM the same table)`, which
+        // MySQL refuses. A run that writes between the two was idle for the whole TTL a moment ago.
+        const lapsed = rowsOf(await this.db.rawQuery(`SELECT "run_id" AS run_id FROM "${this.table}" GROUP BY "run_id" HAVING MAX("created_at") < ?`, [cutoff])).map((row) => String(row.run_id));
+        for (let index = 0; index < lapsed.length; index += PURGE_CHUNK) {
+            await this.db
+                .from(this.table)
+                .whereIn('run_id', lapsed.slice(index, index + PURGE_CHUNK))
+                .delete();
+        }
+        return lapsed.length;
+    }
+    /** {@link purgeExpired}, unawaited and at most once a minute. Its failure is not the run's. */
+    purgeInBackground() {
+        if (!this.autoPurge || this.ttlSeconds <= 0)
+            return;
+        const now = Date.now();
+        if (now - this.lastAutoPurge < AUTO_PURGE_EVERY_MS)
+            return;
+        this.lastAutoPurge = now;
+        this.purgeExpired(now).catch(() => {
+            // Retried after the next run to end; a purge that cannot run must not fail a finished turn.
+        });
+    }
+}
+//# sourceMappingURL=lucid-token-stream-sink.js.map

package/dist/src/lucid-token-stream-sink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lucid-token-stream-sink.js","sourceRoot":"","sources":["../../src/lucid-token-stream-sink.ts"],"names":[],"mappings":"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"}

package/dist/src/mcp/define_config.d.ts

@@ -1,4 +1,5 @@
 import type { RolesPolicy } from '../spi/roles-policy.js';
+import type { EmptyRoles } from '../tool-registry.js';
 import type { McpAuth, McpAuthFactory } from './auth.js';
 import { anyOf, apiKeyAuth, authKitAuth, McpAuthError } from './auth.js';
 /**
@@ -58,6 +59,12 @@ export interface McpConfig {
     authorizer?: RolesPolicy;
     /** Roles a tool requires when it declares none. Defaults to `['ADMIN']`. */
     defaultRoles?: string[];
+    /**
+     * What an empty roles list means to the default authorizer: `'allow'` (default) — no restriction;
+     * `'deny'` — nobody, so a tool needs `roles` (or a non-empty `defaultRoles`) to be reachable. Only
+     * consulted when no `authorizer` is set.
+     */
+    emptyRoles?: EmptyRoles;
     /**
      * Restrict the exposed tools to this allow-list of names. Omit → all tools the acting actor's roles
      * permit are exposed.

package/dist/src/mcp/define_config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define_config.d.ts","sourceRoot":"","sources":["../../../src/mcp/define_config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACzD,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEzE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,SAAS;IACxB,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG,cAAc,CAAC;IAChC;;;;OAIG;IACH,KAAK,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7D;;;OAGG;IACH,UAAU,CAAC,EAAE,WAAW,CAAC;IACzB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,iEAAiE;AACjE,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,CAE5D;AAED,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,qBAAqB,EACrB,OAAO,EACP,cAAc,EACd,cAAc,EACd,gBAAgB,GACjB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,CAAC"}
+{"version":3,"file":"define_config.d.ts","sourceRoot":"","sources":["../../../src/mcp/define_config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACzD,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEzE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,SAAS;IACxB,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG,cAAc,CAAC;IAChC;;;;OAIG;IACH,KAAK,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7D;;;OAGG;IACH,UAAU,CAAC,EAAE,WAAW,CAAC;IACzB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB;;;;OAIG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,iEAAiE;AACjE,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,CAE5D;AAED,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,qBAAqB,EACrB,OAAO,EACP,cAAc,EACd,cAAc,EACd,gBAAgB,GACjB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,CAAC"}

package/dist/src/mcp/define_config.js.map

@@ -1 +1 @@
-{"version":3,"file":"define_config.js","sourceRoot":"","sources":["../../../src/mcp/define_config.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AA8DzE,iEAAiE;AACjE,MAAM,UAAU,eAAe,CAAC,MAAiB;IAC/C,OAAO,MAAM,CAAC;AAChB,CAAC;AAeD,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,CAAC"}
+{"version":3,"file":"define_config.js","sourceRoot":"","sources":["../../../src/mcp/define_config.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAoEzE,iEAAiE;AACjE,MAAM,UAAU,eAAe,CAAC,MAAiB;IAC/C,OAAO,MAAM,CAAC;AAChB,CAAC;AAeD,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,CAAC"}

package/dist/src/spi/confirm-token-store.d.ts

@@ -0,0 +1,30 @@
+/** One confirmation being spent — what {@link ConfirmTokenStore.claim} records. */
+export interface ConfirmTokenClaim {
+    /** SHA-256 (hex) of the token. The token itself is never stored. */
+    hash: string;
+    /** `ctx.actor.id` of the confirming actor. */
+    actorRef: string;
+    /** The tool the token was issued for. */
+    tool: string;
+    /** Epoch-ms the token stops being valid — after it the mark is dead weight and can be purged. */
+    expiresAt: number;
+}
+/**
+ * Makes a confirm token single use (see `defineConfirmedTool`). A signed token is stateless, so on
+ * its own it stays valid until it expires: a double tap, a network retry or a model repeating the
+ * call would commit twice inside that window. The store remembers which tokens were spent.
+ *
+ * Only the token's hash, the actor and the tool name are kept — never an argument or a value.
+ */
+export interface ConfirmTokenStore {
+    /**
+     * Spend the token. `true` = this caller holds it and may commit; `false` = it was already spent.
+     * MUST be atomic: of two concurrent claims for one hash, exactly one gets `true`.
+     */
+    claim(input: ConfirmTokenClaim): Promise<boolean>;
+    /** Give the token back — the commit failed after the claim, so the caller may try again. */
+    release(hash: string): Promise<void>;
+    /** Drop the marks of tokens that expired before `now` (epoch-ms, default the clock). Returns how many. */
+    purgeExpired?(now?: number): Promise<number>;
+}
+//# sourceMappingURL=confirm-token-store.d.ts.map

package/dist/src/spi/confirm-token-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirm-token-store.d.ts","sourceRoot":"","sources":["../../../src/spi/confirm-token-store.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,MAAM,WAAW,iBAAiB;IAChC,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,iGAAiG;IACjG,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClD,4FAA4F;IAC5F,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,0GAA0G;IAC1G,YAAY,CAAC,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC9C"}

package/dist/src/spi/confirm-token-store.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=confirm-token-store.js.map

package/dist/src/spi/confirm-token-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirm-token-store.js","sourceRoot":"","sources":["../../../src/spi/confirm-token-store.ts"],"names":[],"mappings":""}

package/dist/src/spi/token-stream-sink.d.ts

@@ -83,6 +83,12 @@ export interface SinkWriter {
     write(frame: StreamFrame): void | Promise<void>;
     /** Mark the run's stream finished (no more frames). */
     end(): void | Promise<void>;
+    /**
+     * OPTIONAL: write out anything this writer is still holding back, without ending the stream. Only
+     * a sink that gathers frames before writing them (the Lucid sink coalesces text) has anything to
+     * do here; {@link childSinkWriter} calls it where a delegated run would have ended the stream.
+     */
+    flush?(): void | Promise<void>;
 }
 export interface TokenStreamSink {
     /** Open (or reopen) the writer for a run. */
@@ -106,7 +112,9 @@ export interface TokenStreamSink {
  * Forwarding is what makes a sub-agent visible at all: its own runId is not a stream anyone
  * subscribed to, so a question set it parks on would otherwise be written where nobody reads it.
  * The ancestor owns the stream's lifecycle across however many delegations it spans, so the child's
- * `end()` is a no-op — ending the shared stream mid-parent-run would cut the human off.
+ * `end()` is a no-op — ending the shared stream mid-parent-run would cut the human off. It does
+ * {@link SinkWriter.flush} what the child wrote, so nothing of the delegate's is still held back when
+ * its parent (possibly on another replica) writes the next frame.
  */
 export declare function childSinkWriter(inner: SinkWriter): SinkWriter;
 //# sourceMappingURL=token-stream-sink.d.ts.map

package/dist/src/spi/token-stream-sink.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token-stream-sink.d.ts","sourceRoot":"","sources":["../../../src/spi/token-stream-sink.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,KAAK,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAElF;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE;AAC1B;;;;GAIG;GACD;IACE,CAAC,EAAE,WAAW,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AACH;;;;GAIG;GACD;IAAE,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,gBAAgB,CAAA;CAAE;AACzC;;GAEG;GACD;IAAE,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,oBAAoB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AAC7D;;;;;;;;;GASG;GACD;IAAE,CAAC,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,kBAAkB,CAAA;CAAE;AAC9E;;;;;;;;GAQG;GACD;IACE,CAAC,EAAE,UAAU,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,0GAA0G;IAC1G,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEN,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,uDAAuD;IACvD,GAAG,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACtD,8EAA8E;IAC9E,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;IACrD,6CAA6C;IAC7C,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C;;;;;OAKG;IACH,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAO7D"}
+{"version":3,"file":"token-stream-sink.d.ts","sourceRoot":"","sources":["../../../src/spi/token-stream-sink.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,KAAK,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAElF;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE;AAC1B;;;;GAIG;GACD;IACE,CAAC,EAAE,WAAW,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AACH;;;;GAIG;GACD;IAAE,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,gBAAgB,CAAA;CAAE;AACzC;;GAEG;GACD;IAAE,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,oBAAoB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AAC7D;;;;;;;;;GASG;GACD;IAAE,CAAC,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,kBAAkB,CAAA;CAAE;AAC9E;;;;;;;;GAQG;GACD;IACE,CAAC,EAAE,UAAU,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,0GAA0G;IAC1G,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEN,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,uDAAuD;IACvD,GAAG,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B;;;;OAIG;IACH,KAAK,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACtD,8EAA8E;IAC9E,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;IACrD,6CAA6C;IAC7C,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C;;;;;OAKG;IACH,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAM7D"}

package/dist/src/spi/token-stream-sink.js

@@ -5,14 +5,15 @@
  * Forwarding is what makes a sub-agent visible at all: its own runId is not a stream anyone
  * subscribed to, so a question set it parks on would otherwise be written where nobody reads it.
  * The ancestor owns the stream's lifecycle across however many delegations it spans, so the child's
- * `end()` is a no-op — ending the shared stream mid-parent-run would cut the human off.
+ * `end()` is a no-op — ending the shared stream mid-parent-run would cut the human off. It does
+ * {@link SinkWriter.flush} what the child wrote, so nothing of the delegate's is still held back when
+ * its parent (possibly on another replica) writes the next frame.
  */
 export function childSinkWriter(inner) {
     return {
         write: (chunk) => inner.write(chunk),
-        end: () => {
-            /* the top-level run owns end() */
-        },
+        // The top-level run owns end().
+        end: () => inner.flush?.(),
     };
 }
 //# sourceMappingURL=token-stream-sink.js.map

package/dist/src/spi/token-stream-sink.js.map

@@ -1 +1 @@
-{"version":3,"file":"token-stream-sink.js","sourceRoot":"","sources":["../../../src/spi/token-stream-sink.ts"],"names":[],"mappings":"AA2FA;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,KAAiB;IAC/C,OAAO;QACL,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC;QACpC,GAAG,EAAE,GAAG,EAAE;YACR,kCAAkC;QACpC,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"token-stream-sink.js","sourceRoot":"","sources":["../../../src/spi/token-stream-sink.ts"],"names":[],"mappings":"AAiGA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,KAAiB;IAC/C,OAAO;QACL,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC;QACpC,gCAAgC;QAChC,GAAG,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE;KAC3B,CAAC;AACJ,CAAC"}

package/dist/src/stores/factory.d.ts

@@ -336,6 +336,48 @@ export interface RedisTokenSinkConfig {
      */
     client?: RedisStreamClient;
 }
+/** Options for the Lucid (SQL) multi-replica token-stream sink — several replicas, no Redis. */
+export interface LucidTokenSinkConfig {
+    /** Lucid connection name to use. Defaults to the `Database` default connection. */
+    connection?: string;
+    /** The frame table. Defaults to `agent_stream_frame`. */
+    tableName?: string;
+    /**
+     * Gap (ms) between two reads of a run a subscriber is following — the most a frame waits before a
+     * browser sees it. Defaults to 250.
+     */
+    pollIntervalMs?: number;
+    /**
+     * Gap (ms) between two reads once the run has been quiet for five seconds (parked on a human, a
+     * slow tool). Defaults to 1000.
+     */
+    idlePollIntervalMs?: number;
+    /**
+     * Window (ms) consecutive `text` frames are gathered over and written as one row, so a streamed
+     * answer is a handful of inserts rather than one per token. Defaults to 50; `0` writes every frame.
+     */
+    flushMs?: number;
+    /**
+     * TTL (seconds) of a run's rows, counted from its last write; `purgeExpired()` deletes what has
+     * lapsed. Defaults to 3600 (1h). Set `0` to retain until manual cleanup.
+     */
+    ttlSeconds?: number;
+    /**
+     * Purge lapsed runs as a side effect of ending a run, at most once a minute per replica. Default
+     * `true`. Set `false` to purge only from your own schedule (`sink.purgeExpired()`).
+     */
+    autoPurge?: boolean;
+    /**
+     * Create the frame table when the app starts. Default `true`. Set `false` to run the published
+     * migration (`createAgentTables`, which creates it too) instead.
+     */
+    autoCreateTables?: boolean;
+    /**
+     * Bring-your-own Lucid database (or any {@link LucidDatabaseLike}). When set, `'lucid.db'` is NOT
+     * resolved from the container and `connection` is ignored. Handy for tests and scripts.
+     */
+    db?: LucidDatabaseLike;
+}
 /**
  * The token-sink factory namespace used in `config/agent.ts`, mirroring {@link stores}. Also exported as
  * `streamTransports` (an alias — pick whichever name reads better):
@@ -352,7 +394,8 @@ export interface RedisTokenSinkConfig {
  * Omitting `sink` entirely keeps the in-process sink (single replica); `tokenSinks.memory()` selects it
  * explicitly. `tokenSinks.redis()` fans a run's tokens across replicas over Redis pub/sub + a replayable
  * list, keeping the SSE envelope byte-identical. The `@adonisjs/redis` peer is imported ONLY inside the
- * `redis` thunk, so it stays fully optional.
+ * `redis` thunk, so it stays fully optional. `tokenSinks.lucid()` is the multi-replica sink for a
+ * deployment WITHOUT Redis: frames are rows in the app's SQL database, read by polling.
  */
 export declare const tokenSinks: {
     /** The in-process sink — per-run in-memory buffers, single replica. The default when `sink` is omitted. */
@@ -364,6 +407,14 @@ export declare const tokenSinks: {
      * passed.
      */
     redis(config?: RedisTokenSinkConfig): TokenSinkFactory;
+    /**
+     * The Lucid (SQL) multi-replica sink: any pod can serve any run's SSE stream, with no Redis — a
+     * run's frames are rows of `agent_stream_frame` on the app's database, which subscribers poll.
+     * Slower to deliver than Redis (up to `pollIntervalMs`) and it writes to your database on every
+     * streamed answer; pick {@link tokenSinks.redis} when Redis is already there. Requires
+     * `@adonisjs/lucid` installed + configured unless a `db` is passed.
+     */
+    lucid(config?: LucidTokenSinkConfig): TokenSinkFactory;
 };
 /** Alias of {@link tokenSinks}. */
 export declare const streamTransports: {
@@ -376,6 +427,14 @@ export declare const streamTransports: {
      * passed.
      */
     redis(config?: RedisTokenSinkConfig): TokenSinkFactory;
+    /**
+     * The Lucid (SQL) multi-replica sink: any pod can serve any run's SSE stream, with no Redis — a
+     * run's frames are rows of `agent_stream_frame` on the app's database, which subscribers poll.
+     * Slower to deliver than Redis (up to `pollIntervalMs`) and it writes to your database on every
+     * streamed answer; pick {@link tokenSinks.redis} when Redis is already there. Requires
+     * `@adonisjs/lucid` installed + configured unless a `db` is passed.
+     */
+    lucid(config?: LucidTokenSinkConfig): TokenSinkFactory;
 };
 /**
  * A configured {@link ActorDirectory}: a lazy thunk the agent provider calls at boot to build the

package/dist/src/stores/factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../src/stores/factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,KAAK,EACV,uBAAuB,EAGxB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,oBAAoB,EACrB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EACV,4BAA4B,EAC5B,sBAAsB,EACvB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAC3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,kBAAkB,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,YAAY,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;AAwCtE;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAIhF;AAED,qDAAqD;AACrD,MAAM,WAAW,gBAAgB;IAC/B,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,qEAAqE;AACrE,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAEtD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,MAAM;IACjB,2FAA2F;IAC3F,MAAM,WAAU,iBAAiB,GAAQ,YAAY;IAOrD,8EAA8E;IAC9E,KAAK,UAAS,gBAAgB,GAAQ,YAAY;CAgBnD,CAAC;AAIF,wFAAwF;AACxF,MAAM,MAAM,cAAc,GAAG,YAAY,CAAC;AAE1C,iFAAiF;AACjF,MAAM,MAAM,cAAc,GAAG,CAC3B,GAAG,EAAE,cAAc,KAChB,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAEpD,kDAAkD;AAClD,MAAM,WAAW,kBAAkB;IACjC,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa;IACxB,gEAAgE;IAChE,MAAM,IAAI,cAAc;IAOxB,+FAA+F;IAC/F,KAAK,UAAS,kBAAkB,GAAQ,cAAc;CAcvD,CAAC;AAIF;;;;;;GAMG;AACH,MAAM,WAAW,wBAAyB,SAAQ,YAAY;IAC5D,YAAY,CAAC,EAAE,iBAAiB,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,MAAM,wBAAwB,GAAG,CACrC,GAAG,EAAE,wBAAwB,KAC1B,sBAAsB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;AAE9D,0DAA0D;AAC1D,MAAM,WAAW,qBAAqB;IACpC,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB;IAC5B,sGAAsG;IACtG,KAAK,UAAS,qBAAqB,GAAQ,wBAAwB;CAcpE,CAAC;AAIF,0FAA0F;AAC1F,MAAM,MAAM,gBAAgB,GAAG,YAAY,CAAC;AAE5C;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,gBAAgB,KAAK,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;AAEzF,6GAA6G;AAC7G,MAAM,MAAM,gBAAgB,GAAG,MAAM,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAEpF,mFAAmF;AACnF,MAAM,WAAW,qBAAqB;IACpC,kGAAkG;IAClG,QAAQ,EAAE,iBAAiB,GAAG,gBAAgB,CAAC;IAC/C,iGAAiG;IACjG,SAAS,CAAC,EAAE,cAAc,EAAE,CAAC;IAC7B,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,oGAAoG;AACpG,MAAM,WAAW,uBAAuB;IACtC,kGAAkG;IAClG,QAAQ,EAAE,iBAAiB,GAAG,gBAAgB,CAAC;IAC/C;;;OAGG;IACH,EAAE,CAAC,EAAE,iBAAiB,CAAC;IACvB,kGAAkG;IAClG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iGAAiG;IACjG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IACvC,+EAA+E;IAC/E,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,qFAAqF;IACrF,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,8EAA8E;IAC9E,aAAa,CAAC,EAAE,oBAAoB,CAAC,eAAe,CAAC,CAAC;IACtD,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,iBAAiB,GAAG;QAAE,MAAM,CAAC,EAAE,sBAAsB,CAAA;KAAE,CAAC;IACnE;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,kGAAkG;IAClG,SAAS,CAAC,EAAE,cAAc,EAAE,CAAC;IAC7B,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,0GAA0G;AAC1G,MAAM,WAAW,qBAAqB;IACpC,4EAA4E;IAC5E,QAAQ,EAAE,iBAAiB,GAAG,CAAC,MAAM,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC;IACjE,oFAAoF;IACpF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sGAAsG;IACtG,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,6FAA6F;IAC7F,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,wEAAwE;IACxE,SAAS,CAAC,EAAE,cAAc,EAAE,CAAC;IAC7B,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,UAAU;IACrB,uGAAuG;IACvG,MAAM,SAAS,qBAAqB,GAAG,gBAAgB;IAoBvD;;;;;OAKG;IACH,QAAQ,SAAS,uBAAuB,GAAG,gBAAgB;IA2D3D;;;;OAIG;IACH,MAAM,SAAS,qBAAqB,GAAG,gBAAgB;CAkCxD,CAAC;AAIF,mGAAmG;AACnG,MAAM,MAAM,wBAAwB,GAAG,YAAY,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,MAAM,wBAAwB,GAAG,CACrC,GAAG,EAAE,wBAAwB,KAC1B,sBAAsB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;AAE9D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB;IAC3B;;;;;OAKG;IACH,KAAK,WAAU,uBAAuB,GAAQ,wBAAwB;IAmBtE;;;OAGG;IACH,MAAM,UAAS,4BAA4B,GAAQ,wBAAwB;CAQ5E,CAAC;AAIF;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,YAAY,KAAK,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;AAEjG,6DAA6D;AAC7D,MAAM,WAAW,oBAAoB;IACnC,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU;IACrB,2GAA2G;IAC3G,MAAM,IAAI,gBAAgB;IAO1B;;;;;OAKG;IACH,KAAK,UAAS,oBAAoB,GAAQ,gBAAgB;CAU3D,CAAC;AAEF,mCAAmC;AACnC,eAAO,MAAM,gBAAgB;IA3B3B,2GAA2G;cACjG,gBAAgB;IAO1B;;;;;OAKG;mBACW,oBAAoB,GAAQ,gBAAgB;CAalB,CAAC;AAsF3C;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,GAAG,EAAE,YAAY,KAAK,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;AAEpG,iDAAiD;AACjD,MAAM,WAAW,0BAA0B;IACzC,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB;IAC3B,uFAAuF;IACvF,MAAM,UAAS,0BAA0B,GAAQ,qBAAqB;CAMvE,CAAC"}
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../src/stores/factory.ts"],"names":[],"mappings":"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"}

package/dist/src/stores/factory.js

@@ -318,7 +318,8 @@ export const attachmentStores = {
  * Omitting `sink` entirely keeps the in-process sink (single replica); `tokenSinks.memory()` selects it
  * explicitly. `tokenSinks.redis()` fans a run's tokens across replicas over Redis pub/sub + a replayable
  * list, keeping the SSE envelope byte-identical. The `@adonisjs/redis` peer is imported ONLY inside the
- * `redis` thunk, so it stays fully optional.
+ * `redis` thunk, so it stays fully optional. `tokenSinks.lucid()` is the multi-replica sink for a
+ * deployment WITHOUT Redis: frames are rows in the app's SQL database, read by polling.
  */
 export const tokenSinks = {
     /** The in-process sink — per-run in-memory buffers, single replica. The default when `sink` is omitted. */
@@ -344,6 +345,25 @@ export const tokenSinks = {
             });
         };
     },
+    /**
+     * The Lucid (SQL) multi-replica sink: any pod can serve any run's SSE stream, with no Redis — a
+     * run's frames are rows of `agent_stream_frame` on the app's database, which subscribers poll.
+     * Slower to deliver than Redis (up to `pollIntervalMs`) and it writes to your database on every
+     * streamed answer; pick {@link tokenSinks.redis} when Redis is already there. Requires
+     * `@adonisjs/lucid` installed + configured unless a `db` is passed.
+     */
+    lucid(config = {}) {
+        return async (ctx) => {
+            const { LucidTokenStreamSink } = await import('../lucid-token-stream-sink.js');
+            const { connection, db: ownDb, ...options } = config;
+            const manager = ownDb === undefined ? await resolveLucidDatabase(ctx.app) : undefined;
+            const db = ownDb ??
+                (connection !== undefined
+                    ? manager?.connection(connection)
+                    : manager);
+            return new LucidTokenStreamSink(db, Object.fromEntries(Object.entries(options).filter(([, value]) => value !== undefined)));
+        };
+    },
 };
 /** Alias of {@link tokenSinks}. */
 export const streamTransports = tokenSinks;