@adonis-agora/agent 0.48.0 → 0.50.0

package/dist/src/spi/chat-queue.d.ts

@@ -0,0 +1,133 @@
+import type { Actor, MessageAttachment, PageContext } from '../types.js';
+import { type AgentStore } from './agent-store.js';
+/**
+ * Why a thread's queue stopped draining. A paused queue keeps its messages; nothing starts until
+ * someone resumes it (`POST <base>/threads/:id/queue/resume`, `chat.queue.resume()`).
+ *
+ *  - `run_failed`     the turn before it failed — the next message would likely fail the same way,
+ *                     and the person should see the error before more of their messages are spent.
+ *  - `cancelled`      someone pressed Stop. Stop means stop: the queue does not start behind it.
+ *                     An interrupt (`mode: 'interrupt'`) is the exception — its message starts.
+ *  - `quota_exceeded` the next message's actor is over budget; resuming later retries the check.
+ *  - `start_failed`   the next message could not be started (the runner refused it).
+ */
+export type QueuePauseReason = 'run_failed' | 'cancelled' | 'quota_exceeded' | 'start_failed';
+export interface QueuePause {
+    reason: QueuePauseReason;
+    /** Human-facing detail (the failure, the quota window), when there is one. */
+    message?: string;
+    /** ISO-8601 instant the queue paused. */
+    at: string;
+}
+/**
+ * A message a person sent while a turn was still running on the thread, waiting its turn. It is not
+ * part of the transcript until it starts: the loop appends it as the turn's user message, exactly as
+ * if it had been sent then. Everything a send carries is captured at enqueue time, resolved and
+ * checked there (agent, model, attachments), so a queued message starts with no request around it.
+ */
+export interface QueuedMessage {
+    id: string;
+    threadId: string;
+    /** Who queued it. The turn it starts runs as this actor. */
+    actor: Actor;
+    content: string;
+    attachments?: MessageAttachment[];
+    agentName?: string;
+    model?: string;
+    pageContext?: PageContext;
+    /**
+     * Queued by an interrupt (`POST chat { mode: 'interrupt' }`): the running turn was cancelled to
+     * make room for it, so the cancel starts it instead of pausing the queue.
+     */
+    interrupt?: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/** A queued message as the wire shows it — {@link QueuedMessage} without the actor or thread. */
+export interface QueuedMessageView {
+    id: string;
+    content: string;
+    attachments?: MessageAttachment[];
+    agentName?: string;
+    model?: string;
+    interrupt?: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * A thread's queue: its waiting messages in the order they will run, and whether it is draining.
+ * What `GET <base>/threads/:id/queue` answers, what `ThreadDetail.queue` carries, and what every
+ * `queue` stream frame snapshots.
+ */
+export interface ChatQueueState {
+    items: QueuedMessageView[];
+    paused: QueuePause | null;
+}
+export interface EnqueueMessageInput {
+    threadId: string;
+    actor: Actor;
+    content: string;
+    attachments?: MessageAttachment[];
+    agentName?: string;
+    model?: string;
+    pageContext?: PageContext;
+    interrupt?: boolean;
+    /** `'tail'` (default) runs it after everything already waiting; `'head'` runs it next. */
+    at?: 'tail' | 'head';
+}
+/** What `PATCH <base>/queue/:messageId` may change. An omitted key leaves the field as it is. */
+export interface QueuedMessagePatch {
+    content?: string;
+    /** `null` drops every attachment. */
+    attachments?: MessageAttachment[] | null;
+}
+/**
+ * A store that can hold a thread's queue of waiting messages, and admit ONE run per thread at a time.
+ *
+ * Probed STRUCTURALLY ({@link isChatQueueStore}), like `ThreadTurnReader`: a store that predates it
+ * keeps the old behaviour (a send on a busy thread starts a second, concurrent run). All members or
+ * none — a queue without the admission primitives cannot be drained safely across processes.
+ *
+ * Admission is the thread's active run (`activeRunId` on a thread read), compare-and-set:
+ *  - {@link claimActiveStream} sets it to `runId` only when it is free, already `runId` (a retried
+ *    claim is idempotent), or held by `replacing` (a handoff from the run that is settling, or a
+ *    takeover from a holder the runner reports dead). Exactly one of two racing claims wins.
+ *  - {@link releaseActiveStream} clears it only when `runId` still holds it — so a run that settles
+ *    after it handed the thread to the next one cannot clear the next one's claim.
+ */
+export interface ChatQueueStore {
+    enqueueMessage(input: EnqueueMessageInput): Promise<QueuedMessage>;
+    /** The thread's waiting messages, in run order (the head first). */
+    listQueue(threadId: string): Promise<QueuedMessage[]>;
+    getQueuedMessage(id: string): Promise<QueuedMessage | null>;
+    /** `null` when there is no such message (it started, or was removed). */
+    updateQueuedMessage(id: string, patch: QueuedMessagePatch): Promise<QueuedMessage | null>;
+    /** Move a message to `index` (clamped) in its thread's run order. `false` when it is gone. */
+    moveQueuedMessage(id: string, index: number): Promise<boolean>;
+    /**
+     * Remove a message. `false` when it was already gone — which is also how a drain learns that the
+     * head it was about to start was deleted under it, so it must be a real conditional delete.
+     */
+    removeQueuedMessage(id: string): Promise<boolean>;
+    /** Remove every waiting message on the thread; answers how many there were. */
+    clearQueue(threadId: string): Promise<number>;
+    queuePause(threadId: string): Promise<QueuePause | null>;
+    setQueuePause(threadId: string, pause: QueuePause | null): Promise<void>;
+    /** The run currently holding the thread, or `null`. */
+    activeRunForThread(threadId: string): Promise<string | null>;
+    claimActiveStream(threadId: string, runId: string, options?: {
+        replacing?: string;
+    }): Promise<boolean>;
+    releaseActiveStream(threadId: string, runId: string): Promise<boolean>;
+}
+/** Whether `store` implements every {@link ChatQueueStore} member. */
+export declare function isChatQueueStore(store: AgentStore): store is AgentStore & ChatQueueStore;
+/**
+ * Release the thread `runId` was streaming — conditionally when the store can compare, so a run
+ * that already handed the thread to the next queued turn does not clear that turn's claim; the old
+ * unconditional clear on a store that cannot.
+ */
+export declare function releaseThreadRun(store: AgentStore, threadId: string, runId: string): Promise<void>;
+/** The wire view of a queued message. */
+export declare function queuedMessageView(message: QueuedMessage): QueuedMessageView;
+//# sourceMappingURL=chat-queue.d.ts.map

package/dist/src/spi/chat-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-queue.d.ts","sourceRoot":"","sources":["../../../src/spi/chat-queue.ts"],"names":[],"mappings":"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"}

package/dist/src/spi/chat-queue.js

@@ -0,0 +1,48 @@
+import { clearActiveRun } from './agent-store.js';
+const CHAT_QUEUE_METHODS = [
+    'enqueueMessage',
+    'listQueue',
+    'getQueuedMessage',
+    'updateQueuedMessage',
+    'moveQueuedMessage',
+    'removeQueuedMessage',
+    'clearQueue',
+    'queuePause',
+    'setQueuePause',
+    'activeRunForThread',
+    'claimActiveStream',
+    'releaseActiveStream',
+];
+/** Whether `store` implements every {@link ChatQueueStore} member. */
+export function isChatQueueStore(store) {
+    const candidate = store;
+    return CHAT_QUEUE_METHODS.every((method) => typeof candidate[method] === 'function');
+}
+/**
+ * Release the thread `runId` was streaming — conditionally when the store can compare, so a run
+ * that already handed the thread to the next queued turn does not clear that turn's claim; the old
+ * unconditional clear on a store that cannot.
+ */
+export async function releaseThreadRun(store, threadId, runId) {
+    if (isChatQueueStore(store)) {
+        await store.releaseActiveStream(threadId, runId);
+        return;
+    }
+    await clearActiveRun(store, threadId, runId);
+}
+/** The wire view of a queued message. */
+export function queuedMessageView(message) {
+    return {
+        id: message.id,
+        content: message.content,
+        ...(message.attachments !== undefined && message.attachments.length > 0
+            ? { attachments: message.attachments }
+            : {}),
+        ...(message.agentName !== undefined ? { agentName: message.agentName } : {}),
+        ...(message.model !== undefined ? { model: message.model } : {}),
+        ...(message.interrupt === true ? { interrupt: true } : {}),
+        createdAt: message.createdAt,
+        updatedAt: message.updatedAt,
+    };
+}
+//# sourceMappingURL=chat-queue.js.map

package/dist/src/spi/chat-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-queue.js","sourceRoot":"","sources":["../../../src/spi/chat-queue.ts"],"names":[],"mappings":"AACA,OAAO,EAAmB,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAuInE,MAAM,kBAAkB,GAAG;IACzB,gBAAgB;IAChB,WAAW;IACX,kBAAkB;IAClB,qBAAqB;IACrB,mBAAmB;IACnB,qBAAqB;IACrB,YAAY;IACZ,YAAY;IACZ,eAAe;IACf,oBAAoB;IACpB,mBAAmB;IACnB,qBAAqB;CAC+B,CAAC;AAEvD,sEAAsE;AACtE,MAAM,UAAU,gBAAgB,CAAC,KAAiB;IAChD,MAAM,SAAS,GAAG,KAA2C,CAAC;IAC9D,OAAO,kBAAkB,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,SAAS,CAAC,MAAM,CAAC,KAAK,UAAU,CAAC,CAAC;AACvF,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,KAAiB,EACjB,QAAgB,EAChB,KAAa;IAEb,IAAI,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,KAAK,CAAC,mBAAmB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QACjD,OAAO;IACT,CAAC;IACD,MAAM,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;AAC/C,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,iBAAiB,CAAC,OAAsB;IACtD,OAAO;QACL,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,GAAG,CAAC,OAAO,CAAC,WAAW,KAAK,SAAS,IAAI,OAAO,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC;YACrE,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE;YACtC,CAAC,CAAC,EAAE,CAAC;QACP,GAAG,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,GAAG,CAAC,OAAO,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1D,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,SAAS,EAAE,OAAO,CAAC,SAAS;KAC7B,CAAC;AACJ,CAAC"}

package/dist/src/spi/model-catalog.d.ts

@@ -21,9 +21,22 @@ export interface ModelCatalogProviderGroup {
     label: string;
     models: ModelCatalogEntry[];
 }
+/** The agent always runs on one model: the picker shows it and offers no choice. */
+export interface ModelCatalogLock {
+    /** The catalog id every turn runs on. */
+    model: string;
+    /** Why, in words a picker can show ("This assistant always uses GPT-5"). */
+    reason?: string;
+}
 /** What `GET <base>/models` answers. */
 export interface ModelCatalogView {
     providers: ModelCatalogProviderGroup[];
+    /**
+     * Present when the agent is locked to one model. Every turn runs on `locked.model` — a send's own
+     * `model` and a thread's pin included — and a send naming another model is refused (`400`). List
+     * the other models as unavailable too, so an older client that ignores the lock cannot pick them.
+     */
+    locked?: ModelCatalogLock;
     /** The model a turn runs on when nobody picked one; `null` when the provider decides. */
     default: string | null;
 }

package/dist/src/spi/model-catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-catalog.d.ts","sourceRoot":"","sources":["../../../src/spi/model-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,qBAAqB,CAAC;AAExE,mCAAmC;AACnC,MAAM,WAAW,iBAAiB;IAChC,oGAAoG;IACpG,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gGAAgG;IAChG,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,wGAAwG;IACxG,SAAS,EAAE,OAAO,CAAC;IACnB,yDAAyD;IACzD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,yDAAyD;IACzD,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,0DAA0D;AAC1D,MAAM,WAAW,yBAAyB;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,iBAAiB,EAAE,CAAC;CAC7B;AAED,wCAAwC;AACxC,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,yBAAyB,EAAE,CAAC;IACvC,yFAAyF;IACzF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,KAAK,CAAC;IACb,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,KAAK,EAAE,iBAAiB,GAAG,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC9E;AAED,qFAAqF;AACrF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,YAAY,CAEvE;AAED,0EAA0E;AAC1E,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,gBAAgB,GAAG,YAAY,CAInF;AAED,sDAAsD;AACtD,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,gBAAgB,EACtB,EAAE,EAAE,MAAM,GACT,iBAAiB,GAAG,SAAS,CAM/B;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,CAIvF;AAED;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF"}
+{"version":3,"file":"model-catalog.d.ts","sourceRoot":"","sources":["../../../src/spi/model-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,qBAAqB,CAAC;AAExE,mCAAmC;AACnC,MAAM,WAAW,iBAAiB;IAChC,oGAAoG;IACpG,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gGAAgG;IAChG,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,wGAAwG;IACxG,SAAS,EAAE,OAAO,CAAC;IACnB,yDAAyD;IACzD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,yDAAyD;IACzD,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,0DAA0D;AAC1D,MAAM,WAAW,yBAAyB;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,iBAAiB,EAAE,CAAC;CAC7B;AAED,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wCAAwC;AACxC,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,yBAAyB,EAAE,CAAC;IACvC;;;;OAIG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,yFAAyF;IACzF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,KAAK,CAAC;IACb,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,KAAK,EAAE,iBAAiB,GAAG,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC9E;AAED,qFAAqF;AACrF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,YAAY,CAEvE;AAED,0EAA0E;AAC1E,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,gBAAgB,GAAG,YAAY,CAInF;AAED,sDAAsD;AACtD,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,gBAAgB,EACtB,EAAE,EAAE,MAAM,GACT,iBAAiB,GAAG,SAAS,CAM/B;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,CAIvF;AAED;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF"}

package/dist/src/spi/model-catalog.js.map

@@ -1 +1 @@
-{"version":3,"file":"model-catalog.js","sourceRoot":"","sources":["../../../src/spi/model-catalog.ts"],"names":[],"mappings":"AAoDA,qFAAqF;AACrF,MAAM,UAAU,kBAAkB,CAAC,IAAsB;IACvD,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC;AAC9B,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,cAAc,CAAC,KAAsC;IACnE,OAAO,OAAQ,KAAsB,CAAC,IAAI,KAAK,UAAU;QACvD,CAAC,CAAE,KAAsB;QACzB,CAAC,CAAC,kBAAkB,CAAC,KAAyB,CAAC,CAAC;AACpD,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,gBAAgB,CAC9B,IAAsB,EACtB,EAAU;IAEV,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QACnC,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5D,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;IACxC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAuB,EAAE,KAAa;IACtE,OAAO;QACL,OAAO,EAAE,CAAC,IAAmB,EAAE,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,CAAC;KACvE,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF"}
+{"version":3,"file":"model-catalog.js","sourceRoot":"","sources":["../../../src/spi/model-catalog.ts"],"names":[],"mappings":"AAkEA,qFAAqF;AACrF,MAAM,UAAU,kBAAkB,CAAC,IAAsB;IACvD,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC;AAC9B,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,cAAc,CAAC,KAAsC;IACnE,OAAO,OAAQ,KAAsB,CAAC,IAAI,KAAK,UAAU;QACvD,CAAC,CAAE,KAAsB;QACzB,CAAC,CAAC,kBAAkB,CAAC,KAAyB,CAAC,CAAC;AACpD,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,gBAAgB,CAC9B,IAAsB,EACtB,EAAU;IAEV,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QACnC,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5D,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;IACxC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAuB,EAAE,KAAa;IACtE,OAAO;QACL,OAAO,EAAE,CAAC,IAAmB,EAAE,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,CAAC;KACvE,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF"}

package/dist/src/spi/quota-provider.d.ts

@@ -4,7 +4,11 @@ export type QuotaPeriod = 'day' | 'month';
 /** One budget window: what was spent in it, and the ceiling when there is one. */
 export interface QuotaWindow {
     period: QuotaPeriod;
-    usedTokens: number;
+    /**
+     * Tokens used in the window. Absent → the budget does not count tokens (a USD-only spend cap, such
+     * as an AI gateway's) — never a fabricated `0`.
+     */
+    usedTokens?: number;
     /** Absent → no token ceiling on this window. */
     limitTokens?: number;
     usedUsd: number;
@@ -12,6 +16,11 @@ export interface QuotaWindow {
     limitUsd?: number;
     /** ISO-8601 instant the window starts over (next UTC midnight, first of next month). */
     resetsAt?: string;
+    /**
+     * The soft limit: the share of a ceiling (`0..1`, e.g. `0.8`) past which a client should warn
+     * that the budget is running out. Absent → no warning for this window.
+     */
+    warnAt?: number;
 }
 /** Which window stopped the actor, when one did. */
 export interface QuotaBlock {
@@ -19,11 +28,24 @@ export interface QuotaBlock {
     /** Words a client can show ("Monthly AI budget reached"). */
     reason?: string;
 }
+/** A window past its soft limit ({@link QuotaWindow.warnAt}) but not exhausted. */
+export interface QuotaWarning {
+    period: QuotaPeriod;
+    /** How much of the window's ceiling is used, `0..1` (the larger of spend and tokens). */
+    ratio: number;
+    /** Words a client can show ("80% of your monthly AI budget used"). */
+    reason?: string;
+}
 /** What `GET <base>/quota` answers. */
 export interface QuotaReport {
     windows: QuotaWindow[];
     /** Present when a window is exhausted — a send will be refused until it resets. */
     blocked?: QuotaBlock;
+    /**
+     * Present when a window crossed its `warnAt` and none is exhausted — the fullest one. A client
+     * may also derive it from the windows ({@link quotaWarning}); the server's wins.
+     */
+    warning?: QuotaWarning;
 }
 export interface QuotaQuery {
     actor: Actor;
@@ -44,6 +66,13 @@ export interface QuotaProvider {
 }
 /** The first window whose token or spend ceiling is reached, as a {@link QuotaBlock}. */
 export declare function exhaustedWindow(windows: readonly QuotaWindow[]): QuotaBlock | undefined;
+/** How much of `window`'s ceilings is used, `0..1+` (the larger of spend and tokens), or `null`. */
+export declare function quotaUsedRatio(window: QuotaWindow): number | null;
+/**
+ * The fullest window past its `warnAt`, as a {@link QuotaWarning} — `undefined` when none is, or
+ * when one is exhausted (that is `blocked`, not a warning).
+ */
+export declare function quotaWarning(windows: readonly QuotaWindow[]): QuotaWarning | undefined;
 /** The UTC day range (`YYYY-MM-DD`, inclusive) and reset instant of `period` around `now`. */
 export declare function quotaPeriodRange(period: QuotaPeriod, now: Date): {
     fromDay: string;

package/dist/src/spi/quota-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"quota-provider.d.ts","sourceRoot":"","sources":["../../../src/spi/quota-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,mDAAmD;AACnD,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,OAAO,CAAC;AAE1C,kFAAkF;AAClF,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,WAAW,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wFAAwF;IACxF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,oDAAoD;AACpD,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,WAAW,CAAC;IACpB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,uCAAuC;AACvC,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,mFAAmF;IACnF,OAAO,CAAC,EAAE,UAAU,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,KAAK,CAAC;IACb,kDAAkD;IAClD,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CACjD;AAED,yFAAyF;AACzF,wBAAgB,eAAe,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,UAAU,GAAG,SAAS,CAYvF;AAED,8FAA8F;AAC9F,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,WAAW,EACnB,GAAG,EAAE,IAAI,GACR;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAetD;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAMtE;AAED,mGAAmG;AACnG,qBAAa,iBAAkB,SAAQ,KAAK;IAExC,QAAQ,CAAC,MAAM,EAAE,WAAW;IAD9B,YACW,MAAM,EAAE,WAAW,EAC5B,OAAO,EAAE,MAAM,EAIhB;CACF"}
+{"version":3,"file":"quota-provider.d.ts","sourceRoot":"","sources":["../../../src/spi/quota-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,mDAAmD;AACnD,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,OAAO,CAAC;AAE1C,kFAAkF;AAClF,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,WAAW,CAAC;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wFAAwF;IACxF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,oDAAoD;AACpD,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,WAAW,CAAC;IACpB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,mFAAmF;AACnF,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,WAAW,CAAC;IACpB,yFAAyF;IACzF,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,uCAAuC;AACvC,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,mFAAmF;IACnF,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,KAAK,CAAC;IACb,kDAAkD;IAClD,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CACjD;AAED,yFAAyF;AACzF,wBAAgB,eAAe,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,UAAU,GAAG,SAAS,CAavF;AAED,oGAAoG;AACpG,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAajE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,YAAY,GAAG,SAAS,CAYtF;AAED,8FAA8F;AAC9F,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,WAAW,EACnB,GAAG,EAAE,IAAI,GACR;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAetD;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAMtE;AAED,mGAAmG;AACnG,qBAAa,iBAAkB,SAAQ,KAAK;IAExC,QAAQ,CAAC,MAAM,EAAE,WAAW;IAD9B,YACW,MAAM,EAAE,WAAW,EAC5B,OAAO,EAAE,MAAM,EAIhB;CACF"}

package/dist/src/spi/quota-provider.js

@@ -1,7 +1,7 @@
 /** The first window whose token or spend ceiling is reached, as a {@link QuotaBlock}. */
 export function exhaustedWindow(windows) {
     for (const window of windows) {
-        const tokensOut = window.limitTokens !== undefined && window.usedTokens >= window.limitTokens;
+        const tokensOut = window.limitTokens !== undefined && (window.usedTokens ?? 0) >= window.limitTokens;
         const spendOut = window.limitUsd !== undefined && window.usedUsd >= window.limitUsd;
         if (tokensOut || spendOut) {
             return {
@@ -12,6 +12,39 @@ export function exhaustedWindow(windows) {
     }
     return undefined;
 }
+/** How much of `window`'s ceilings is used, `0..1+` (the larger of spend and tokens), or `null`. */
+export function quotaUsedRatio(window) {
+    const ratios = [];
+    if (window.limitUsd !== undefined && window.limitUsd > 0) {
+        ratios.push(window.usedUsd / window.limitUsd);
+    }
+    if (window.limitTokens !== undefined &&
+        window.limitTokens > 0 &&
+        window.usedTokens !== undefined) {
+        ratios.push(window.usedTokens / window.limitTokens);
+    }
+    return ratios.length === 0 ? null : Math.max(...ratios);
+}
+/**
+ * The fullest window past its `warnAt`, as a {@link QuotaWarning} — `undefined` when none is, or
+ * when one is exhausted (that is `blocked`, not a warning).
+ */
+export function quotaWarning(windows) {
+    if (exhaustedWindow(windows) !== undefined)
+        return undefined;
+    let fullest;
+    for (const window of windows) {
+        if (window.warnAt === undefined)
+            continue;
+        const ratio = quotaUsedRatio(window);
+        if (ratio === null || ratio < window.warnAt)
+            continue;
+        if (fullest === undefined || ratio > fullest.ratio) {
+            fullest = { period: window.period, ratio };
+        }
+    }
+    return fullest;
+}
 /** The UTC day range (`YYYY-MM-DD`, inclusive) and reset instant of `period` around `now`. */
 export function quotaPeriodRange(period, now) {
     const year = now.getUTCFullYear();

package/dist/src/spi/quota-provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"quota-provider.js","sourceRoot":"","sources":["../../../src/spi/quota-provider.ts"],"names":[],"mappings":"AAmDA,yFAAyF;AACzF,MAAM,UAAU,eAAe,CAAC,OAA+B;IAC7D,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,SAAS,GAAG,MAAM,CAAC,WAAW,KAAK,SAAS,IAAI,MAAM,CAAC,UAAU,IAAI,MAAM,CAAC,WAAW,CAAC;QAC9F,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,KAAK,SAAS,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,QAAQ,CAAC;QACpF,IAAI,SAAS,IAAI,QAAQ,EAAE,CAAC;YAC1B,OAAO;gBACL,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,IAAI,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,gBAAgB;aACzG,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,gBAAgB,CAC9B,MAAmB,EACnB,GAAS;IAET,MAAM,IAAI,GAAG,GAAG,CAAC,cAAc,EAAE,CAAC;IAClC,MAAM,KAAK,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;IAChC,MAAM,GAAG,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC3C,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;QACrB,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;QACnE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;IACpE,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IACjD,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACpD,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;QACzC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;QACtC,QAAQ,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE;KAC/D,CAAC;AACJ,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,OAAQ,KAAuB,CAAC,MAAM,KAAK,UAAU,CACtD,CAAC;AACJ,CAAC;AAED,mGAAmG;AACnG,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAE/B,MAAM;IADjB,YACW,MAAmB,EAC5B,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;sBAHN,MAAM;QAIf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF"}
+{"version":3,"file":"quota-provider.js","sourceRoot":"","sources":["../../../src/spi/quota-provider.ts"],"names":[],"mappings":"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"}

package/dist/src/stores/ledger-quota-provider.d.ts

@@ -11,6 +11,14 @@ export interface QuotaLimits {
     day?: QuotaWindowLimits;
     month?: QuotaWindowLimits;
 }
+/** {@link LedgerQuotaProvider}'s tuning beyond the ceilings. */
+export interface LedgerQuotaOptions {
+    /**
+     * The soft limit: the share of a ceiling (`0..1`) past which the report carries a `warning`.
+     * Stamped on every window that has a ceiling. Omit → no warnings.
+     */
+    warnAt?: number;
+}
 /**
  * A {@link QuotaProvider} over the usage ledger: a day window (tokens from `quotaToday`, spend from
  * `usageBetween` when the store has it), and a month window when the store implements
@@ -24,7 +32,8 @@ export declare class LedgerQuotaProvider implements QuotaProvider {
     private readonly store;
     private readonly quota?;
     private readonly limits;
-    constructor(store: AgentStore, quota?: QuotaStore | undefined, limits?: QuotaLimits);
+    private readonly options;
+    constructor(store: AgentStore, quota?: QuotaStore | undefined, limits?: QuotaLimits, options?: LedgerQuotaOptions);
     report(query: QuotaQuery): Promise<QuotaReport>;
     private dayWindow;
     private window;

package/dist/src/stores/ledger-quota-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ledger-quota-provider.d.ts","sourceRoot":"","sources":["../../../src/stores/ledger-quota-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,WAAW,EAGjB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAExD,wDAAwD;AACxD,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,gEAAgE;AAChE,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,EAAE,iBAAiB,CAAC;IACxB,KAAK,CAAC,EAAE,iBAAiB,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,qBAAa,mBAAoB,YAAW,aAAa;IAErD,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAHzB,YACmB,KAAK,EAAE,UAAU,EACjB,KAAK,CAAC,EAAE,UAAU,YAAA,EAClB,MAAM,GAAE,WAAgB,EACvC;IAEE,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAWpD;YAEa,SAAS;IAavB,OAAO,CAAC,MAAM;CAgBf"}
+{"version":3,"file":"ledger-quota-provider.d.ts","sourceRoot":"","sources":["../../../src/stores/ledger-quota-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,WAAW,EAIjB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAExD,wDAAwD;AACxD,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,gEAAgE;AAChE,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,EAAE,iBAAiB,CAAC;IACxB,KAAK,CAAC,EAAE,iBAAiB,CAAC;CAC3B;AAED,gEAAgE;AAChE,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,qBAAa,mBAAoB,YAAW,aAAa;IAErD,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJ1B,YACmB,KAAK,EAAE,UAAU,EACjB,KAAK,CAAC,EAAE,UAAU,YAAA,EAClB,MAAM,GAAE,WAAgB,EACxB,OAAO,GAAE,kBAAuB,EAC/C;IAEE,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAgBpD;YAEa,SAAS;IAavB,OAAO,CAAC,MAAM;CAoBf"}

package/dist/src/stores/ledger-quota-provider.js

@@ -1,4 +1,4 @@
-import { exhaustedWindow, quotaPeriodRange, } from '../spi/quota-provider.js';
+import { exhaustedWindow, quotaPeriodRange, quotaWarning, } from '../spi/quota-provider.js';
 /**
  * A {@link QuotaProvider} over the usage ledger: a day window (tokens from `quotaToday`, spend from
  * `usageBetween` when the store has it), and a month window when the store implements
@@ -12,10 +12,12 @@ export class LedgerQuotaProvider {
     store;
     quota;
     limits;
-    constructor(store, quota, limits = {}) {
+    options;
+    constructor(store, quota, limits = {}, options = {}) {
         this.store = store;
         this.quota = quota;
         this.limits = limits;
+        this.options = options;
     }
     async report(query) {
         const now = query.now ?? new Date();
@@ -27,7 +29,12 @@ export class LedgerQuotaProvider {
             windows.push(this.window('month', used.usedTokens, used.costUsd, range.resetsAt));
         }
         const blocked = exhaustedWindow(windows);
-        return { windows, ...(blocked !== undefined ? { blocked } : {}) };
+        const warning = quotaWarning(windows);
+        return {
+            windows,
+            ...(blocked !== undefined ? { blocked } : {}),
+            ...(warning !== undefined ? { warning } : {}),
+        };
     }
     async dayWindow(actorRef, now) {
         const range = quotaPeriodRange('day', now);
@@ -49,6 +56,10 @@ export class LedgerQuotaProvider {
             usedUsd,
             ...(limits.usd !== undefined ? { limitUsd: limits.usd } : {}),
             resetsAt,
+            ...(this.options.warnAt !== undefined &&
+                (limits.tokens !== undefined || limits.usd !== undefined)
+                ? { warnAt: this.options.warnAt }
+                : {}),
         };
     }
 }

package/dist/src/stores/ledger-quota-provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"ledger-quota-provider.js","sourceRoot":"","sources":["../../../src/stores/ledger-quota-provider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ledger-quota-provider.js","sourceRoot":"","sources":["../../../src/stores/ledger-quota-provider.ts"],"names":[],"mappings":"AACA,OAAO,EACL,eAAe,EAMf,gBAAgB,EAChB,YAAY,GACb,MAAM,0BAA0B,CAAC;AAwBlC;;;;;;;;GAQG;AACH,MAAM,OAAO,mBAAmB;IAEX,KAAK;IACL,KAAK;IACL,MAAM;IACN,OAAO;IAJ1B,YACmB,KAAiB,EACjB,KAAkB,EAClB,MAAM,GAAgB,EAAE,EACxB,OAAO,GAAuB,EAAE;qBAHhC,KAAK;qBACL,KAAK;sBACL,MAAM;uBACN,OAAO;IACvB,CAAC;IAEJ,KAAK,CAAC,MAAM,CAAC,KAAiB;QAC5B,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;QACpC,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QAChC,MAAM,OAAO,GAAkB,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC;QACrE,IAAI,IAAI,CAAC,KAAK,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YAC1C,MAAM,KAAK,GAAG,gBAAgB,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;YAC7C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,QAAQ,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;YACjF,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;QACpF,CAAC;QACD,MAAM,OAAO,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;QACzC,MAAM,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;QACtC,OAAO;YACL,OAAO;YACP,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7C,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9C,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,SAAS,CAAC,QAAgB,EAAE,GAAS;QACjD,MAAM,KAAK,GAAG,gBAAgB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC3C,MAAM,IAAI,GACR,IAAI,CAAC,KAAK,CAAC,YAAY,KAAK,SAAS;YACnC,CAAC,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,QAAQ,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC;YACrE,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;QAChF,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;QACjF,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,MAAM,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YACjE,MAAM,CAAC,WAAW,GAAG,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC;QACrF,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAEO,MAAM,CACZ,MAAmB,EACnB,UAAkB,EAClB,OAAe,EACf,QAAgB;QAEhB,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QACzC,OAAO;YACL,MAAM;YACN,UAAU;YACV,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACtE,OAAO;YACP,GAAG,CAAC,MAAM,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7D,QAAQ;YACR,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS;gBACrC,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,GAAG,KAAK,SAAS,CAAC;gBACvD,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE;gBACjC,CAAC,CAAC,EAAE,CAAC;SACR,CAAC;IACJ,CAAC;CACF"}

package/dist/src/stores/lucid-schema.d.ts

@@ -1,6 +1,6 @@
 import type { LucidRawRunner } from './lucid.js';
 /**
- * The six agent table names. They match the cross-adapter snake_case contract the reference Drizzle
+ * The seven agent table names. They match the cross-adapter snake_case contract the reference Drizzle
  * store uses, so a dashboard or migration can point at any adapter and see the same physical schema.
  */
 export declare const AGENT_TABLES: {
@@ -10,9 +10,11 @@ export declare const AGENT_TABLES: {
     readonly tokenUsage: 'agent_token_usage';
     readonly modelPricing: 'agent_model_pricing';
     readonly runs: 'agent_run';
+    /** Messages sent while a turn was running, waiting to run after it (the chat queue). */
+    readonly queuedMessages: 'agent_queued_message';
 };
 /**
- * `CREATE TABLE IF NOT EXISTS` DDL for the six agent tables plus their indexes, one statement per
+ * `CREATE TABLE IF NOT EXISTS` DDL for the seven agent tables plus their indexes, one statement per
  * array element so each can be issued through Lucid's `rawQuery`. Portable across SQLite / Postgres /
  * MySQL: quoted identifiers, epoch-ms `BIGINT` timestamps, `INTEGER` booleans (0/1) and `TEXT` JSON
  * columns — no dialect-only types. A real deployment should prefer the bundled migration stub so the
@@ -29,7 +31,7 @@ export declare const AGENT_TABLES: {
  */
 export declare function createTableStatements(): string[];
 /**
- * Idempotently provision the six agent tables through Lucid's async raw runner (`CREATE TABLE IF
+ * Idempotently provision the seven agent tables through Lucid's async raw runner (`CREATE TABLE IF
  * NOT EXISTS`), then additively repair a database that predates run tracking by ALTERing in the
  * `run_id` columns its three older tables are missing.
  *
@@ -46,15 +48,15 @@ export declare function createTableStatements(): string[];
  */
 export declare function createAgentTables(db: LucidRawRunner): Promise<string[]>;
 /**
- * `DROP TABLE IF EXISTS` for the six agent tables, in reverse dependency order so a dialect that
+ * `DROP TABLE IF EXISTS` for the seven agent tables, in reverse dependency order so a dialect that
  * enforces the `REFERENCES` clauses never refuses a drop for a child that still exists. The mirror of
  * {@link createAgentTables}, and what the published migration's `down()` calls.
  */
 export declare function dropTableStatements(): string[];
-/** Drop the six agent tables. Destructive and irreversible — this erases every thread and every ledger row. */
+/** Drop the seven agent tables. Destructive and irreversible — this erases every thread and every ledger row. */
 export declare function dropAgentTables(db: LucidRawRunner): Promise<void>;
 /**
- * Idempotently ensure the six agent tables exist, memoized per db client. This is what the stores
+ * Idempotently ensure the seven agent tables exist, memoized per db client. This is what the stores
  * call on first use when `autoCreateTables` is on (the default) — whichever store touches the
  * connection first provisions the shared schema, so pricing seeds and governance reads work even
  * before the first agent run.

package/dist/src/stores/lucid-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lucid-schema.d.ts","sourceRoot":"","sources":["../../../src/stores/lucid-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,YAAY;aACvB,OAAO,EAAE,cAAc;aACvB,QAAQ,EAAE,eAAe;aACzB,SAAS,EAAE,iBAAiB;aAC5B,UAAU,EAAE,mBAAmB;aAC/B,YAAY,EAAE,qBAAqB;aACnC,IAAI,EAAE,WAAW;CACT,CAAC;AAEX;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CA6GhD;AAmDD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,iBAAiB,CAAC,EAAE,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA6B7E;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,EAAE,CAK9C;AAED,+GAA+G;AAC/G,wBAAsB,eAAe,CAAC,EAAE,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAIvE;AAWD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAanE"}
+{"version":3,"file":"lucid-schema.d.ts","sourceRoot":"","sources":["../../../src/stores/lucid-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,YAAY;aACvB,OAAO,EAAE,cAAc;aACvB,QAAQ,EAAE,eAAe;aACzB,SAAS,EAAE,iBAAiB;aAC5B,UAAU,EAAE,mBAAmB;aAC/B,YAAY,EAAE,qBAAqB;aACnC,IAAI,EAAE,WAAW;IACjB,wFAAwF;aACxF,cAAc,EAAE,sBAAsB;CAC9B,CAAC;AAEX;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CA6HhD;AAoDD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,iBAAiB,CAAC,EAAE,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA6B7E;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,EAAE,CAW9C;AAED,iHAAiH;AACjH,wBAAsB,eAAe,CAAC,EAAE,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAIvE;AAWD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAanE"}

package/dist/src/stores/lucid-schema.js

@@ -1,5 +1,5 @@
 /**
- * The six agent table names. They match the cross-adapter snake_case contract the reference Drizzle
+ * The seven agent table names. They match the cross-adapter snake_case contract the reference Drizzle
  * store uses, so a dashboard or migration can point at any adapter and see the same physical schema.
  */
 export const AGENT_TABLES = {
@@ -9,9 +9,11 @@ export const AGENT_TABLES = {
     tokenUsage: 'agent_token_usage',
     modelPricing: 'agent_model_pricing',
     runs: 'agent_run',
+    /** Messages sent while a turn was running, waiting to run after it (the chat queue). */
+    queuedMessages: 'agent_queued_message',
 };
 /**
- * `CREATE TABLE IF NOT EXISTS` DDL for the six agent tables plus their indexes, one statement per
+ * `CREATE TABLE IF NOT EXISTS` DDL for the seven agent tables plus their indexes, one statement per
  * array element so each can be issued through Lucid's `rawQuery`. Portable across SQLite / Postgres /
  * MySQL: quoted identifiers, epoch-ms `BIGINT` timestamps, `INTEGER` booleans (0/1) and `TEXT` JSON
  * columns — no dialect-only types. A real deployment should prefer the bundled migration stub so the
@@ -41,6 +43,7 @@ export function createTableStatements() {
       "summary_message_count" INTEGER NOT NULL DEFAULT 0,
       "active_stream_id" VARCHAR(255) NULL,
       "model" VARCHAR(255) NULL,
+      "queue_pause" TEXT NULL,
       "created_at" BIGINT NOT NULL,
       "updated_at" BIGINT NOT NULL,
       "deleted_at" BIGINT NULL
@@ -134,6 +137,21 @@ export function createTableStatements() {
         `CREATE INDEX IF NOT EXISTS "${t.runs}_started_idx" ON "${t.runs}" ("started_at")`,
         `CREATE INDEX IF NOT EXISTS "${t.runs}_actor_started_idx" ON "${t.runs}" ("actor_ref", "started_at")`,
         `CREATE INDEX IF NOT EXISTS "${t.runs}_status_started_idx" ON "${t.runs}" ("status", "started_at")`,
+        `CREATE TABLE IF NOT EXISTS "${t.queuedMessages}" (
+      "id" VARCHAR(255) PRIMARY KEY NOT NULL,
+      "thread_id" VARCHAR(255) NOT NULL REFERENCES "${t.threads}" ("id") ON DELETE CASCADE,
+      "actor" TEXT NOT NULL,
+      "content" TEXT NOT NULL,
+      "attachments" TEXT NULL,
+      "agent_name" VARCHAR(255) NULL,
+      "model" VARCHAR(255) NULL,
+      "page_context" TEXT NULL,
+      "interrupt" INTEGER NOT NULL DEFAULT 0,
+      "position" INTEGER NOT NULL,
+      "created_at" BIGINT NOT NULL,
+      "updated_at" BIGINT NOT NULL
+    )`,
+        `CREATE INDEX IF NOT EXISTS "${t.queuedMessages}_thread_position_idx" ON "${t.queuedMessages}" ("thread_id", "position")`,
     ];
 }
 /**
@@ -160,6 +178,7 @@ const ADDITIVE_COLUMNS = [
     { table: AGENT_TABLES.messages, column: 'ui', type: 'TEXT NULL' },
     { table: AGENT_TABLES.messages, column: 'feedback', type: 'TEXT NULL' },
     { table: AGENT_TABLES.threads, column: 'model', type: 'VARCHAR(255) NULL' },
+    { table: AGENT_TABLES.threads, column: 'queue_pause', type: 'TEXT NULL' },
     { table: AGENT_TABLES.toolCalls, column: 'approver', type: 'VARCHAR(255) NULL' },
     { table: AGENT_TABLES.toolCalls, column: 'expires_at', type: 'BIGINT NULL' },
     { table: AGENT_TABLES.toolCalls, column: 'remember', type: 'INTEGER NULL' },
@@ -184,7 +203,7 @@ async function hasColumn(db, table, column) {
     }
 }
 /**
- * Idempotently provision the six agent tables through Lucid's async raw runner (`CREATE TABLE IF
+ * Idempotently provision the seven agent tables through Lucid's async raw runner (`CREATE TABLE IF
  * NOT EXISTS`), then additively repair a database that predates run tracking by ALTERing in the
  * `run_id` columns its three older tables are missing.
  *
@@ -230,15 +249,23 @@ export async function createAgentTables(db) {
     return repairs;
 }
 /**
- * `DROP TABLE IF EXISTS` for the six agent tables, in reverse dependency order so a dialect that
+ * `DROP TABLE IF EXISTS` for the seven agent tables, in reverse dependency order so a dialect that
  * enforces the `REFERENCES` clauses never refuses a drop for a child that still exists. The mirror of
  * {@link createAgentTables}, and what the published migration's `down()` calls.
  */
 export function dropTableStatements() {
     const t = AGENT_TABLES;
-    return [t.runs, t.tokenUsage, t.toolCalls, t.messages, t.modelPricing, t.threads].map((table) => `DROP TABLE IF EXISTS "${table}"`);
+    return [
+        t.queuedMessages,
+        t.runs,
+        t.tokenUsage,
+        t.toolCalls,
+        t.messages,
+        t.modelPricing,
+        t.threads,
+    ].map((table) => `DROP TABLE IF EXISTS "${table}"`);
 }
-/** Drop the six agent tables. Destructive and irreversible — this erases every thread and every ledger row. */
+/** Drop the seven agent tables. Destructive and irreversible — this erases every thread and every ledger row. */
 export async function dropAgentTables(db) {
     for (const stmt of dropTableStatements()) {
         await db.rawQuery(stmt);
@@ -253,7 +280,7 @@ export async function dropAgentTables(db) {
  */
 const provisioned = new WeakMap();
 /**
- * Idempotently ensure the six agent tables exist, memoized per db client. This is what the stores
+ * Idempotently ensure the seven agent tables exist, memoized per db client. This is what the stores
  * call on first use when `autoCreateTables` is on (the default) — whichever store touches the
  * connection first provisions the shared schema, so pricing seeds and governance reads work even
  * before the first agent run.