@kortix/sdk 0.12.2 → 0.12.4

package/dist/core/session/message-queue.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The rules a message queue obeys, as pure functions.
+ *
+ * A message typed while the agent is mid-run is held until the turn ends. That
+ * much is easy. What is not easy — and what three previous implementations got
+ * wrong — is *when* it is released and *how many times*.
+ *
+ * The failures this module exists to make impossible:
+ *
+ *   - **Two drains, one message sent twice.** `claimNext` records the claim in
+ *     the same transition that returns the item. A second claim against the
+ *     returned state gets nothing. There is no ref to read stale, no effect
+ *     ordering to reason about, no window between deciding to send and having
+ *     said so.
+ *   - **A failed head locking out every later send.** `failInFlight` moves the
+ *     item to `failed` and leaves `pending` immediately drainable. This is the
+ *     exact lockout that caused the client queue to be deleted wholesale in
+ *     `67749c1f76`; it cannot recur here.
+ *   - **A queued message sending under the wrong model.** `agent`, `model`, and
+ *     `variant` are captured at enqueue and carried verbatim.
+ *
+ * The claimed item stays at `pending[0]` while it is in flight rather than
+ * being spliced out. That makes `inFlightId` a real lock (one field to check),
+ * makes "reorder cannot cross the in-flight slot" an index clamp rather than a
+ * special case, and means a crash between claim and dispatch leaves the message
+ * visible in the queue instead of silently gone.
+ *
+ * Framework-free, storage-free, and timer-free by construction. There is no
+ * `Date.now()` and no `crypto` here: ids and timestamps are inputs, so every
+ * transition is deterministic and testable without fakes. Persistence and the
+ * decision of *when* the turn ended belong to the host.
+ */
+/** What a host hands in when the user queues a message. */
+export interface QueuedMessageInput<TFile = unknown, TMention = unknown> {
+    /** Queue-local id. Client-only; never sent to the server. */
+    id: string;
+    /**
+     * Stable across retries, so a host can key an optimistic message — and a
+     * server that grows idempotency — off one value.
+     */
+    clientMessageId: string;
+    text: string;
+    files?: TFile[];
+    mentions?: TMention[];
+    /** Captured at enqueue so a later model switch cannot rewrite this send. */
+    agent?: string | null;
+    model?: {
+        providerID: string;
+        modelID: string;
+    } | null;
+    variant?: string | null;
+    createdAt: number;
+}
+/** A queued message, once the queue owns it. */
+export interface QueuedMessage<TFile = unknown, TMention = unknown> extends QueuedMessageInput<TFile, TMention> {
+    /** Dispatch attempts so far. Incremented by `claimNext`. */
+    attempts: number;
+    /** Why the last attempt failed. Cleared on retry. */
+    lastError?: string;
+}
+/** One session's queue. */
+export interface SessionQueue<TFile = unknown, TMention = unknown> {
+    /** Waiting to send, oldest first. `pending[0]` is in flight when claimed. */
+    pending: QueuedMessage<TFile, TMention>[];
+    /** Gave up. Never blocks `pending`; a host offers these a retry. */
+    failed: QueuedMessage<TFile, TMention>[];
+    /** The id of the item currently on the wire, or null. This is the lock. */
+    inFlightId: string | null;
+}
+export declare function createSessionQueue<TFile = unknown, TMention = unknown>(): SessionQueue<TFile, TMention>;
+/**
+ * Add a message to the tail.
+ *
+ * Always the tail — never the head, even while something is in flight and even
+ * if the session happens to read idle this instant. Jumping the line is what
+ * "Stop & send" is for, and that is an explicit user action, not a side effect
+ * of timing.
+ */
+export declare function enqueue<TFile, TMention>(state: SessionQueue<TFile, TMention>, input: QueuedMessageInput<TFile, TMention>): SessionQueue<TFile, TMention>;
+/**
+ * Take the head for dispatch, and record the claim in the same transition.
+ *
+ * Returns `claimed: undefined` when the queue is empty or something is already
+ * in flight — so a caller that races itself sends once, not twice.
+ */
+export declare function claimNext<TFile, TMention>(state: SessionQueue<TFile, TMention>): {
+    state: SessionQueue<TFile, TMention>;
+    claimed?: QueuedMessage<TFile, TMention>;
+};
+/** The send landed. Drop the item and free the queue. */
+export declare function completeInFlight<TFile, TMention>(state: SessionQueue<TFile, TMention>): SessionQueue<TFile, TMention>;
+/**
+ * The send failed for good. Set it aside — do not put it back at the head.
+ *
+ * Requeueing a failure at the head is how the queue used to wedge, and it is
+ * also how a prompt the server already accepted gets sent a second time. The
+ * item lands in `failed` with its reason, and `pending` keeps moving.
+ */
+export declare function failInFlight<TFile, TMention>(state: SessionQueue<TFile, TMention>, error: string): SessionQueue<TFile, TMention>;
+/** Put a failed item back at the tail, with its error cleared. */
+export declare function retryFailed<TFile, TMention>(state: SessionQueue<TFile, TMention>, id: string): SessionQueue<TFile, TMention>;
+/** Drop a message. Refuses the in-flight item — it is already on the wire. */
+export declare function removeQueued<TFile, TMention>(state: SessionQueue<TFile, TMention>, id: string): SessionQueue<TFile, TMention>;
+/** Rewrite a queued message. Refuses the in-flight item. */
+export declare function editQueued<TFile, TMention>(state: SessionQueue<TFile, TMention>, id: string, text: string): SessionQueue<TFile, TMention>;
+/**
+ * Move a pending message to `toIndex`.
+ *
+ * `toIndex` is clamped to the movable range. While something is in flight that
+ * range starts at 1, so nothing can be reordered into or past the slot that is
+ * already sending — and the in-flight item itself cannot move at all.
+ */
+export declare function reorderQueued<TFile, TMention>(state: SessionQueue<TFile, TMention>, id: string, toIndex: number): SessionQueue<TFile, TMention>;
+//# sourceMappingURL=message-queue.d.ts.map

