@nightowlsdev/engine-ai-sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,210 @@
+import { EngineCapabilities, Engine, AssembledEngineOpts, RunInput, SwarmContext, SwarmEvent, SwarmMessage, ThreadSummary, ScratchpadEntry, ActiveRun, AgentSummary } from '@nightowlsdev/core';
+
+/**
+ * The AI-SDK-native engine's static capability descriptor (P3 v0). Tier 3 declared with
+ * `swarm.handoff` absent from `emits` — handoff is delegation-only (this engine's `delegation` is
+ * `false`); `emits` is authoritative over the declared tier for which events actually stream.
+ *
+ * Kept in its OWN module (not `index.ts`) so `src/engine.ts` (Task 5+) can import it without a
+ * circular dependency once `index.ts`'s `aiSdkEngine()` factory constructs `AiSdkEngine` directly
+ * (Task 10) — `index.ts` re-exports this same constant, so the public export path
+ * (`@nightowlsdev/engine-ai-sdk`'s `AI_SDK_ENGINE_CAPABILITIES`) is unchanged.
+ */
+declare const AI_SDK_ENGINE_CAPABILITIES: EngineCapabilities;
+
+/**
+ * The AI-SDK-native engine (P3) — a governed `ai@^6` `streamText` turn loop behind the `Engine` seam, single-
+ * agent v1 (no delegation/workflows). `run()` carries the full pre-loop + lifecycle scaffolding (rows, floor
+ * serialization, the preGeneration reserve, the persisted-not-yielded user message, telemetry spans); `resume()`
+ * recovers a parked run's snapshot, turns the human/approval/client answer into the tool-call's result, and
+ * re-enters the SAME governed loop (`drive()`) from there. Both share `drive()`: tool assembly (Task 4),
+ * system-prompt assembly (Task 3), the `streamText` multi-step loop, per-generation metering + cost caps,
+ * mid-stream cancellation, completion supervision (nudge-on-incomplete), and suspend/resume parking (ask /
+ * native tool approvals / client actions).
+ */
+declare class AiSdkEngine implements Engine {
+    private readonly opts;
+    readonly capabilities: EngineCapabilities;
+    private readonly hooks;
+    private readonly floor;
+    private readonly telemetry;
+    constructor(opts: AssembledEngineOpts, extra: {
+        durable: boolean;
+    });
+    /**
+     * SP2 — the preGeneration DECISION seam, awaited immediately before every model launch. Verbatim mirror of
+     * the reference engine's private `guardGeneration` (`packages/core/src/engine.ts:543-553`): the dispatcher is
+     * fail-closed (a throwing hook ⇒ deny), so this only ever sees a clean allow/deny; a deny THROWS
+     * `ReserveDenied` (re-exported from core, not redefined here) so the caller's model launch never happens and
+     * the run/resume catch-all maps it to a terminal `run_failed` stage `"reserve"` (never the generic
+     * `"exception"`).
+     */
+    private guardGeneration;
+    /**
+     * SP5 truth-fix — resolve whether a tool WILL require approval, for the `swarm.tool_call` event's advisory
+     * `needsApproval` field. Verbatim mirror of the reference engine's private `gatesApproval`
+     * (`packages/core/src/engine.ts:528-534`): the tool's resolved `needsApproval` (its own flag, defaulting by
+     * origin) run through the dispatcher's SYNC `policyDecision` (`ask` ⇒ true). The async `preToolCall` hook can
+     * still escalate a specific call at execute time (that's what actually drives the tool's native pause — see
+     * `tools.ts`'s `buildServerTool`); this is only the truthful baseline the event carries.
+     */
+    private gatesApproval;
+    /**
+     * T9 (T8-review fix) — best-effort recall of the thread's request text for the completion verifier's
+     * `request` param on RESUME (the engine doesn't hold the original prompt there — `resume()` only carries the
+     * suspended tool's answer). Mirrors the reference engine's `recallRequest`, but deliberately the LAST user
+     * turn (not the first): a resume continues whichever prompt MOST RECENTLY triggered this run, not the
+     * thread's opening message. Fail-safe: gated behind `verifyCompletion` (a no-verifier config never pays for
+     * the read) and never throws — any failure yields `""`, matching the reference's own fallback.
+     */
+    private recallRequest;
+    /** Run the completion supervisor (`EngineOpts.verifyCompletion`), FAIL-OPEN: no verifier, or a throwing one,
+     *  yields `{ complete: true }` so a missing/broken judge never traps a run in a verify loop. Mirrors the
+     *  reference engine's private `safeVerify`. */
+    private safeVerify;
+    /** FR-024 — resolve the host's per-run advisory system-context block. FAIL-SAFE: a throwing/rejecting resolver
+     *  is swallowed (logged) and yields no block, so a broken context source never breaks the run. Mirrors the
+     *  reference engine's private `safeSystemContext`. */
+    private safeSystemContext;
+    /** FR-027 — resolve the host's opt-in per-request instruction-only (dynamic/imported) skills, by name.
+     *  FAIL-SAFE: a throwing/rejecting resolver yields no dynamic skills (never breaks the run). No memoization —
+     *  v1 has no delegation, so there is only ever ONE resolution per segment (no sub-agent to share it with);
+     *  re-resolved fresh on every `resume()` segment too (never carried over the suspend boundary). */
+    private safeDynamicSkills;
+    /**
+     * Resolve the CONCRETE model instance for one generation launch: tier routing (a sentinel `modelId` routes to
+     * the configured tier; a concrete pin passes verbatim), THEN the allow-list `opts.model.resolve` (a deny
+     * throws — this is the security-critical re-validation the plan calls out: EVERY resolved id, tier-routed or
+     * not, goes through the allow-list, never just the stored one), THEN `opts.modelFactory`. Mirrors the
+     * reference engine's private `modelFor` (`packages/core/src/mastra-map.ts:284-292`). Called once for the
+     * `streamText` call's outer `model` field AND again from `prepareStep` for EVERY step (including the first) —
+     * so a revoked/rotated allow-list entry is caught mid-run, not just at the top of the segment.
+     */
+    private resolveModel;
+    /** Build this segment's `ToolAssemblyOpts` — identical wiring for `run()` and `resume()` (both rebuild tools
+     *  fresh from the CURRENT agent row; only `runCtx` differs). */
+    private toolAssemblyOpts;
+    /**
+     * The shared governed `streamText` drive — Task 6's loop, generalized so both `run()` (segmentIndex 0) and
+     * `resume()` (segmentIndex = the snapshot's genIndex) call the SAME implementation: per-step metering + cost
+     * caps, mid-stream cancellation, suspend-parking (ask / native tool approvals / client actions), and
+     * completion-supervisor nudging. Returns the segment's terminal outcome as the generator's return value (the
+     * caller captures it via `const outcome = yield* this.drive(...)`); every terminal event (`done`/`run_failed`/
+     * `run_cancelled`/the park's `waiting`+`question`/`client_action`) is yielded from INSIDE this loop — the
+     * caller only needs the returned outcome for its own `onRunEnd` reporting.
+     */
+    private drive;
+    run(input: RunInput, ctx: SwarmContext, signal?: AbortSignal): AsyncIterable<SwarmEvent>;
+    /**
+     * Resume a parked run: `markFollowupAnswered` EARLY (CAS, replay-safe) → `loadSnapshot` → reload the agent
+     * row fresh (same as `run()`) → re-acquire the floor → emit `swarm.answer` → preGeneration re-fire (kind
+     * 'resume', at the snapshot's genIndex) → per-kind append the answer to the snapshot's messages → re-enter
+     * the SHARED `drive()` with rebuilt tools (`approvedToolCallIds` pre-populated on an approval-approve, BEFORE
+     * `buildTools`/`streamText` — Task 4's blocker-fix contract) + restored messages. A re-park persists
+     * `genIndex = (this segment's own segmentIndex) + 1` — the same bookkeeping `drive()` already does for
+     * `run()`'s park, generalized.
+     *
+     * ⚠ `onRunStart` deliberately does NOT fire here — this is a CONTINUATION of the run `onRunStart` already
+     * announced (in `run()`), not a new one. Mirrors the reference (Mastra) engine exactly: `packages/core/src/
+     * engine.ts`'s own `resume()` never calls `this.opts.onRunStart` either (only `run()` does — see that file's
+     * `onRunStart` doc comment: "fires on `run()` only"). A host that seeds per-run state in `onRunStart` gets it
+     * back via `snap.state` → `resumedState` below, so nothing is lost across the suspend/resume boundary.
+     */
+    resume(args: {
+        runId: string;
+        toolCallId: string;
+        followupId: string;
+        answer: unknown;
+        context?: Record<string, unknown>;
+    }, ctx: SwarmContext, signal?: AbortSignal): AsyncIterable<SwarmEvent>;
+    /**
+     * T9 — events-derived thread history (no Mastra memory in this engine: the events log IS the store).
+     * `container(threadId)` resolves the root container; `events.listForContainer` (optional on `StorageAdapter`
+     * — absent ⇒ `[]`, matching the reference's "no memory ⇒ []" degradation) returns the FULL container log
+     * (root + any lane sub-threads), each event tagged with its OWN run's `threadId`. Filtered LANE-EXACT to the
+     * REQUESTED `threadId` (so a root read never leaks a lane's side-chat and vice versa), then folded into
+     * `SwarmMessage[]` by `messagesFromEvents` (structural attribution; decode-only legacy prefix stripping — see
+     * its doc comment). Hard-capped to the most recent `limit` (default 200, mirrors the reference).
+     */
+    history(threadId: string, ctx: SwarmContext, opts?: {
+        limit?: number;
+    }): Promise<SwarmMessage[]>;
+    /** T9 helper — one container's `ThreadSummary`: title = its first (oldest) user message's text, falling back
+     *  to the bare container id (an empty/title-less container, matching the reference's "no Mastra row" fallback
+     *  shape: `{ threadId: container, title: container, lastActivityAt: 0 }`). `lastActivityAt` = the max `seq`
+     *  seen on the container's BARE (non-lane) events (T9-review fix): `seq` is the storage-assigned, GLOBALLY
+     *  monotonic append counter, so a newer run's events always rank above an older run's — whereas `ts` is a
+     *  per-segment ordinal (restarts at 0/1000 every segment, see `emit.ts`) and is meaningless across runs. Same
+     *  seq-over-ts preference the react timeline established (react/timeline.ts). NOT a wall-clock epoch (no
+     *  adapter in the `StorageAdapter` contract exposes one for runs/events) — a recency-ORDERING proxy only.
+     */
+    private threadSummaryFor;
+    /**
+     * T9 — R14 participation-based thread listing (mirrors the reference `listThreads`, minus the Mastra memory
+     * dependency): `runs.listUserContainers` (optional) gives the containers this user has a run in,
+     * newest-active first; each is summarized via `threadSummaryFor` (concurrently, order preserved).
+     * FALLBACK (an adapter without `listUserContainers`): the reference degrades to the CURRENT container under
+     * multi-user (no cross-container Mastra listing to fall back on here either) — a single-entry list for
+     * `ctx.threadId`'s own container.
+     */
+    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).
+     *  Mirrors the reference engine's `scratchpadPublic` verbatim (storage-backed, engine-neutral). */
+    scratchpadPublic(container: string, ctx: SwarmContext): Promise<ScratchpadEntry[]>;
+    /** In-flight runs (running|suspended) for a container + its lanes. Mirrors the reference engine's
+     *  `activeRuns` verbatim (storage-backed, engine-neutral). */
+    activeRuns(container: string, ctx: SwarmContext): Promise<ActiveRun[]>;
+    /** The full, globally-ordered event log for a thread's CONTAINER (all its runs + lane sub-threads) — unlike
+     *  `history()`, NOT lane-filtered: this is the rich raw timeline (tool calls + status, not just messages).
+     *  Mirrors the reference engine's `threadEvents` verbatim (storage-backed, engine-neutral). Returns `[]` when
+     *  the store has no `events.listForContainer`. */
+    threadEvents(threadId: string, ctx: SwarmContext): Promise<SwarmEvent[]>;
+    /**
+     * T9 (REQUIRED on `Engine`) — the tenant's agent roster as wall-safe `AgentSummary[]`: `agents.listSlugs` →
+     * `head` per slug (dropping any slug whose head resolves to `null`, a race with a mid-listing deletion).
+     * `delegateSlugs` is ALWAYS `[]` — a deliberate divergence from the reference engine (which surfaces the
+     * stored `AgentVersion.delegateSlugs`): this engine's `capabilities.delegation` is `false` (v1, single-agent),
+     * so there is no addressable delegate graph to report regardless of what a row happens to store.
+     */
+    listAgents(ctx: SwarmContext): Promise<AgentSummary[]>;
+}
+
+/**
+ * Engine factory for `defineSwarm({ engine: aiSdkEngine() })` — constructs the wired `AiSdkEngine` (a
+ * governed `ai@^6` `streamText` loop, single-agent v1; see `src/engine.ts`). Mirrors the reference
+ * (Mastra) engine's own `durable` ctor param: `durableResume` is a per-INSTANCE capability flip
+ * (`AI_SDK_ENGINE_CAPABILITIES.hitl.durableResume`), never inferred from the injected `StorageAdapter`.
+ * Pass `aiSdkEngine({ durable: true })` only when that storage persists suspend/resume snapshots
+ * CROSS-PROCESS (e.g. `@nightowlsdev/storage-supabase`) — otherwise leave the default `false` so
+ * consumers (mcp-server/runner-background) keep treating `ask`/approval resumes as non-durable.
+ */
+declare function aiSdkEngine({ durable }?: {
+    durable?: boolean;
+}): (opts: AssembledEngineOpts) => Engine;
+/**
+ * The declarative Night Owls plugin manifest consumed by `@nightowlsdev/cli`. STRUCTURALLY matches the CLI's
+ * `NightOwlsPlugin` type but does NOT import it (no dependency cycle): all codegen lives in `@nightowlsdev/cli`;
+ * this adapter stays data-only.
+ */
+declare const nightOwlsPlugin: {
+    readonly name: "engine-ai-sdk";
+    readonly version: "0.0.0";
+    readonly kind: "engine";
+    readonly pkg: "@nightowlsdev/engine-ai-sdk";
+    readonly description: "The AI-SDK-native engine as a named engine package (single-agent v1, governed ai@6 streamText loop).";
+    readonly env: readonly [];
+    readonly config: {
+        readonly import: "import { aiSdkEngine } from \"@nightowlsdev/engine-ai-sdk\";";
+        readonly snippet: "engine = aiSdkEngine();";
+        readonly marker: "engine";
+    };
+    readonly init: (ctx: {
+        cwd: string;
+        log: (m: string) => void;
+    }) => void;
+    readonly commands: readonly [];
+};
+
+export { AI_SDK_ENGINE_CAPABILITIES, AiSdkEngine, aiSdkEngine, nightOwlsPlugin };

