@data-club/ai-hub-server 0.0.1

package/dist/state/rotationRunner.js

@@ -0,0 +1,246 @@
+/**
+ * Rotation runner for **rotating starting messages**.
+ *
+ * One rotation turns a configured prompt into a fresh, forkable "prepared
+ * conversation" (see `rotating_message` in `db/schema.ts`):
+ *
+ *   1. `createConversation(letta_agent_id)` — a clean conversation.
+ *   2. Send `prompt` via the normal streaming path, drained to the terminal
+ *      `result`. Reuses `streamUserMessage`, so the rotation inherits the same
+ *      subprocess throttle + toolset-none suppression + model routing as a
+ *      real chat turn.
+ *   3. Find the prompt's `user_message` in the resulting history and delete it,
+ *      so the conversation opens with the agent's reply.
+ *   4. Persist the new conversation id as `current_conversation_id`.
+ *
+ * **Resilience.** Any failure leaves `current_conversation_id` at its last-good
+ * value (sessions keep forking the previous good conversation), records
+ * `last_status = 'error'` + `last_error`, and still advances `next_rotation_at`
+ * so the next interval retries rather than the tick hammering a broken agent.
+ *
+ * `computeNextRotation` / `validateScheduleFields` are pure and unit-tested
+ * independently of any Letta interaction.
+ *
+ * @see docs/server/rotating-messages.md
+ */
+import { eq } from "drizzle-orm";
+import { rotatingMessage } from "../db/schema.js";
+import { CronParseError, cronNextRun, parseCron } from "./cron.js";
+/** Smallest allowed `every`-interval (guards against hammering Letta). */
+export const MIN_INTERVAL_SECONDS = 60;
+/** Largest allowed `every`-interval (366 days). */
+export const MAX_INTERVAL_SECONDS = 366 * 24 * 3600;
+/** `"HH:MM"` 24-hour validator for the `daily` preset (UTC). */
+const DAILY_TIME_RE = /^([01]\d|2[0-3]):([0-5]\d)$/;
+/**
+ * Validates a schedule config (used by the admin create/patch handlers).
+ * Pure — the only "work" is parsing cron, which throws `CronParseError` on
+ * malformed input.
+ *
+ * @param s - the schedule fields to validate.
+ * @returns `{ ok: true }` or `{ ok: false, message }`.
+ */
+export function validateScheduleFields(s) {
+    switch (s.scheduleKind) {
+        case "every": {
+            if (s.intervalSeconds === null ||
+                !Number.isInteger(s.intervalSeconds) ||
+                s.intervalSeconds < MIN_INTERVAL_SECONDS ||
+                s.intervalSeconds > MAX_INTERVAL_SECONDS) {
+                return {
+                    ok: false,
+                    message: `interval_seconds must be an integer between ${MIN_INTERVAL_SECONDS} and ${MAX_INTERVAL_SECONDS}.`,
+                };
+            }
+            return { ok: true };
+        }
+        case "daily": {
+            if (!s.dailyTime || !DAILY_TIME_RE.test(s.dailyTime)) {
+                return { ok: false, message: 'daily_time must be "HH:MM" (24-hour, UTC).' };
+            }
+            return { ok: true };
+        }
+        case "cron": {
+            if (!s.cronExpression || s.cronExpression.trim() === "") {
+                return { ok: false, message: "cron_expression is required for schedule_kind 'cron'." };
+            }
+            try {
+                parseCron(s.cronExpression);
+            }
+            catch (err) {
+                return {
+                    ok: false,
+                    message: err instanceof CronParseError ? err.message : "Invalid cron expression.",
+                };
+            }
+            return { ok: true };
+        }
+    }
+}
+/**
+ * Computes the next rotation instant (UTC ISO-8601) strictly after `from`.
+ *
+ * Assumes the schedule already passed `validateScheduleFields`. `daily` and
+ * `cron` are evaluated in UTC (see `cron.ts`).
+ *
+ * @param s - the schedule fields.
+ * @param from - the reference instant.
+ * @returns the next rotation time as a UTC ISO string.
+ */
+export function computeNextRotation(s, from) {
+    switch (s.scheduleKind) {
+        case "every": {
+            const secs = s.intervalSeconds ?? MIN_INTERVAL_SECONDS;
+            return new Date(from.getTime() + secs * 1000).toISOString();
+        }
+        case "daily": {
+            const [hh, mm] = (s.dailyTime ?? "00:00").split(":").map(Number);
+            const next = new Date(from.getTime());
+            next.setUTCHours(hh, mm, 0, 0);
+            if (next.getTime() <= from.getTime()) {
+                next.setUTCDate(next.getUTCDate() + 1);
+            }
+            return next.toISOString();
+        }
+        case "cron":
+            return cronNextRun(s.cronExpression ?? "* * * * *", from);
+    }
+}
+/** `computeNextRotation` that never throws — falls back to +1h on a poison row. */
+function safeComputeNextRotation(s, from, logger) {
+    try {
+        return computeNextRotation(s, from);
+    }
+    catch (err) {
+        logger.error({ err: err instanceof Error ? err.message : String(err), event: "rotation_next_compute_failed" }, "Failed to compute next rotation time; falling back to +1h.");
+        return new Date(from.getTime() + 3600 * 1000).toISOString();
+    }
+}
+/**
+ * Runs one rotation for `row` and persists the result. Never throws — the
+ * outcome is reported via the return value and the row's `last_status`.
+ *
+ * @param deps - db + Letta client + logger.
+ * @param row - the rotating-message row to rotate.
+ * @returns the rotation outcome.
+ */
+export async function runRotation(deps, row) {
+    const now = (deps.now ?? (() => new Date()))();
+    const nowIso = now.toISOString();
+    const nextRotationAt = safeComputeNextRotation(row, now, deps.logger);
+    const previousConversationId = row.currentConversationId;
+    let createdConversationId = null;
+    try {
+        const conv = await deps.lettaClient.createConversation(row.lettaAgentId);
+        createdConversationId = conv.id;
+        await sendPromptAndDrain(deps.lettaClient, conv.id, row.lettaAgentId, row.prompt);
+        // Delete the prompt's user message so the conversation opens with the
+        // agent's reply. listMessages is oldest-first; the first user_message is
+        // the prompt we just sent.
+        const messages = await deps.lettaClient.listMessages(conv.id);
+        const firstUser = messages.find((m) => m.message_type === "user_message");
+        if (firstUser?.id) {
+            await deps.lettaClient.deleteMessage(row.lettaAgentId, firstUser.id);
+        }
+        else {
+            deps.logger.warn({ rotating_message_id: row.id, conversation_id: conv.id, event: "rotation_no_user_message" }, "Rotation produced no user_message to delete; storing conversation as-is.");
+        }
+        deps.db
+            .update(rotatingMessage)
+            .set({
+            currentConversationId: conv.id,
+            lastStatus: "ok",
+            lastError: null,
+            lastRotatedAt: nowIso,
+            nextRotationAt,
+            updatedAt: nowIso,
+        })
+            .where(eq(rotatingMessage.id, row.id))
+            .run();
+        // Best-effort cleanup of the now-superseded conversation.
+        if (previousConversationId && previousConversationId !== conv.id) {
+            try {
+                await deps.lettaClient.deleteConversation(previousConversationId);
+            }
+            catch (err) {
+                deps.logger.warn({
+                    rotating_message_id: row.id,
+                    conversation_id: previousConversationId,
+                    err: err instanceof Error ? err.message : String(err),
+                    event: "rotation_previous_cleanup_failed",
+                }, "Failed to delete the previous prepared conversation; leaving it orphaned.");
+            }
+        }
+        deps.logger.info({
+            rotating_message_id: row.id,
+            letta_agent_id: row.lettaAgentId,
+            conversation_id: conv.id,
+            next_rotation_at: nextRotationAt,
+            event: "rotation_ok",
+        }, "Rotating starting message refreshed.");
+        return { status: "ok", conversationId: conv.id };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        // Best-effort drop of the half-built conversation so failures don't
+        // accumulate orphans. The last-good current_conversation_id is untouched.
+        if (createdConversationId) {
+            try {
+                await deps.lettaClient.deleteConversation(createdConversationId);
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+        deps.db
+            .update(rotatingMessage)
+            .set({
+            lastStatus: "error",
+            lastError: message,
+            nextRotationAt,
+            updatedAt: nowIso,
+        })
+            .where(eq(rotatingMessage.id, row.id))
+            .run();
+        deps.logger.error({
+            rotating_message_id: row.id,
+            letta_agent_id: row.lettaAgentId,
+            err: message,
+            next_rotation_at: nextRotationAt,
+            event: "rotation_error",
+        }, "Rotation failed; keeping the previous prepared conversation.");
+        return { status: "error", error: message };
+    }
+}
+/**
+ * Sends `prompt` to `conversationId` and drains the stream to its terminal
+ * `result`. Throws when the run produced no terminal result or finished
+ * unsuccessfully. Always tears the subprocess down via `handle.close()`.
+ */
+async function sendPromptAndDrain(client, conversationId, lettaAgentId, prompt) {
+    const handle = await client.streamUserMessage({
+        conversationId,
+        lettaAgentId,
+        userMessage: prompt,
+    });
+    let sawResult = false;
+    let success = false;
+    try {
+        for await (const msg of handle.events) {
+            if (msg.type === "result") {
+                sawResult = true;
+                success = msg.success;
+            }
+        }
+    }
+    finally {
+        handle.close();
+    }
+    if (!sawResult) {
+        throw new Error("Agent run produced no terminal result.");
+    }
+    if (!success) {
+        throw new Error("Agent run did not complete successfully.");
+    }
+}
+//# sourceMappingURL=rotationRunner.js.map

package/dist/state/rotationRunner.js.map

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

package/dist/state/rotationScheduler.d.ts

@@ -0,0 +1,76 @@
+/**
+ * In-process scheduler for **rotating starting messages**.
+ *
+ * ai-hub deploys as one long-running Node process (in-process
+ * `better-sqlite3` + self-hosted Letta), so a simple tick loop is the right
+ * tool — no external cron, queue, or multi-instance coordination needed.
+ *
+ * Each tick selects non-archived `rotating_message` rows whose
+ * `next_rotation_at <= now` and runs them **serially** through `runRotation`.
+ * An in-memory `inFlight` set prevents a slow rotation from being re-picked by
+ * the next tick. `runRotation` advances `next_rotation_at` itself, so a row is
+ * naturally not due again until its interval elapses.
+ *
+ * The scheduler is started once per process from `createFetchHandler`
+ * (`ensureRotationScheduler`) — that's the single construction point both the
+ * dev `node:http` runner and the Next.js wrapper go through. It is **skipped
+ * under tests** (`VITEST` / `NODE_ENV=test`) and via
+ * `AI_HUB_DISABLE_ROTATION_SCHEDULER=1`, so the existing server-boot test
+ * suite is unaffected.
+ *
+ * @see docs/server/rotating-messages.md
+ */
+import type { DrizzleDB } from "../db/connection.js";
+import type { LettaClient } from "../letta/client.js";
+import type { Logger } from "../observability/logger.js";
+/** Dependency bundle for the scheduler. */
+export interface RotationSchedulerDeps {
+    db: DrizzleDB;
+    lettaClient: LettaClient;
+    logger: Logger;
+}
+/** Handle for stopping a running scheduler. */
+export interface RotationScheduler {
+    /** Stops the tick loop. Idempotent. */
+    stop(): void;
+}
+/** Options for `startRotationScheduler`. */
+export interface StartRotationSchedulerOptions {
+    /** Tick interval in ms. Default 30000. Tests pass a small value. */
+    intervalMs?: number;
+    /** Skip the immediate kick-off tick (tests drive `tickOnce` directly). */
+    skipInitialTick?: boolean;
+}
+/**
+ * Starts a tick loop and returns a handle. Most callers want
+ * `ensureRotationScheduler` (process singleton); this is the testable core.
+ *
+ * @param deps - db + Letta client + logger.
+ * @param opts - tick cadence + initial-tick control.
+ * @returns a scheduler handle with `stop()`.
+ */
+export declare function startRotationScheduler(deps: RotationSchedulerDeps, opts?: StartRotationSchedulerOptions): RotationScheduler;
+/**
+ * Runs every due, non-archived rotation once, serially. Exported for tests
+ * (drive a single tick deterministically without a timer).
+ *
+ * @param deps - db + Letta client + logger.
+ * @param inFlight - shared set guarding against re-entrancy across ticks.
+ */
+export declare function tickOnce(deps: RotationSchedulerDeps, inFlight?: Set<string>): Promise<void>;
+/**
+ * Starts the rotation scheduler once per process and returns it (or `null`
+ * when intentionally disabled). Idempotent — subsequent calls return the
+ * already-running instance, so building multiple Fetch handlers in one process
+ * never spawns competing loops.
+ *
+ * Disabled (returns `null`, starts nothing) when:
+ *  - `AI_HUB_DISABLE_ROTATION_SCHEDULER=1`, or
+ *  - running under tests (`VITEST` set, or `NODE_ENV === "test"`).
+ *
+ * @param deps - db + Letta client + logger.
+ * @param env - env source (defaults to `process.env`).
+ * @returns the scheduler handle, or `null` when disabled.
+ */
+export declare function ensureRotationScheduler(deps: RotationSchedulerDeps, env?: Record<string, string | undefined>): RotationScheduler | null;
+//# sourceMappingURL=rotationScheduler.d.ts.map

package/dist/state/rotationScheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rotationScheduler.d.ts","sourceRoot":"","sources":["../../src/state/rotationScheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAOzD,2CAA2C;AAC3C,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,SAAS,CAAC;IACd,WAAW,EAAE,WAAW,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,+CAA+C;AAC/C,MAAM,WAAW,iBAAiB;IAChC,uCAAuC;IACvC,IAAI,IAAI,IAAI,CAAC;CACd;AAED,4CAA4C;AAC5C,MAAM,WAAW,6BAA6B;IAC5C,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,qBAAqB,EAC3B,IAAI,GAAE,6BAAkC,GACvC,iBAAiB,CAmCnB;AAED;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,qBAAqB,EAC3B,QAAQ,GAAE,GAAG,CAAC,MAAM,CAAa,GAChC,OAAO,CAAC,IAAI,CAAC,CAiBf;AAQD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,qBAAqB,EAC3B,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,iBAAiB,GAAG,IAAI,CAO1B"}

package/dist/state/rotationScheduler.js

@@ -0,0 +1,124 @@
+/**
+ * In-process scheduler for **rotating starting messages**.
+ *
+ * ai-hub deploys as one long-running Node process (in-process
+ * `better-sqlite3` + self-hosted Letta), so a simple tick loop is the right
+ * tool — no external cron, queue, or multi-instance coordination needed.
+ *
+ * Each tick selects non-archived `rotating_message` rows whose
+ * `next_rotation_at <= now` and runs them **serially** through `runRotation`.
+ * An in-memory `inFlight` set prevents a slow rotation from being re-picked by
+ * the next tick. `runRotation` advances `next_rotation_at` itself, so a row is
+ * naturally not due again until its interval elapses.
+ *
+ * The scheduler is started once per process from `createFetchHandler`
+ * (`ensureRotationScheduler`) — that's the single construction point both the
+ * dev `node:http` runner and the Next.js wrapper go through. It is **skipped
+ * under tests** (`VITEST` / `NODE_ENV=test`) and via
+ * `AI_HUB_DISABLE_ROTATION_SCHEDULER=1`, so the existing server-boot test
+ * suite is unaffected.
+ *
+ * @see docs/server/rotating-messages.md
+ */
+import { and, eq, lte } from "drizzle-orm";
+import { rotatingMessage } from "../db/schema.js";
+import { runRotation } from "./rotationRunner.js";
+/** Default tick cadence. Rotations are hourly/daily, so 30s polling is ample. */
+const DEFAULT_TICK_MS = 30_000;
+/**
+ * Starts a tick loop and returns a handle. Most callers want
+ * `ensureRotationScheduler` (process singleton); this is the testable core.
+ *
+ * @param deps - db + Letta client + logger.
+ * @param opts - tick cadence + initial-tick control.
+ * @returns a scheduler handle with `stop()`.
+ */
+export function startRotationScheduler(deps, opts = {}) {
+    const intervalMs = opts.intervalMs ?? DEFAULT_TICK_MS;
+    const inFlight = new Set();
+    let stopped = false;
+    let ticking = false;
+    const tick = async () => {
+        if (stopped || ticking)
+            return;
+        ticking = true;
+        try {
+            await tickOnce(deps, inFlight);
+        }
+        catch (err) {
+            deps.logger.error({ err: err instanceof Error ? err.message : String(err), event: "rotation_tick_failed" }, "Rotation scheduler tick failed.");
+        }
+        finally {
+            ticking = false;
+        }
+    };
+    const timer = setInterval(() => void tick(), intervalMs);
+    // Never let the scheduler alone keep the process alive.
+    if (typeof timer.unref === "function")
+        timer.unref();
+    if (!opts.skipInitialTick) {
+        void tick();
+    }
+    return {
+        stop() {
+            stopped = true;
+            clearInterval(timer);
+        },
+    };
+}
+/**
+ * Runs every due, non-archived rotation once, serially. Exported for tests
+ * (drive a single tick deterministically without a timer).
+ *
+ * @param deps - db + Letta client + logger.
+ * @param inFlight - shared set guarding against re-entrancy across ticks.
+ */
+export async function tickOnce(deps, inFlight = new Set()) {
+    const nowIso = new Date().toISOString();
+    const due = deps.db
+        .select()
+        .from(rotatingMessage)
+        .where(and(eq(rotatingMessage.isArchived, false), lte(rotatingMessage.nextRotationAt, nowIso)))
+        .all();
+    for (const row of due) {
+        if (inFlight.has(row.id))
+            continue;
+        inFlight.add(row.id);
+        try {
+            await runRotation(deps, row);
+        }
+        finally {
+            inFlight.delete(row.id);
+        }
+    }
+}
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Process singleton                                                         */
+/* ────────────────────────────────────────────────────────────────────────── */
+let singleton = null;
+/**
+ * Starts the rotation scheduler once per process and returns it (or `null`
+ * when intentionally disabled). Idempotent — subsequent calls return the
+ * already-running instance, so building multiple Fetch handlers in one process
+ * never spawns competing loops.
+ *
+ * Disabled (returns `null`, starts nothing) when:
+ *  - `AI_HUB_DISABLE_ROTATION_SCHEDULER=1`, or
+ *  - running under tests (`VITEST` set, or `NODE_ENV === "test"`).
+ *
+ * @param deps - db + Letta client + logger.
+ * @param env - env source (defaults to `process.env`).
+ * @returns the scheduler handle, or `null` when disabled.
+ */
+export function ensureRotationScheduler(deps, env = process.env) {
+    if (singleton)
+        return singleton;
+    if (env.AI_HUB_DISABLE_ROTATION_SCHEDULER === "1")
+        return null;
+    if (env.VITEST || env.NODE_ENV === "test")
+        return null;
+    singleton = startRotationScheduler(deps);
+    deps.logger.info({ event: "rotation_scheduler_started" }, "Rotating-message scheduler started.");
+    return singleton;
+}
+//# sourceMappingURL=rotationScheduler.js.map

package/dist/state/rotationScheduler.js.map

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

package/dist/state/turnRegistry.d.ts

@@ -0,0 +1,95 @@
+/**
+ * In-memory broadcaster for live turn streams.
+ *
+ * Every active turn has at most one writer (the runner) and zero-or-more
+ * subscribers (the original `POST /chat` connection + every
+ * `GET /chat/:turn_id/events?from_seq=N` resumption connection still
+ * running while the turn is live).
+ *
+ * Persistence lives in `turn_events` (§11) — the registry only handles the
+ * **live attach** part of resumption. The first half of a resumption read
+ * (replay from `from_seq`) is a plain DB query.
+ *
+ * The registry is process-local — this matches the single-customer
+ * deployment model (§1). When ai-hub scales to multiple replicas in a
+ * v1.x release, this gets a Redis-backed implementation behind the same
+ * interface; the wire protocol (§9) and the resumption contract (§6.3.2)
+ * stay unchanged.
+ *
+ * @see SPECIFICATIONS.md §6.3.2 — resumption endpoint
+ * @see SPECIFICATIONS.md §6.6 — server-authoritative state machine
+ * @see SPECIFICATIONS.md §11 — `turn_events` table
+ */
+import type { AIHubEvent } from "@data-club/ai-hub";
+/** Callback signature for a live subscriber. */
+export type TurnEventListener = (event: AIHubEvent) => void;
+/** Returned by `subscribe()` so the caller can unsubscribe. */
+export type Unsubscribe = () => void;
+/**
+ * Begins a new live turn channel.
+ *
+ * The runner calls this when it inserts the `turn` row, before it starts
+ * pumping events. Returns an opaque `TurnPublisher` the runner uses to
+ * publish + close.
+ *
+ * @param turnId - the freshly-created turn id.
+ * @returns the publisher handle.
+ */
+export declare function openTurnChannel(turnId: string): TurnPublisher;
+/**
+ * Subscribes to a live turn channel.
+ *
+ * Returns `null` when the turn is not active (either never opened or
+ * already closed) — the caller should fall back to replaying persisted
+ * events from `turn_events` instead.
+ *
+ * @param turnId - the turn id to attach to.
+ * @param listener - called once per event (with `seq` already assigned).
+ * @param onClose - called once when the channel closes (after final event).
+ * @returns an unsubscribe function, or `null` when the channel is closed.
+ */
+export declare function subscribeToTurn(turnId: string, listener: TurnEventListener, onClose: () => void): Unsubscribe | null;
+/**
+ * Returns `true` when the turn has an open channel right now.
+ *
+ * The chat handler uses this to disambiguate "turn is in flight" from
+ * "turn completed long ago" without having to query the DB twice.
+ */
+export declare function isTurnLive(turnId: string): boolean;
+/**
+ * Test-only utility — wipes the registry so tests can isolate from each
+ * other. Production code never calls this.
+ */
+export declare function _resetTurnRegistryForTests(): void;
+/**
+ * The runner's handle on a live channel. Opaque on purpose — the runner
+ * is the only writer.
+ */
+export interface TurnPublisher {
+    /**
+     * AbortSignal that fires when a separate `POST /chat/:id/cancel`
+     * request calls `requestTurnCancellation(turnId)`. The runner listens
+     * to this in addition to the originating request's signal.
+     */
+    cancelSignal: AbortSignal;
+    /** Push one event to every current subscriber. */
+    publish(event: AIHubEvent): void;
+    /** Mark the channel closed. After this, `subscribeToTurn` returns null. */
+    close(): void;
+}
+/**
+ * Triggers cancellation of the named turn. The runner is expected to
+ * have wired its run to the publisher's `cancelSignal`; firing it from
+ * here aborts the upstream Letta call and short-circuits the loop.
+ *
+ * Idempotent: calling on a closed / unknown turn is a no-op. The
+ * `POST /chat/:id/cancel` route's user-facing 200 response covers
+ * race-conditions where the turn terminated between the request and
+ * this call.
+ *
+ * @param turnId - the turn to cancel.
+ * @returns `true` if the signal was fired, `false` if the channel is
+ *   closed or unknown.
+ */
+export declare function requestTurnCancellation(turnId: string): boolean;
+//# sourceMappingURL=turnRegistry.d.ts.map

package/dist/state/turnRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turnRegistry.d.ts","sourceRoot":"","sources":["../../src/state/turnRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,gDAAgD;AAChD,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;AAE5D,+DAA+D;AAC/D,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAyCrC;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CA0C7D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,EAAE,MAAM,IAAI,GAClB,WAAW,GAAG,IAAI,CAYpB;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAGlD;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,YAAY,EAAE,WAAW,CAAC;IAC1B,kDAAkD;IAClD,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACjC,2EAA2E;IAC3E,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAK/D"}