package/dist/core/session/message-queue.d.ts.map

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

package/dist/core/session/message-queue.js

@@ -0,0 +1,155 @@
+/**
+ * The rules a message queue obeys, as pure functions.
+ *
+ * A message typed while the agent is mid-run is held until the turn ends. That
+ * much is easy. What is not easy — and what three previous implementations got
+ * wrong — is *when* it is released and *how many times*.
+ *
+ * The failures this module exists to make impossible:
+ *
+ *   - **Two drains, one message sent twice.** `claimNext` records the claim in
+ *     the same transition that returns the item. A second claim against the
+ *     returned state gets nothing. There is no ref to read stale, no effect
+ *     ordering to reason about, no window between deciding to send and having
+ *     said so.
+ *   - **A failed head locking out every later send.** `failInFlight` moves the
+ *     item to `failed` and leaves `pending` immediately drainable. This is the
+ *     exact lockout that caused the client queue to be deleted wholesale in
+ *     `67749c1f76`; it cannot recur here.
+ *   - **A queued message sending under the wrong model.** `agent`, `model`, and
+ *     `variant` are captured at enqueue and carried verbatim.
+ *
+ * The claimed item stays at `pending[0]` while it is in flight rather than
+ * being spliced out. That makes `inFlightId` a real lock (one field to check),
+ * makes "reorder cannot cross the in-flight slot" an index clamp rather than a
+ * special case, and means a crash between claim and dispatch leaves the message
+ * visible in the queue instead of silently gone.
+ *
+ * Framework-free, storage-free, and timer-free by construction. There is no
+ * `Date.now()` and no `crypto` here: ids and timestamps are inputs, so every
+ * transition is deterministic and testable without fakes. Persistence and the
+ * decision of *when* the turn ended belong to the host.
+ */
+export function createSessionQueue() {
+    return { pending: [], failed: [], inFlightId: null };
+}
+/**
+ * Add a message to the tail.
+ *
+ * Always the tail — never the head, even while something is in flight and even
+ * if the session happens to read idle this instant. Jumping the line is what
+ * "Stop & send" is for, and that is an explicit user action, not a side effect
+ * of timing.
+ */
+export function enqueue(state, input) {
+    return { ...state, pending: [...state.pending, { ...input, attempts: 0 }] };
+}
+/**
+ * Take the head for dispatch, and record the claim in the same transition.
+ *
+ * Returns `claimed: undefined` when the queue is empty or something is already
+ * in flight — so a caller that races itself sends once, not twice.
+ */
+export function claimNext(state) {
+    if (state.inFlightId !== null)
+        return { state };
+    const head = state.pending[0];
+    if (!head)
+        return { state };
+    const claimed = { ...head, attempts: head.attempts + 1 };
+    return {
+        state: {
+            ...state,
+            pending: [claimed, ...state.pending.slice(1)],
+            inFlightId: claimed.id,
+        },
+        claimed,
+    };
+}
+/** The send landed. Drop the item and free the queue. */
+export function completeInFlight(state) {
+    if (state.inFlightId === null)
+        return state;
+    return {
+        ...state,
+        pending: state.pending.filter((m) => m.id !== state.inFlightId),
+        inFlightId: null,
+    };
+}
+/**
+ * The send failed for good. Set it aside — do not put it back at the head.
+ *
+ * Requeueing a failure at the head is how the queue used to wedge, and it is
+ * also how a prompt the server already accepted gets sent a second time. The
+ * item lands in `failed` with its reason, and `pending` keeps moving.
+ */
+export function failInFlight(state, error) {
+    if (state.inFlightId === null)
+        return state;
+    const item = state.pending.find((m) => m.id === state.inFlightId);
+    if (!item)
+        return { ...state, inFlightId: null };
+    return {
+        pending: state.pending.filter((m) => m.id !== state.inFlightId),
+        failed: [...state.failed, { ...item, lastError: error }],
+        inFlightId: null,
+    };
+}
+/** Put a failed item back at the tail, with its error cleared. */
+export function retryFailed(state, id) {
+    const item = state.failed.find((m) => m.id === id);
+    if (!item)
+        return state;
+    const { lastError: _dropped, ...rest } = item;
+    return {
+        ...state,
+        pending: [...state.pending, rest],
+        failed: state.failed.filter((m) => m.id !== id),
+    };
+}
+/** Drop a message. Refuses the in-flight item — it is already on the wire. */
+export function removeQueued(state, id) {
+    if (id === state.inFlightId)
+        return state;
+    if (state.pending.some((m) => m.id === id)) {
+        return { ...state, pending: state.pending.filter((m) => m.id !== id) };
+    }
+    if (state.failed.some((m) => m.id === id)) {
+        return { ...state, failed: state.failed.filter((m) => m.id !== id) };
+    }
+    return state;
+}
+/** Rewrite a queued message. Refuses the in-flight item. */
+export function editQueued(state, id, text) {
+    if (id === state.inFlightId)
+        return state;
+    if (!state.pending.some((m) => m.id === id))
+        return state;
+    return {
+        ...state,
+        pending: state.pending.map((m) => (m.id === id ? { ...m, text } : m)),
+    };
+}
+/**
+ * Move a pending message to `toIndex`.
+ *
+ * `toIndex` is clamped to the movable range. While something is in flight that
+ * range starts at 1, so nothing can be reordered into or past the slot that is
+ * already sending — and the in-flight item itself cannot move at all.
+ */
+export function reorderQueued(state, id, toIndex) {
+    if (id === state.inFlightId)
+        return state;
+    const from = state.pending.findIndex((m) => m.id === id);
+    if (from === -1)
+        return state;
+    const first = state.inFlightId === null ? 0 : 1;
+    const to = Math.min(Math.max(toIndex, first), state.pending.length - 1);
+    if (to === from)
+        return state;
+    const pending = [...state.pending];
+    const [moved] = pending.splice(from, 1);
+    pending.splice(to, 0, moved);
+    return { ...state, pending };
+}
+//# sourceMappingURL=message-queue.js.map