package/dist/index.d.ts

@@ -0,0 +1,210 @@
+import { EngineCapabilities, Engine, AssembledEngineOpts, RunInput, SwarmContext, SwarmEvent, SwarmMessage, ThreadSummary, ScratchpadEntry, ActiveRun, AgentSummary } from '@nightowlsdev/core';
+
+/**
+ * The AI-SDK-native engine's static capability descriptor (P3 v0). Tier 3 declared with
+ * `swarm.handoff` absent from `emits` — handoff is delegation-only (this engine's `delegation` is
+ * `false`); `emits` is authoritative over the declared tier for which events actually stream.
+ *
+ * Kept in its OWN module (not `index.ts`) so `src/engine.ts` (Task 5+) can import it without a
+ * circular dependency once `index.ts`'s `aiSdkEngine()` factory constructs `AiSdkEngine` directly
+ * (Task 10) — `index.ts` re-exports this same constant, so the public export path
+ * (`@nightowlsdev/engine-ai-sdk`'s `AI_SDK_ENGINE_CAPABILITIES`) is unchanged.
+ */
+declare const AI_SDK_ENGINE_CAPABILITIES: EngineCapabilities;
+
+/**
+ * The AI-SDK-native engine (P3) — a governed `ai@^6` `streamText` turn loop behind the `Engine` seam, single-
+ * agent v1 (no delegation/workflows). `run()` carries the full pre-loop + lifecycle scaffolding (rows, floor
+ * serialization, the preGeneration reserve, the persisted-not-yielded user message, telemetry spans); `resume()`
+ * recovers a parked run's snapshot, turns the human/approval/client answer into the tool-call's result, and
+ * re-enters the SAME governed loop (`drive()`) from there. Both share `drive()`: tool assembly (Task 4),
+ * system-prompt assembly (Task 3), the `streamText` multi-step loop, per-generation metering + cost caps,
+ * mid-stream cancellation, completion supervision (nudge-on-incomplete), and suspend/resume parking (ask /
+ * native tool approvals / client actions).
+ */
+declare class AiSdkEngine implements Engine {
+    private readonly opts;
+    readonly capabilities: EngineCapabilities;
+    private readonly hooks;
+    private readonly floor;
+    private readonly telemetry;
+    constructor(opts: AssembledEngineOpts, extra: {
+        durable: boolean;
+    });
+    /**
+     * SP2 — the preGeneration DECISION seam, awaited immediately before every model launch. Verbatim mirror of
+     * the reference engine's private `guardGeneration` (`packages/core/src/engine.ts:543-553`): the dispatcher is
+     * fail-closed (a throwing hook ⇒ deny), so this only ever sees a clean allow/deny; a deny THROWS
+     * `ReserveDenied` (re-exported from core, not redefined here) so the caller's model launch never happens and
+     * the run/resume catch-all maps it to a terminal `run_failed` stage `"reserve"` (never the generic
+     * `"exception"`).
+     */
+    private guardGeneration;
+    /**
+     * SP5 truth-fix — resolve whether a tool WILL require approval, for the `swarm.tool_call` event's advisory
+     * `needsApproval` field. Verbatim mirror of the reference engine's private `gatesApproval`
+     * (`packages/core/src/engine.ts:528-534`): the tool's resolved `needsApproval` (its own flag, defaulting by
+     * origin) run through the dispatcher's SYNC `policyDecision` (`ask` ⇒ true). The async `preToolCall` hook can
+     * still escalate a specific call at execute time (that's what actually drives the tool's native pause — see
+     * `tools.ts`'s `buildServerTool`); this is only the truthful baseline the event carries.
+     */
+    private gatesApproval;
+    /**
+     * T9 (T8-review fix) — best-effort recall of the thread's request text for the completion verifier's
+     * `request` param on RESUME (the engine doesn't hold the original prompt there — `resume()` only carries the
+     * suspended tool's answer). Mirrors the reference engine's `recallRequest`, but deliberately the LAST user
+     * turn (not the first): a resume continues whichever prompt MOST RECENTLY triggered this run, not the
+     * thread's opening message. Fail-safe: gated behind `verifyCompletion` (a no-verifier config never pays for
+     * the read) and never throws — any failure yields `""`, matching the reference's own fallback.
+     */
+    private recallRequest;
+    /** Run the completion supervisor (`EngineOpts.verifyCompletion`), FAIL-OPEN: no verifier, or a throwing one,
+     *  yields `{ complete: true }` so a missing/broken judge never traps a run in a verify loop. Mirrors the
+     *  reference engine's private `safeVerify`. */
+    private safeVerify;
+    /** FR-024 — resolve the host's per-run advisory system-context block. FAIL-SAFE: a throwing/rejecting resolver
+     *  is swallowed (logged) and yields no block, so a broken context source never breaks the run. Mirrors the
+     *  reference engine's private `safeSystemContext`. */
+    private safeSystemContext;
+    /** FR-027 — resolve the host's opt-in per-request instruction-only (dynamic/imported) skills, by name.
+     *  FAIL-SAFE: a throwing/rejecting resolver yields no dynamic skills (never breaks the run). No memoization —
+     *  v1 has no delegation, so there is only ever ONE resolution per segment (no sub-agent to share it with);
+     *  re-resolved fresh on every `resume()` segment too (never carried over the suspend boundary). */
+    private safeDynamicSkills;
+    /**
+     * Resolve the CONCRETE model instance for one generation launch: tier routing (a sentinel `modelId` routes to
+     * the configured tier; a concrete pin passes verbatim), THEN the allow-list `opts.model.resolve` (a deny
+     * throws — this is the security-critical re-validation the plan calls out: EVERY resolved id, tier-routed or
+     * not, goes through the allow-list, never just the stored one), THEN `opts.modelFactory`. Mirrors the
+     * reference engine's private `modelFor` (`packages/core/src/mastra-map.ts:284-292`). Called once for the
+     * `streamText` call's outer `model` field AND again from `prepareStep` for EVERY step (including the first) —
+     * so a revoked/rotated allow-list entry is caught mid-run, not just at the top of the segment.
+     */
+    private resolveModel;
+    /** Build this segment's `ToolAssemblyOpts` — identical wiring for `run()` and `resume()` (both rebuild tools
+     *  fresh from the CURRENT agent row; only `runCtx` differs). */
+    private toolAssemblyOpts;
+    /**
+     * The shared governed `streamText` drive — Task 6's loop, generalized so both `run()` (segmentIndex 0) and
+     * `resume()` (segmentIndex = the snapshot's genIndex) call the SAME implementation: per-step metering + cost
+     * caps, mid-stream cancellation, suspend-parking (ask / native tool approvals / client actions), and
+     * completion-supervisor nudging. Returns the segment's terminal outcome as the generator's return value (the
+     * caller captures it via `const outcome = yield* this.drive(...)`); every terminal event (`done`/`run_failed`/
+     * `run_cancelled`/the park's `waiting`+`question`/`client_action`) is yielded from INSIDE this loop — the
+     * caller only needs the returned outcome for its own `onRunEnd` reporting.
+     */
+    private drive;
+    run(input: RunInput, ctx: SwarmContext, signal?: AbortSignal): AsyncIterable<SwarmEvent>;
+    /**
+     * Resume a parked run: `markFollowupAnswered` EARLY (CAS, replay-safe) → `loadSnapshot` → reload the agent
+     * row fresh (same as `run()`) → re-acquire the floor → emit `swarm.answer` → preGeneration re-fire (kind
+     * 'resume', at the snapshot's genIndex) → per-kind append the answer to the snapshot's messages → re-enter
+     * the SHARED `drive()` with rebuilt tools (`approvedToolCallIds` pre-populated on an approval-approve, BEFORE
+     * `buildTools`/`streamText` — Task 4's blocker-fix contract) + restored messages. A re-park persists
+     * `genIndex = (this segment's own segmentIndex) + 1` — the same bookkeeping `drive()` already does for
+     * `run()`'s park, generalized.
+     *
+     * ⚠ `onRunStart` deliberately does NOT fire here — this is a CONTINUATION of the run `onRunStart` already
+     * announced (in `run()`), not a new one. Mirrors the reference (Mastra) engine exactly: `packages/core/src/
+     * engine.ts`'s own `resume()` never calls `this.opts.onRunStart` either (only `run()` does — see that file's
+     * `onRunStart` doc comment: "fires on `run()` only"). A host that seeds per-run state in `onRunStart` gets it
+     * back via `snap.state` → `resumedState` below, so nothing is lost across the suspend/resume boundary.
+     */
+    resume(args: {
+        runId: string;
+        toolCallId: string;
+        followupId: string;
+        answer: unknown;
+        context?: Record<string, unknown>;
+    }, ctx: SwarmContext, signal?: AbortSignal): AsyncIterable<SwarmEvent>;
+    /**
+     * T9 — events-derived thread history (no Mastra memory in this engine: the events log IS the store).
+     * `container(threadId)` resolves the root container; `events.listForContainer` (optional on `StorageAdapter`
+     * — absent ⇒ `[]`, matching the reference's "no memory ⇒ []" degradation) returns the FULL container log
+     * (root + any lane sub-threads), each event tagged with its OWN run's `threadId`. Filtered LANE-EXACT to the
+     * REQUESTED `threadId` (so a root read never leaks a lane's side-chat and vice versa), then folded into
+     * `SwarmMessage[]` by `messagesFromEvents` (structural attribution; decode-only legacy prefix stripping — see
+     * its doc comment). Hard-capped to the most recent `limit` (default 200, mirrors the reference).
+     */
+    history(threadId: string, ctx: SwarmContext, opts?: {
+        limit?: number;
+    }): Promise<SwarmMessage[]>;
+    /** T9 helper — one container's `ThreadSummary`: title = its first (oldest) user message's text, falling back
+     *  to the bare container id (an empty/title-less container, matching the reference's "no Mastra row" fallback
+     *  shape: `{ threadId: container, title: container, lastActivityAt: 0 }`). `lastActivityAt` = the max `seq`
+     *  seen on the container's BARE (non-lane) events (T9-review fix): `seq` is the storage-assigned, GLOBALLY
+     *  monotonic append counter, so a newer run's events always rank above an older run's — whereas `ts` is a
+     *  per-segment ordinal (restarts at 0/1000 every segment, see `emit.ts`) and is meaningless across runs. Same
+     *  seq-over-ts preference the react timeline established (react/timeline.ts). NOT a wall-clock epoch (no
+     *  adapter in the `StorageAdapter` contract exposes one for runs/events) — a recency-ORDERING proxy only.
+     */
+    private threadSummaryFor;
+    /**
+     * T9 — R14 participation-based thread listing (mirrors the reference `listThreads`, minus the Mastra memory
+     * dependency): `runs.listUserContainers` (optional) gives the containers this user has a run in,
+     * newest-active first; each is summarized via `threadSummaryFor` (concurrently, order preserved).
+     * FALLBACK (an adapter without `listUserContainers`): the reference degrades to the CURRENT container under
+     * multi-user (no cross-container Mastra listing to fall back on here either) — a single-entry list for
+     * `ctx.threadId`'s own container.
+     */
+    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).
+     *  Mirrors the reference engine's `scratchpadPublic` verbatim (storage-backed, engine-neutral). */
+    scratchpadPublic(container: string, ctx: SwarmContext): Promise<ScratchpadEntry[]>;
+    /** In-flight runs (running|suspended) for a container + its lanes. Mirrors the reference engine's
+     *  `activeRuns` verbatim (storage-backed, engine-neutral). */
+    activeRuns(container: string, ctx: SwarmContext): Promise<ActiveRun[]>;
+    /** The full, globally-ordered event log for a thread's CONTAINER (all its runs + lane sub-threads) — unlike
+     *  `history()`, NOT lane-filtered: this is the rich raw timeline (tool calls + status, not just messages).
+     *  Mirrors the reference engine's `threadEvents` verbatim (storage-backed, engine-neutral). Returns `[]` when
+     *  the store has no `events.listForContainer`. */
+    threadEvents(threadId: string, ctx: SwarmContext): Promise<SwarmEvent[]>;
+    /**
+     * T9 (REQUIRED on `Engine`) — the tenant's agent roster as wall-safe `AgentSummary[]`: `agents.listSlugs` →
+     * `head` per slug (dropping any slug whose head resolves to `null`, a race with a mid-listing deletion).
+     * `delegateSlugs` is ALWAYS `[]` — a deliberate divergence from the reference engine (which surfaces the
+     * stored `AgentVersion.delegateSlugs`): this engine's `capabilities.delegation` is `false` (v1, single-agent),
+     * so there is no addressable delegate graph to report regardless of what a row happens to store.
+     */
+    listAgents(ctx: SwarmContext): Promise<AgentSummary[]>;
+}
+
+/**
+ * Engine factory for `defineSwarm({ engine: aiSdkEngine() })` — constructs the wired `AiSdkEngine` (a
+ * governed `ai@^6` `streamText` loop, single-agent v1; see `src/engine.ts`). Mirrors the reference
+ * (Mastra) engine's own `durable` ctor param: `durableResume` is a per-INSTANCE capability flip
+ * (`AI_SDK_ENGINE_CAPABILITIES.hitl.durableResume`), never inferred from the injected `StorageAdapter`.
+ * Pass `aiSdkEngine({ durable: true })` only when that storage persists suspend/resume snapshots
+ * CROSS-PROCESS (e.g. `@nightowlsdev/storage-supabase`) — otherwise leave the default `false` so
+ * consumers (mcp-server/runner-background) keep treating `ask`/approval resumes as non-durable.
+ */
+declare function aiSdkEngine({ durable }?: {
+    durable?: boolean;
+}): (opts: AssembledEngineOpts) => Engine;
+/**
+ * The declarative Night Owls plugin manifest consumed by `@nightowlsdev/cli`. STRUCTURALLY matches the CLI's
+ * `NightOwlsPlugin` type but does NOT import it (no dependency cycle): all codegen lives in `@nightowlsdev/cli`;
+ * this adapter stays data-only.
+ */
+declare const nightOwlsPlugin: {
+    readonly name: "engine-ai-sdk";
+    readonly version: "0.0.0";
+    readonly kind: "engine";
+    readonly pkg: "@nightowlsdev/engine-ai-sdk";
+    readonly description: "The AI-SDK-native engine as a named engine package (single-agent v1, governed ai@6 streamText loop).";
+    readonly env: readonly [];
+    readonly config: {
+        readonly import: "import { aiSdkEngine } from \"@nightowlsdev/engine-ai-sdk\";";
+        readonly snippet: "engine = aiSdkEngine();";
+        readonly marker: "engine";
+    };
+    readonly init: (ctx: {
+        cwd: string;
+        log: (m: string) => void;
+    }) => void;
+    readonly commands: readonly [];
+};
+
+export { AI_SDK_ENGINE_CAPABILITIES, AiSdkEngine, aiSdkEngine, nightOwlsPlugin };