@nightowlsdev/core 0.3.0

package/dist/index.d.cts

@@ -0,0 +1,814 @@
+import { z } from 'zod';
+
+interface SwarmContext {
+    tenantId: string;
+    userId: string;
+    agentSlug: string;
+    agentVersion?: number;
+    runId: string;
+    threadId: string;
+}
+interface AuthContext {
+    tenantId: string;
+    userId: string;
+    capabilities?: string[];
+}
+interface AuthProvider {
+    authenticate(req: Request): Promise<AuthContext | null>;
+    can?(ctx: AuthContext, capability: string): boolean | Promise<boolean>;
+}
+interface SecretResolver {
+    resolve(ref: string, ctx: SwarmContext): Promise<string>;
+}
+/** An optional rich input the asking agent CONSTRUCTS for a HITL `ask`, so the UI can render a fitting
+ *  widget instead of a bare text box. Omitted ⇒ a plain text input. Answer shape by kind: confirm→boolean,
+ *  buttons/select→the chosen `value`, multiselect→`value[]`, number→number, text/textarea→string. */
+interface AskFieldOption {
+    label: string;
+    value: string;
+    description?: string;
+}
+interface AskField {
+    kind: "confirm" | "buttons" | "select" | "multiselect" | "number" | "text" | "textarea";
+    /** buttons | select | multiselect */
+    options?: AskFieldOption[];
+    /** number */
+    min?: number;
+    max?: number;
+    step?: number;
+    unit?: string;
+    /** text | textarea */
+    placeholder?: string;
+    rows?: number;
+    /** confirm */
+    confirmLabel?: string;
+    rejectLabel?: string;
+    /** any kind with a submit action */
+    submitLabel?: string;
+    /** prefilled value */
+    default?: unknown;
+}
+interface EvBase {
+    runId: string;
+    agentSlug: string;
+    ts: number;
+    seq?: number;
+    schemaVersion: 1;
+}
+type SwarmEvent = (EvBase & {
+    type: "swarm.status";
+    data: {
+        state: "thinking" | "delegating" | "waiting" | "tool" | "done" | "blocked";
+        note?: string;
+        position?: number;
+    };
+}) | (EvBase & {
+    type: "swarm.message";
+    data: {
+        role: "assistant";
+        delta?: string;
+        text?: string;
+    };
+}) | (EvBase & {
+    type: "swarm.handoff";
+    data: {
+        from: string;
+        to: string;
+        task: string;
+    };
+}) | (EvBase & {
+    type: "swarm.tool_call";
+    data: {
+        toolCallId: string;
+        name: string;
+        args: unknown;
+        needsApproval: boolean;
+    };
+}) | (EvBase & {
+    type: "swarm.tool_result";
+    data: {
+        toolCallId: string;
+        ok: boolean;
+        result?: unknown;
+        error?: string;
+    };
+}) | (EvBase & {
+    type: "swarm.question";
+    data: {
+        followupId: string;
+        toolCallId: string;
+        to: "user" | string;
+        from?: string;
+        prompt: string;
+        field?: AskField;
+        schema?: unknown;
+    };
+}) | (EvBase & {
+    type: "swarm.answer";
+    data: {
+        followupId: string;
+        from: "user" | string;
+        answer: unknown;
+    };
+}) | (EvBase & {
+    type: "swarm.run_failed";
+    data: {
+        stage: string;
+        message: string;
+        retryable: boolean;
+    };
+});
+interface AgentVersion {
+    slug: string;
+    version: number;
+    role: "orchestrator" | "specialist";
+    personality: string;
+    capabilities: string[];
+    skillNames: string[];
+    delegateSlugs: string[];
+    modelId: string;
+    /** Per-agent memory OPTIONS override (R9), merged over the swarm MemoryConfig. Infra stays swarm-wide. */
+    memory?: AgentMemoryOverride;
+}
+/** A per-agent override of the swarm memory OPTIONS (R9) — never the infra (store/vector/embedder). */
+interface AgentMemoryOverride {
+    lastMessages?: number;
+    workingMemory?: boolean | {
+        template?: string;
+    };
+    semanticRecall?: boolean | {
+        topK?: number;
+        messageRange?: number;
+    };
+    observationalMemory?: boolean | Record<string, unknown>;
+}
+interface AgentDef {
+    slug: string;
+    head: AgentVersion;
+    /**
+     * The concrete skill handles this agent was defined with. Carried on the def
+     * (not a module global) so `defineSwarm` can build a per-swarm skill registry —
+     * avoids cross-swarm leakage. `SwarmSkill` lives in define.ts; typed loosely
+     * here to keep types.ts free of a back-edge import.
+     */
+    skills?: {
+        name: string;
+    }[];
+}
+interface RunRow {
+    runId: string;
+    tenantId: string;
+    userId: string;
+    threadId: string;
+    status: RunStatus;
+    agentSlug: string;
+}
+type RunStatus = "running" | "suspended" | "done" | "failed";
+interface ActiveRun {
+    runId: string;
+    threadId: string;
+    agentSlug: string;
+    status: RunStatus;
+}
+interface NewRun {
+    runId: string;
+    tenantId: string;
+    userId: string;
+    threadId: string;
+    agentSlug: string;
+}
+interface SwarmMessage {
+    threadId: string;
+    role: "user" | "assistant";
+    text: string;
+    ts: number;
+    /** Speaker of an assistant turn on a shared (multi-agent) thread, decoded from the engine's persisted
+     *  "[<slug>] " prefix. Undefined for user turns and for single-agent threads with no prefix. Lets the
+     *  group-chat history render per-message speaker labels (live turns get the speaker from `nightowls.events`). */
+    agentSlug?: string;
+    /** Sender of a USER turn on a shared (multi-user) thread (R14), decoded from the engine's trusted
+     *  "[user:<id>] " prefix. Undefined for assistant turns and single-user threads with no prefix. */
+    userId?: string;
+}
+/** Wall-safe summary of one of a user's conversations (powers the threads-list sidebar). Built by
+ *  `engine.listThreads` from the engine's Memory — no engine-vendor type in the shape. */
+interface ThreadSummary {
+    threadId: string;
+    title: string;
+    lastActivityAt: number;
+}
+/** Wall-safe roster entry for a swarm's agent (no vendor type). Powers the multi-agent pile/@mention UI. */
+interface AgentSummary {
+    slug: string;
+    /** Display name — title-cased from the slug (agents have no separate name field). */
+    name: string;
+    role: string;
+    /** Slugs this agent can delegate to (the addressable graph). */
+    delegateSlugs: string[];
+}
+interface EventStore {
+    append(e: SwarmEvent): Promise<number>;
+    /** Tenant-scoped (R11): a forged cross-org runId returns []. The store enforces tenancy, not just the caller. */
+    list(tenantId: string, runId: string, sinceSeq: number): Promise<SwarmEvent[]>;
+    subscribe(runId: string): AsyncIterable<SwarmEvent>;
+}
+interface RunStore {
+    create(run: NewRun): Promise<void>;
+    setStatus(runId: string, status: RunStatus, patch?: Partial<RunRow>): Promise<void>;
+    saveSnapshot(runId: string, snapshot: unknown): Promise<void>;
+    /** Tenant-scoped (R11): a cross-org runId returns null (defense-in-depth; resume also gates via findSuspended). */
+    loadSnapshot(tenantId: string, runId: string): Promise<unknown | null>;
+    findSuspended(tenantId: string, followupId: string): Promise<{
+        runId: string;
+        toolCallId: string;
+    } | null>;
+    get(runId: string): Promise<RunRow | null>;
+    /** In-flight runs (running|suspended) for a container thread + its lane threads. Powers cross-lane presence (E5). */
+    listActive(tenantId: string, container: string): Promise<ActiveRun[]>;
+    /** Distinct container threadIds the user has a run in, most-recently-active first (R14: participation-based
+     *  `listThreads` — under thread-scoped `resourceId`, a user's threads are the ones they participated in, not
+     *  a resourceId filter). `container` = the threadId before any `:lane`. Tenant-scoped. Optional: an adapter
+     *  that omits it leaves `engine.listThreads` on the degraded single-container fallback. */
+    listUserContainers?(tenantId: string, userId: string, limit?: number): Promise<string[]>;
+    /** Authorization gate for the read endpoints (R14 security): may this user read this container? True iff the
+     *  container has NO runs yet (a brand-new/empty thread — nothing to protect) OR the user has a run in it (a
+     *  participant). Blocks a same-tenant non-participant from reading another user's populated thread once
+     *  `resourceId` is thread-scoped. Tenant-scoped. Optional: an adapter that omits it leaves the endpoints
+     *  ungated (the prior behavior) — the shipped adapters implement it. */
+    canAccessContainer?(tenantId: string, userId: string, container: string): Promise<boolean>;
+    /** Durable-runner only (background): persist the vendor waitpoint token id for a followup. Optional. */
+    attachWaitpoint?(followupId: string, token: string, kind: "trigger" | "vercel"): Promise<void>;
+    /** Durable-runner only: read the waitpoint token id back (for completeWaitpoint). Optional. */
+    getWaitpoint?(followupId: string): Promise<string | null>;
+}
+interface MessageStore {
+    append(m: SwarmMessage): Promise<void>;
+    /** Tenant-scoped (R11). NOTE: currently no production caller — the runner's history endpoint goes through
+     *  `engine.history` (Mastra recall, scoped by resourceId=tenant:user). Kept for contract consistency. */
+    history(tenantId: string, threadId: string, limit?: number): Promise<SwarmMessage[]>;
+}
+/** Scratchpad caps (intentionally lossy — working memory, not a system of record). */
+declare const SCRATCHPAD_MAX_ENTRY_CHARS = 4000;
+declare const SCRATCHPAD_MAX_KEYS = 64;
+interface ScratchpadEntry {
+    section: "public" | "meta";
+    key: string;
+    author: string;
+    requestedBy: string;
+    content: string;
+    updatedAt: number;
+}
+interface ScratchpadStore {
+    /** Upsert one keyed entry — different keys never collide; same key revises in place. Concurrent-safe.
+     *  `by` carries attribution + an optional per-write `maxKeys` cap (L3): the store keeps only the newest
+     *  `maxKeys` keys per section, defaulting to `SCRATCHPAD_MAX_KEYS` when omitted. */
+    write(tenantId: string, container: string, section: "public" | "meta", key: string, content: string, by: {
+        agentSlug: string;
+        userId: string;
+        requestedBy: string;
+        maxKeys?: number;
+    }): Promise<void>;
+    /** All entries for a container (both sections). Empty array when none. Never throws. */
+    list(tenantId: string, container: string): Promise<ScratchpadEntry[]>;
+}
+interface AgentRepo {
+    head(tenantId: string, slug: string): Promise<AgentVersion | null>;
+    getVersion(tenantId: string, slug: string, version: number): Promise<AgentVersion | null>;
+    listSlugs(tenantId: string): Promise<string[]>;
+}
+interface StorageAdapter {
+    agents: AgentRepo;
+    runs: RunStore;
+    events: EventStore;
+    messages: MessageStore;
+    /** Opt-in container scratchpad (Part D). Optional so existing adapters keep compiling. */
+    scratchpad?: ScratchpadStore;
+    /**
+     * Record a suspended run in the tenant-scoped followup index so a later `resume` can authorize it
+     * (the runner's `findSuspended(tenantId, followupId)` gate). Called by the engine on every `ask`
+     * suspend (incl. a sub-agent's `ask` bubbling up through a delegation). REQUIRED for human-in-the-loop
+     * resume to work — an adapter that omits it leaves `findSuspended` empty and every resume is forbidden.
+     * Awaited by the engine so the row commits before the run is marked suspended.
+     */
+    recordSuspend?(runId: string, tenantId: string, followupId: string, toolCallId: string): void | Promise<void>;
+    /**
+     * Mark a followup as answered so it can no longer be resumed (the engine calls this when a `resume`
+     * begins). Closes a replay hole: without it, `findSuspended` keeps returning the followup and the same
+     * answer can be replayed indefinitely. Idempotent; tenant-scoped. Awaited by the engine.
+     */
+    markFollowupAnswered?(followupId: string, tenantId: string): void | Promise<void>;
+    /**
+     * Cross-process cache invalidation (R12). Subscribe to agent-republish notifications so an engine on ANY
+     * instance can evict its agent-row cache immediately instead of waiting out the TTL. `onInvalidate` receives
+     * the cache key (`tenantId:slug`). Returns an unsubscribe. Optional — single-process stores omit it (the TTL
+     * is the only staleness bound there). The supabase adapter uses Postgres LISTEN/NOTIFY.
+     */
+    subscribeInvalidations?(onInvalidate: (key: string) => void): () => void;
+}
+interface ModelProvider {
+    resolve(modelId: string, ctx: {
+        tenantId: string;
+    }): Promise<string> | string;
+}
+interface SwarmSpan {
+    name: string;
+    kind: "run" | "delegation" | "tool" | "generation" | "event" | "recall";
+    traceId: string;
+    attributes: Record<string, unknown>;
+    startedAt: number;
+    endedAt?: number;
+}
+interface TelemetryExporter {
+    export(spans: SwarmSpan[]): Promise<void>;
+}
+/** Opt-in conversational memory (Mastra-backed). Mastra handles are `unknown` to keep the engine wall
+ *  intact — the same pattern as `mastraStore`. Omit `memory` entirely for today's stateless behavior. */
+interface MemoryConfig {
+    /** Mastra memory storage. Pass `createMastraPgStore({ dbUrl })` from @nightowlsdev/storage-supabase. REQUIRED. */
+    store: unknown;
+    /** Mastra vector store. Pass `createMastraVectorStore({ dbUrl })`. REQUIRED when `semanticRecall` is set. */
+    vector?: unknown;
+    /** AI-SDK embedding model (host-provided). REQUIRED when `semanticRecall` is set. */
+    embedder?: unknown;
+    /** Recent messages included each turn. Default 20. */
+    lastMessages?: number;
+    /** Working-memory scratchpad. Thread-scoped: shared by every participant in a thread, never across a
+     *  user's other threads. Default off. */
+    workingMemory?: boolean | {
+        template?: string;
+    };
+    /** Vector recall over older messages. Thread-scoped: only ever recalls from the current thread, never
+     *  from the user's other threads. Default off. Requires `vector` + `embedder`. */
+    semanticRecall?: boolean | {
+        topK?: number;
+        messageRange?: number;
+    };
+    /** Opt-in observational memory (R10): Mastra's built-in LLM observation/reflection — compacts the conversation
+     *  into durable observations so context isn't lost beyond the recent window. `true` for defaults, or pass
+     *  Mastra's `observationalMemory` options object (opaque — see Mastra docs). Default off. */
+    observationalMemory?: boolean | Record<string, unknown>;
+}
+interface RunInput {
+    message: string;
+    /**
+     * Opt-in, host-supplied page context. UNTRUSTED and advisory only — it is data the host page
+     * volunteered (e.g. the current route, selection, or visible records) for the agent to optionally
+     * pull via the `get_page_context` tool. NEVER use it for identity, authorization, or tenancy
+     * (those come from `SwarmContext`); treat its contents as opaque, attacker-controllable input.
+     */
+    context?: Record<string, unknown>;
+}
+interface Runner {
+    run(input: RunInput, ctx: SwarmContext): AsyncIterable<SwarmEvent>;
+    enqueue(input: RunInput, ctx: SwarmContext): Promise<{
+        runId: string;
+    }>;
+    resume(args: {
+        runId: string;
+        toolCallId: string;
+        followupId: string;
+        answer: unknown;
+    }, ctx: SwarmContext): AsyncIterable<SwarmEvent>;
+}
+
+type ByType<T extends SwarmEvent["type"]> = Extract<SwarmEvent, {
+    type: T;
+}>;
+declare function ev<T extends SwarmEvent["type"]>(type: T, base: {
+    runId: string;
+    agentSlug: string;
+    ts: number;
+    seq?: number;
+}, data: ByType<T>["data"]): ByType<T>;
+declare function isEvent<T extends SwarmEvent["type"]>(e: SwarmEvent, type: T): e is ByType<T>;
+
+/** Identifies who holds (or is queued for) a container's floor — surfaced in the "waiting for X" indicator. */
+interface FloorHolder {
+    /** Display name of the holding run's lane agent, e.g. "Coordinator". */
+    label: string;
+    /** The holding run's id (telemetry / debugging). */
+    runId: string;
+}
+/** A release fn — idempotent (calling it more than once is a no-op). */
+type Release = () => void | Promise<void>;
+interface ContainerFloor {
+    /** Take the floor synchronously if free; returns a release fn, or null if currently held. */
+    tryAcquire(container: string, who: FloorHolder): Promise<Release | null>;
+    /** Wait for the floor (FIFO). Resolves immediately if free. If `signal` aborts while queued, the waiter
+     *  is dropped and the resolved release is a no-op; if it aborts after the grant, the floor is released. */
+    acquire(container: string, who: FloorHolder, signal?: AbortSignal): Promise<Release>;
+    /** The current holder of a container's floor, or null if free. */
+    holder(container: string): Promise<FloorHolder | null>;
+    /** Number of live (non-cancelled) waiters currently queued for this container's floor. */
+    queueDepth(container: string): Promise<number>;
+}
+/** In-memory, single-process container floor. Process-wide via the `containerFloor` singleton.
+ *  NOT shared across serverless instances — see the spec's "in-memory, single-process" tradeoff. */
+declare class InMemoryContainerFloor implements ContainerFloor {
+    private readonly maxHoldMs;
+    private slots;
+    /** @param maxHoldMs force-release backstop for a hung grant (a run that never releases). */
+    constructor(maxHoldMs?: number);
+    private slot;
+    holder(container: string): Promise<FloorHolder | null>;
+    queueDepth(container: string): Promise<number>;
+    tryAcquire(container: string, who: FloorHolder): Promise<Release | null>;
+    acquire(container: string, who: FloorHolder, signal?: AbortSignal): Promise<Release>;
+    /** Take the floor for `who`, arm the backstop, and return an idempotent release that hands off FIFO. */
+    private grant;
+    /** Release `who`'s hold (if still current) and grant the next live FIFO waiter, or free the floor. */
+    private release;
+}
+/** Process-wide singleton. In-memory → single-process only (serverless instances don't share it). */
+declare const containerFloor: ContainerFloor;
+
+interface Price {
+    inUsdPerMtok: number;
+    outUsdPerMtok: number;
+}
+declare const PRICE_TABLE: Record<string, Price>;
+declare class CostGovernor {
+    private opts;
+    private steps;
+    private usd;
+    private prices;
+    constructor(opts: {
+        maxSteps: number;
+        maxCostUsd: number;
+        prices?: Record<string, Price>;
+    });
+    step(): void;
+    /** Price a single usage WITHOUT accumulating it (for per-generation telemetry cost). */
+    priceOf(modelId: string, u: {
+        inputTokens: number;
+        outputTokens: number;
+    }): number;
+    addUsage(modelId: string, u: {
+        inputTokens: number;
+        outputTokens: number;
+    }): void;
+    costUsd(): number;
+    shouldStop(): {
+        stop: boolean;
+        reason?: string;
+    };
+}
+/**
+ * Per-delegate USD sub-budgets (R5). The global `cost.maxCostUsd` bounds the WHOLE turn; this adds an
+ * optional ceiling applied to EACH delegate (sub-agent) so one runaway sub-agent can't burn the entire
+ * turn before the global cap notices. `maxCostUsd` is the default ceiling for every delegate; `bySlug`
+ * overrides it per delegate slug (a slug listed there is capped even if there is no default). The run's
+ * root orchestrator is NOT a delegate and is never capped here — the global cap already covers it.
+ */
+interface PerDelegateBudget {
+    /** Default USD ceiling per delegate. Omit to cap only the slugs named in `bySlug`. */
+    maxCostUsd?: number;
+    /** Per-slug overrides of `maxCostUsd`. */
+    bySlug?: Record<string, {
+        maxCostUsd?: number;
+    }>;
+}
+/** Tracks per-delegate USD spend and reports the first delegate to exceed its budget. Priced from the same
+ *  table as CostGovernor (via the shared `priceUsage`) so the global and per-delegate caps agree. Usage
+ *  attributed to the root orchestrator slug is ignored. */
+declare class DelegateBudgets {
+    private cfg;
+    private rootSlug;
+    private usd;
+    private prices;
+    constructor(cfg: PerDelegateBudget, rootSlug: string, prices?: Record<string, Price>);
+    /** The USD cap for a delegate: its `bySlug` override if present, else the default. `undefined` → uncapped. */
+    private capFor;
+    /** Accumulate one generation's usage against a delegate. No-op for the root orchestrator (not a delegate). */
+    addUsage(slug: string, modelId: string, u: {
+        inputTokens: number;
+        outputTokens: number;
+    }): void;
+    /** The first delegate that has met or exceeded its USD cap, or null. */
+    exceeded(): {
+        slug: string;
+        reason: string;
+    } | null;
+}
+
+interface EngineOpts {
+    storage: StorageAdapter;
+    model: ModelProvider;
+    modelFactory: (modelId: string, agentSlug?: string) => unknown;
+    /** Global per-run caps + optional per-delegate sub-budgets (R5: `perDelegate` stops one runaway sub-agent
+     *  from burning the whole turn before the global `maxCostUsd` notices). */
+    cost: {
+        maxSteps: number;
+        maxCostUsd: number;
+        perDelegate?: PerDelegateBudget;
+    };
+    /** Per-swarm skill resolver. When omitted, agents expose only built-in tools. */
+    resolveSkill?: (name: string) => SwarmSkill | undefined;
+    /**
+     * Mastra storage backend for suspend/resume snapshots. Resume is storage-gated
+     * (SPIKE-FINDINGS item 5): the in-memory default cannot survive process death.
+     * Inject a durable store (e.g. `@nightowlsdev/storage-supabase`'s `createMastraPgStore`)
+     * to make `ask`-suspend/`resumeStream` cross-process. Falls back to InMemoryStore.
+     */
+    mastraStore?: unknown;
+    /**
+     * Optional telemetry exporter. When set, `run`/`resume` collect `run`/`generation`/`tool`
+     * SwarmSpans and batch-export them once in a `finally` (best-effort — a throwing exporter
+     * never breaks the run). When null/omitted, span collection is skipped (no-op).
+     */
+    telemetry?: TelemetryExporter | null;
+    /** Opt-in conversational memory. When set, later tasks build+attach a Mastra Memory and pass ids to
+     *  stream/resumeStream. Omitted => stateless (unchanged). */
+    memory?: MemoryConfig;
+    /** Opt-in page-context channel. Default false. When true, a later task exposes a `get_page_context`
+     *  tool the agent can pull the host page's untrusted, advisory `RunInput.context` from. */
+    pageContext?: boolean;
+    /** Opt-in shared scratchpad (Part D). Requires `storage.scratchpad`. `true` uses default caps; pass an object
+     *  to override the per-entry char cap and/or per-section key cap (L3). */
+    scratchpad?: boolean | {
+        maxEntryChars?: number;
+        maxKeys?: number;
+    };
+    /** Opt-in `recall_lane` tool (Part E). Read-only peer-lane transcript read. */
+    recallLane?: boolean;
+    /** Injectable per-lane floor (Part C / E3). Default: the in-memory process singleton. Pass a Postgres-backed
+     *  floor (createPostgresFloor) for serverless / multi-instance deploys. */
+    floor?: ContainerFloor;
+}
+declare class SwarmEngine {
+    private opts;
+    private mastra;
+    private rowCache;
+    private memory;
+    private floor;
+    constructor(opts: EngineOpts);
+    /** Cached agent-row load shared by the three dynamic agent fns AND run/resume. */
+    private loadRow;
+    private agent;
+    private requestContext;
+    /** Per-call Mastra memory ids + delegation, only when memory is configured (else stream is unchanged). */
+    private memoryOpts;
+    /**
+     * Read a thread's persisted conversation from the engine's Memory and return it as wall-safe
+     * `SwarmMessage[]` (no engine-vendor type in the signature or the result — powers "reload keeps the chat").
+     *
+     * Shapes are spike-proven against the Mastra memory surface (`memory.recall`, NOT `memory.query`): each
+     * recalled row is a MastraDBMessage whose text lives in `content.parts[]` (NOT a flat `m.text`/string
+     * `m.content`). The vendor value is cast THROUGH a local structural type so no vendor type leaks to the
+     * public `.d.ts` (engine wall). Returns `[]` when the engine is stateless (no memory configured).
+     */
+    history(threadId: string, ctx: SwarmContext, opts?: {
+        limit?: number;
+    }): Promise<SwarmMessage[]>;
+    /**
+     * R4: emit a single `recall` telemetry span for a `history` recall, best-effort. Fire-and-forget — a
+     * throwing/slow exporter must never delay or break a history read, so we don't await it and swallow errors.
+     * traceId is the invoking ctx's runId so a recall inside a run (via `recall_lane`) joins that run's trace.
+     */
+    private emitRecallSpan;
+    /**
+     * Multi-agent shared-thread attribution (the persist boundary). Mastra recall carries NO per-message
+     * author field (spike-proven), so on a thread several agents share, a later agent can't tell who said an
+     * earlier assistant turn. After a run drains, this PREFIXES that run's just-persisted assistant turn(s)
+     * with `"[<slug>] "` — the only place the speaker survives in Mastra memory — so a subsequent agent's
+     * recall sees it inline; `history` decodes + strips it for display. Best-effort: never throws into the
+     * run, and no-op when the engine is stateless. Idempotent (skips an already-prefixed turn) and bounded to
+     * THIS run's responses (only assistant turns AFTER the most-recent user message) so a wide recall window
+     * can never re-stamp an older agent's turn with the wrong slug.
+     */
+    private attributeRun;
+    /**
+     * Part B — mirror a delegation into the sub-agent's LANE thread. A delegation runs the sub-agent as a
+     * Mastra `agent-<slug>` tool inside the orchestrator's turn, so its work lands in the orchestrator's
+     * thread, not the sub-agent's lane (`<container>:<slug>`). After the run drains, this recalls THIS run's
+     * assistant turn(s) and, for each `agent-<slug>` tool-invocation part (which carries BOTH the task =
+     * `args.prompt` and the answer = `result.text`), `saveMessages` the pair into the sub-agent's lane thread
+     * — so switching to that agent's lane shows the delegated task + result, durably. Best-effort; Mastra-only
+     * (no nightowls.runs row ⇒ no thread-backing FK). Bounded to this run's turns ⇒ each run mirrors once.
+     */
+    private mirrorDelegations;
+    /**
+     * List the user's conversations from the engine's Memory and return them as wall-safe
+     * `ThreadSummary[]` (no engine-vendor type in the signature or the result — powers a threads-list
+     * sidebar). Returns `[]` when the engine is stateless (no memory configured).
+     *
+     * Shape is spike-proven against the Mastra memory surface (`memory.listThreads`, NOT the
+     * non-existent `getThreadsByResourceId`): resourceId goes under `filter`, the envelope is
+     * `{ threads }`, and each thread row carries `{ id, title?, createdAt, updatedAt }` (see the
+     * threads-spike SPIKE-FINDINGS). The vendor value is cast THROUGH a local structural type so no
+     * vendor type leaks to the public `.d.ts` (engine wall). Already DESC by `updatedAt`, so the
+     * newest-active thread is first; no per-thread recall (avoids N+1) — the engine auto-titles threads.
+     */
+    listThreads(ctx: SwarmContext, opts?: {
+        limit?: number;
+    }): Promise<ThreadSummary[]>;
+    /** The PUBLIC entries of a conversation's scratchpad (empty array when the feature is off or unset). */
+    scratchpadPublic(container: string, ctx: SwarmContext): Promise<ScratchpadEntry[]>;
+    /** In-flight runs (running|suspended) for a container + its lanes — powers cross-lane background presence (E5). */
+    activeRuns(container: string, ctx: SwarmContext): Promise<ActiveRun[]>;
+    /** The tenant's agent roster (slug, title-cased display name, role, delegate graph) as wall-safe
+     *  AgentSummary[]. Sourced from the agent rows; no vendor type in the signature or result. Powers
+     *  the multi-agent pile / @mention UI. */
+    listAgents(ctx: SwarmContext): Promise<AgentSummary[]>;
+    run(input: RunInput, ctx: SwarmContext): AsyncIterable<SwarmEvent>;
+    resume(args: {
+        runId: string;
+        toolCallId: string;
+        followupId: string;
+        answer: unknown;
+        context?: Record<string, unknown>;
+    }, ctx: SwarmContext): AsyncIterable<SwarmEvent>;
+}
+
+interface ToolSpec<I, O> {
+    name: string;
+    description?: string;
+    inputSchema: z.ZodType<I>;
+    outputSchema?: z.ZodType<O>;
+    needsApproval?: boolean;
+    origin?: "first-party" | "mcp";
+    execute: (input: I, ctx: SwarmToolContext) => Promise<O>;
+}
+interface SwarmToolContext {
+    tenantId: string;
+    userId: string;
+    runId: string;
+    secrets?: {
+        resolve(ref: string): Promise<string>;
+    };
+}
+interface SwarmTool {
+    name: string;
+    needsApproval: boolean;
+    origin: "first-party" | "mcp";
+}
+type SwarmSkill = SwarmTool;
+declare function defineTool<I, O>(spec: ToolSpec<I, O>): SwarmTool;
+declare function defineSkill(tool: SwarmTool): SwarmSkill;
+interface AgentSpec {
+    slug: string;
+    role?: "orchestrator" | "specialist";
+    personality: string;
+    capabilities?: string[];
+    skills?: SwarmSkill[];
+    delegates?: string[];
+    modelId?: string;
+    /** Per-agent memory OPTIONS override (R9), merged over the swarm `memory` config. Infra stays swarm-wide. */
+    memory?: AgentMemoryOverride;
+}
+declare function defineAgent(spec: AgentSpec): AgentDef;
+/** Build a per-swarm skill resolver from the agents' attached skill handles. */
+declare function buildSkillResolver(agents: AgentDef[]): (name: string) => SwarmSkill | undefined;
+declare const ASK_TOOL_NAME = "ask";
+interface SwarmConfig {
+    storage: StorageAdapter;
+    agents: AgentDef[];
+    models: {
+        allow: string[];
+    };
+    modelFactory: (modelId: string, agentSlug?: string) => unknown;
+    cost: {
+        maxSteps: number;
+        maxCostUsd: number;
+        perDelegate?: PerDelegateBudget;
+    };
+    /**
+     * Telemetry exporter(s). One or many — many are composed best-effort
+     * (`compositeTelemetry`: a throwing exporter never breaks a run). Spans are
+     * batch-exported once per run in a `finally`. Omit for a no-op.
+     */
+    telemetry?: TelemetryExporter | TelemetryExporter[];
+    /**
+     * Durable Mastra snapshot store for `ask`-suspend / `resume`. REQUIRED for human-in-the-loop resume
+     * to survive across requests/processes (each HTTP request — chat vs resume — is a fresh route
+     * invocation; serverless has no shared memory). Pass `createMastraPgStore({ dbUrl })` from
+     * `@nightowlsdev/storage-supabase`. Omit and the engine falls back to an in-memory store: resume then only
+     * works within a single live process (fine for unit tests, NOT for a deployed app).
+     */
+    mastraStore?: unknown;
+    /** Opt-in conversational memory. Omit for stateless turns (today's behavior). See MemoryConfig. */
+    memory?: MemoryConfig;
+    /** Opt-in page-context channel. Default false. When true, a later task exposes a `get_page_context`
+     *  tool the agent can pull the host page's untrusted, advisory `RunInput.context` from. */
+    pageContext?: boolean;
+    /** Opt-in shared scratchpad (Part D). Default false. When true, agents get a `scratchpad_write` tool and
+     *  the conversation's shared doc is injected into every agent's context. Requires a StorageAdapter with a
+     *  `scratchpad` store. Pass an object to override the caps (L3): `{ maxEntryChars?, maxKeys? }`. */
+    scratchpad?: boolean | {
+        maxEntryChars?: number;
+        maxKeys?: number;
+    };
+    /** Opt-in `recall_lane` tool (Part E): lets an agent read a peer agent's lane transcript in the same
+     *  conversation. Read-only; reuses the engine's history (best-effort — empty without memory). */
+    recallLane?: boolean;
+}
+interface Swarm {
+    engine: SwarmEngine;
+}
+declare function defineSwarm(cfg: SwarmConfig): Swarm;
+
+declare function allowListModelProvider(opts: {
+    allow: string[];
+}): ModelProvider;
+
+/** Wrap a plain function into a TelemetryExporter. */
+declare function customTelemetry(fn: (spans: SwarmSpan[]) => Promise<void> | void): TelemetryExporter;
+/**
+ * Fan out to many exporters. Best-effort: one failing exporter never blocks the others or the run
+ * (Promise.allSettled), and the composite's export() never rejects.
+ */
+declare function compositeTelemetry(exporters: TelemetryExporter[]): TelemetryExporter;
+/** Normalize the SwarmConfig.telemetry field (one | many | none) into a single exporter or null. */
+declare function resolveTelemetry(t: TelemetryExporter | TelemetryExporter[] | undefined): TelemetryExporter | null;
+/** Test/no-op exporter that records spans in memory. */
+declare class CapturingExporter implements TelemetryExporter {
+    spans: SwarmSpan[];
+    export(spans: SwarmSpan[]): Promise<void>;
+}
+/**
+ * Collects SwarmSpans during a single run/resume. The engine drives it from its chunk loop:
+ * one root `run` span; one `generation` span per model call (opened lazily on first model activity,
+ * closed on that call's `step-finish` with the step's own usage + per-generation cost); one `tool`
+ * span per tool_call→tool_result pair. Each generation's `costUsd` is the per-call cost (priced
+ * directly from that step's usage — NOT a running cumulative total), so multi-step runs never
+ * double-count. Times come from the engine's own clock (`now`) so they align with event ts and
+ * stay deterministic in tests.
+ */
+declare class SpanCollector {
+    private traceId;
+    private now;
+    private spans;
+    private runSpan;
+    private gen;
+    private tools;
+    constructor(traceId: string, now: () => number, runName: string, runAttrs?: Record<string, unknown>);
+    /** Ensure a generation span is open (lazy — first model activity in this step). */
+    openGeneration(modelId: string): void;
+    /**
+     * Close the open generation with this step's usage + its own per-call cost (already priced from
+     * the step usage by the engine). `costUsd` is per-generation — never a cumulative running total.
+     */
+    closeGeneration(usage: {
+        inputTokens: number;
+        outputTokens: number;
+    }, costUsd: number): void;
+    openTool(toolCallId: string, name: string): void;
+    closeTool(toolCallId: string, ok: boolean): void;
+    /**
+     * Seal: close the run span and any dangling open spans, return the batch. A run that suspends
+     * mid-step (e.g. an `ask` tool-call → `tool-call-suspended` with no `step-finish`) leaves the
+     * generation/tool spans open with no usage/result — those are tagged `incomplete:true` so
+     * downstream consumers don't mistake a sealed-but-unfinished span for a completed one.
+     */
+    finish(): SwarmSpan[];
+}
+
+declare class RowCache<V> {
+    private opts;
+    private map;
+    constructor(opts: {
+        max: number;
+        ttlMs: number;
+        now?: () => number;
+    });
+    private now;
+    get(key: string, load: () => Promise<V>): Promise<V>;
+    /** Synchronous read of an already-cached, unexpired value (no load, no LRU touch). */
+    peek(key: string): V | undefined;
+    invalidate(key: string): void;
+}
+
+declare class InMemoryStorage implements StorageAdapter {
+    private evts;
+    private seq;
+    private runRows;
+    private snapshots;
+    private suspends;
+    private waitpoints;
+    private msgs;
+    private agentRows;
+    private heads;
+    private pads;
+    seedAgent(v: AgentVersion, tenantId?: string): void;
+    recordSuspend(runId: string, tenantId: string, followupId: string, toolCallId: string): void;
+    markFollowupAnswered(followupId: string, tenantId: string): void;
+    /** Test/host helper: read a run row (the RunStore interface is write-mostly). */
+    getRun(runId: string): RunRow | undefined;
+    events: EventStore;
+    runs: RunStore;
+    messages: MessageStore;
+    scratchpad: ScratchpadStore;
+    agents: AgentRepo;
+}
+
+declare const GUARDRAILS: string;
+declare function composeSystemPrompt(row: AgentVersion): {
+    role: "system";
+    content: string;
+}[];
+
+declare const customAuth: (fn: AuthProvider["authenticate"]) => AuthProvider;
+
+declare const VERSION = "0.0.0";
+
+export { ASK_TOOL_NAME, type ActiveRun, type AgentDef, type AgentMemoryOverride, type AgentRepo, type AgentSpec, type AgentSummary, type AgentVersion, type AskField, type AskFieldOption, type AuthContext, type AuthProvider, CapturingExporter, type ContainerFloor, CostGovernor, DelegateBudgets, type EngineOpts, type EventStore, type FloorHolder, GUARDRAILS, InMemoryContainerFloor, InMemoryStorage, type MemoryConfig, type MessageStore, type ModelProvider, type NewRun, PRICE_TABLE, type PerDelegateBudget, type Price, type Release, RowCache, type RunInput, type RunRow, type RunStatus, type RunStore, type Runner, SCRATCHPAD_MAX_ENTRY_CHARS, SCRATCHPAD_MAX_KEYS, type ScratchpadEntry, type ScratchpadStore, type SecretResolver, SpanCollector, type StorageAdapter, type Swarm, type SwarmConfig, type SwarmContext, SwarmEngine, type SwarmEvent, type SwarmMessage, type SwarmSkill, type SwarmSpan, type SwarmTool, type SwarmToolContext, type TelemetryExporter, type ThreadSummary, type ToolSpec, VERSION, allowListModelProvider, buildSkillResolver, composeSystemPrompt, compositeTelemetry, containerFloor, customAuth, customTelemetry, defineAgent, defineSkill, defineSwarm, defineTool, ev, isEvent, resolveTelemetry };