package/dist/core/session/message-queue.js.map

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

package/dist/core/session/send-queue.d.ts

@@ -0,0 +1,70 @@
+/**
+ * One prompt at a time, in the order they were written.
+ *
+ * Sending while the agent is mid-run used to be fire-and-hope: the prompt went
+ * out immediately and whatever the runtime did with it was invisible. The
+ * reported symptom was "sending also without upload feels janky while agent is
+ * working" — nothing on screen distinguished "waiting its turn" from "lost".
+ *
+ * This holds a prompt until the session is idle, then dispatches it. Ordering
+ * is guaranteed HERE rather than assumed of the server, which matters because
+ * the endpoint Kortix currently uses (`/session/{id}/prompt_async`) makes no
+ * documented promise about what happens to a prompt that arrives mid-run. The
+ * runtime does have a durable native queue (`delivery: 'queue'` on the v2
+ * `/api/session/{id}/prompt` route, with `session.next.prompt.admitted` to
+ * confirm promotion) — moving to it is the better long-term answer and is
+ * tracked separately. Until then the queue lives here, with the one honest
+ * caveat that a queue in a tab dies with the tab.
+ *
+ * Framework-free and timer-free: `isBusy` is injected and draining is driven by
+ * the caller telling it the session went idle. Nothing here polls.
+ *
+ * **Superseded for host use by `./message-queue`.** This module owns dispatch
+ * (it holds closures and calls them), which is exactly what a host cannot
+ * persist, reorder, or edit — a `dispatch` closure does not survive a page
+ * reload. `message-queue.ts` keeps the same one-at-a-time and never-jump-the-
+ * line guarantees but expresses them as pure transitions over serializable
+ * data, so the queue can be stored, reordered, and rewritten by the user.
+ *
+ * This module stays exported and tested: it is published API. New host code
+ * should reach for `message-queue` instead.
+ */
+/** Where a queued send has got to. Drives the label on the user's bubble. */
+export type SendPhase = 'queued' | 'sending' | 'sent' | 'failed';
+export interface QueuedSend {
+    /** The optimistic message this send belongs to. */
+    messageId: string;
+    /** Actually put it on the wire. Rejects on failure. */
+    dispatch: () => Promise<void>;
+}
+export interface SendQueueOptions {
+    /** Is the session mid-run right now? */
+    isBusy: (sessionId: string) => boolean;
+    /** Report a phase change so a host can render it. */
+    onPhase?: (sessionId: string, messageId: string, phase: SendPhase) => void;
+}
+export interface SendQueue {
+    /**
+     * Send now if the session is idle, otherwise hold it.
+     *
+     * Returns the phase the message entered, so a caller can render without
+     * waiting for the `onPhase` callback to come back around.
+     */
+    submit: (sessionId: string, item: QueuedSend) => 'queued' | 'sending';
+    /**
+     * The session finished a run. Dispatch the next held prompt, if any.
+     *
+     * Called by whatever observes session status — deliberately not a poll, and
+     * deliberately not a subscription this module owns, so it stays framework-
+     * free and testable without fake timers.
+     */
+    drain: (sessionId: string) => void;
+    /** Abandon a specific held send (the user discarded it). */
+    cancel: (sessionId: string, messageId: string) => boolean;
+    /** Abandon everything held for a session (it closed, or was cleared). */
+    clear: (sessionId: string) => void;
+    /** Message ids still waiting, oldest first. */
+    pending: (sessionId: string) => string[];
+}
+export declare function createSendQueue(options: SendQueueOptions): SendQueue;
+//# sourceMappingURL=send-queue.d.ts.map

package/dist/core/session/send-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"send-queue.d.ts","sourceRoot":"","sources":["../../../src/core/session/send-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,6EAA6E;AAC7E,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEjE,MAAM,WAAW,UAAU;IACzB,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC;IACvC,qDAAqD;IACrD,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;CAC5E;AAED,MAAM,WAAW,SAAS;IACxB;;;;;OAKG;IACH,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,KAAK,QAAQ,GAAG,SAAS,CAAC;IACtE;;;;;;OAMG;IACH,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,4DAA4D;IAC5D,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC;IAC1D,yEAAyE;IACzE,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,+CAA+C;IAC/C,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC;CAC1C;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CAgFpE"}

package/dist/core/session/send-queue.js

@@ -0,0 +1,116 @@
+/**
+ * One prompt at a time, in the order they were written.
+ *
+ * Sending while the agent is mid-run used to be fire-and-hope: the prompt went
+ * out immediately and whatever the runtime did with it was invisible. The
+ * reported symptom was "sending also without upload feels janky while agent is
+ * working" — nothing on screen distinguished "waiting its turn" from "lost".
+ *
+ * This holds a prompt until the session is idle, then dispatches it. Ordering
+ * is guaranteed HERE rather than assumed of the server, which matters because
+ * the endpoint Kortix currently uses (`/session/{id}/prompt_async`) makes no
+ * documented promise about what happens to a prompt that arrives mid-run. The
+ * runtime does have a durable native queue (`delivery: 'queue'` on the v2
+ * `/api/session/{id}/prompt` route, with `session.next.prompt.admitted` to
+ * confirm promotion) — moving to it is the better long-term answer and is
+ * tracked separately. Until then the queue lives here, with the one honest
+ * caveat that a queue in a tab dies with the tab.
+ *
+ * Framework-free and timer-free: `isBusy` is injected and draining is driven by
+ * the caller telling it the session went idle. Nothing here polls.
+ *
+ * **Superseded for host use by `./message-queue`.** This module owns dispatch
+ * (it holds closures and calls them), which is exactly what a host cannot
+ * persist, reorder, or edit — a `dispatch` closure does not survive a page
+ * reload. `message-queue.ts` keeps the same one-at-a-time and never-jump-the-
+ * line guarantees but expresses them as pure transitions over serializable
+ * data, so the queue can be stored, reordered, and rewritten by the user.
+ *
+ * This module stays exported and tested: it is published API. New host code
+ * should reach for `message-queue` instead.
+ */
+export function createSendQueue(options) {
+    const { isBusy, onPhase } = options;
+    const queues = new Map();
+    /** Sessions with a dispatch in flight, so `drain` never doubles up. */
+    const inFlight = new Set();
+    const phase = (sessionId, messageId, next) => {
+        onPhase?.(sessionId, messageId, next);
+    };
+    const run = (sessionId, item) => {
+        inFlight.add(sessionId);
+        phase(sessionId, item.messageId, 'sending');
+        void item
+            .dispatch()
+            .then(() => {
+            phase(sessionId, item.messageId, 'sent');
+        })
+            .catch(() => {
+            // A failed send must not wedge everything written after it. The
+            // message keeps its own `failed` phase (the host offers a retry);
+            // the queue moves on.
+            phase(sessionId, item.messageId, 'failed');
+        })
+            .finally(() => {
+            inFlight.delete(sessionId);
+            // The run this send started has not begun yet — `drain` is driven by
+            // the session going idle, and it is about to go busy. Only pull the
+            // next item if the session never became busy at all (e.g. the send
+            // failed outright), otherwise the idle transition will do it.
+            if (!isBusy(sessionId))
+                drain(sessionId);
+        });
+    };
+    const drain = (sessionId) => {
+        if (inFlight.has(sessionId))
+            return;
+        if (isBusy(sessionId))
+            return;
+        const queue = queues.get(sessionId);
+        if (!queue || queue.length === 0)
+            return;
+        const next = queue.shift();
+        if (queue.length === 0)
+            queues.delete(sessionId);
+        if (next)
+            run(sessionId, next);
+    };
+    return {
+        submit: (sessionId, item) => {
+            if (!isBusy(sessionId) && !inFlight.has(sessionId)) {
+                const queue = queues.get(sessionId);
+                // Never jump the line: if anything is already waiting, this one waits
+                // behind it even though the session happens to be idle this instant.
+                if (!queue || queue.length === 0) {
+                    run(sessionId, item);
+                    return 'sending';
+                }
+            }
+            const queue = queues.get(sessionId);
+            if (queue)
+                queue.push(item);
+            else
+                queues.set(sessionId, [item]);
+            phase(sessionId, item.messageId, 'queued');
+            return 'queued';
+        },
+        drain,
+        cancel: (sessionId, messageId) => {
+            const queue = queues.get(sessionId);
+            if (!queue)
+                return false;
+            const index = queue.findIndex((q) => q.messageId === messageId);
+            if (index === -1)
+                return false;
+            queue.splice(index, 1);
+            if (queue.length === 0)
+                queues.delete(sessionId);
+            return true;
+        },
+        clear: (sessionId) => {
+            queues.delete(sessionId);
+        },
+        pending: (sessionId) => (queues.get(sessionId) ?? []).map((q) => q.messageId),
+    };
+}
+//# sourceMappingURL=send-queue.js.map

package/dist/core/session/send-queue.js.map

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