@nightowlsdev/core 0.3.0 → 0.5.0

package/dist/index.d.cts

@@ -1,4 +1,175 @@
 import { z } from 'zod';
+import { HookDispatcher, ToolApprovalPolicy, SwarmHooks } from '@nightowlsdev/hooks';
+export { ALLOW, ALLOW_TOOL, DEFAULT_READ_ONLY_TOOLS, GuardMutationEvent, GuardMutationHook, HookDecision, HookDispatcher, PreGenerationEvent, PreGenerationHook, PreToolCallHook, SwarmHooks, ToolApprovalPolicy, ToolDecision, ToolPreCallEvent, ask, createHookDispatcher, defineHook, deny } from '@nightowlsdev/hooks';
+
+interface Price {
+    inUsdPerMtok: number;
+    outUsdPerMtok: number;
+    /**
+     * Per-class USD rates per million tokens (SP1). All OPTIONAL + additive — a price entry without them
+     * prices exactly like before. When a class's rate is absent the engine falls back to the closest base
+     * rate, picked to match how providers bill these classes:
+     *   - `cacheReadUsdPerMtok`  → falls back to `inUsdPerMtok`  (cache reads are discounted input; absent a
+     *      discount rate we conservatively bill them at the full input rate rather than free).
+     *   - `cacheWriteUsdPerMtok` → falls back to `inUsdPerMtok`  (cache writes are an input-side surcharge).
+     *   - `reasoningUsdPerMtok`  → falls back to `outUsdPerMtok` (reasoning tokens are generated output).
+     */
+    cacheReadUsdPerMtok?: number;
+    cacheWriteUsdPerMtok?: number;
+    reasoningUsdPerMtok?: number;
+}
+/**
+ * Per-generation usage, by token class (SP1). `inputTokens`/`outputTokens` are always present (today's
+ * shape); the rest are OPTIONAL — a provider that does not report a class leaves it undefined and it is
+ * priced as zero (NEVER fabricated). `toolCalls`/`agentActivations` are activity counts for telemetry,
+ * not priced. Plain domain type — @mastra-free (engine wall, CONTRACTS §1).
+ */
+interface UsageBreakdown {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    reasoningTokens?: number;
+    /** Number of (non-delegation) tool calls in this generation. Telemetry only — not priced. */
+    toolCalls?: number;
+    /** Number of sub-agent delegations (`agent-<slug>` calls) in this generation. Telemetry only — not priced. */
+    agentActivations?: number;
+}
+/** A priced usage: the computed USD plus the breakdown it was priced from. */
+interface UsageCost {
+    usd: number;
+    breakdown: UsageBreakdown;
+}
+/**
+ * Optional seam that supplies/overrides per-model prices (SP1). Supplies NUMBERS only (no @mastra) so the
+ * engine wall holds. `prices()` returns a full `modelId → Price` map merged over the built-in `PRICE_TABLE`
+ * + any static `prices` config; a host can back it with a live price feed. Sync to keep governor construction
+ * synchronous on the hot path — resolve/refresh out of band and return the current snapshot here.
+ */
+interface PriceFeed {
+    prices(): Record<string, Price>;
+}
+declare const PRICE_TABLE: Record<string, Price>;
+/** Options shared by the pricing helpers + the governors that thread pricing config through. */
+interface PricingOpts {
+    /**
+     * When TRUE an unpriced `modelId` THROWS instead of pricing at $0. Default FALSE so OSS users (the
+     * built-in `PRICE_TABLE` has only 2 entries) are not broken — an unknown model keeps the historical
+     * $0 fallback (the cost cap simply can't fire on it). A host that wants billing safety flips this on.
+     */
+    failOnUnknownModel?: boolean;
+}
+/** Price one usage at a model's rate, across EVERY token class (SP1). Shared by the global CostGovernor and
+ *  per-delegate DelegateBudgets so the two caps always agree on what a token costs. Each class is priced at
+ *  its explicit per-class rate, with the documented fallbacks (see `Price`) when a rate is absent; a token
+ *  class the provider omitted is treated as zero (never fabricated). An unknown model prices at $0 by default
+ *  (the cap can't fire on a model with no price entry — historical behavior) unless `failOnUnknownModel`. */
+declare function priceUsage(prices: Record<string, Price>, modelId: string, u: UsageBreakdown, opts?: PricingOpts): number;
+/**
+ * Sum a list of `UsageBreakdown` into a single turn-total breakdown (SP4 — the room-turn billing unit).
+ * The always-present base classes (`inputTokens`/`outputTokens`) sum as plain numbers. Each OPTIONAL class
+ * (cacheRead/cacheWrite/reasoning/toolCalls/agentActivations) sums with UNDEFINED as the additive identity:
+ *   - undefined + number → the number (a class present in only some generations still totals correctly),
+ *   - all-undefined      → stays UNDEFINED (we never fabricate a class no provider reported as a zero),
+ *   - present-and-zero   → preserved as 0 (an explicit 0 means "reported zero", distinct from "not reported").
+ * An empty list yields the zero base breakdown `{ inputTokens: 0, outputTokens: 0 }`. @mastra-free.
+ */
+declare function sumBreakdowns(items: UsageBreakdown[]): UsageBreakdown;
+/** One generation's priced usage attributed to an agent slug — the unit the turn aggregates over. */
+interface SlugUsage {
+    slug: string;
+    breakdown: UsageBreakdown;
+    cost: UsageCost;
+}
+/** A room-turn's aggregate usage (SP4): the summed breakdown + summed USD for the WHOLE turn, plus a
+ *  per-agent-slug split so the platform can attribute credits per agent. `bySlug` is in first-seen order. */
+interface TurnUsage {
+    breakdown: UsageBreakdown;
+    cost: UsageCost;
+    bySlug: SlugUsage[];
+}
+/**
+ * Aggregate every generation's `(slug, breakdown, cost)` over a room-turn into ONE turn total + a per-slug
+ * split (SP4). The turn total breakdown/USD are the sum across ALL generations; `bySlug` folds every
+ * generation of the same slug into one entry (so a slug that generated twice — e.g. an orchestrator before
+ * and after a delegation — appears once with its combined breakdown/USD), in FIRST-SEEN order for a stable
+ * split. By construction the per-slug entries sum back to the turn total (the invariant the platform's
+ * per-agent credit attribution relies on). An empty list yields a zero total + empty split. @mastra-free.
+ */
+declare function sumTurnUsage(items: SlugUsage[]): TurnUsage;
+declare class CostGovernor {
+    private opts;
+    private steps;
+    private usd;
+    private prices;
+    private failOnUnknownModel;
+    constructor(opts: {
+        maxSteps: number;
+        maxCostUsd: number;
+        /** Static per-model price overrides, merged over PRICE_TABLE. */
+        prices?: Record<string, Price>;
+        /** Optional live price seam (SP1). Merged OVER `prices` (a feed entry wins) at construction. */
+        priceFeed?: PriceFeed;
+    } & PricingOpts);
+    step(): void;
+    /** Price a single usage WITHOUT accumulating it (for per-generation telemetry cost). */
+    priceOf(modelId: string, u: UsageBreakdown): number;
+    /** Price a single usage WITHOUT accumulating it, returning the usd + the breakdown it was priced from. */
+    costOf(modelId: string, u: UsageBreakdown): UsageCost;
+    addUsage(modelId: string, u: UsageBreakdown): void;
+    costUsd(): number;
+    /** The current USD cap (SP9-core: the cap-that-asks reads this to surface "spend / cap" + to compute the raise). */
+    get maxCostUsd(): number;
+    /**
+     * SP9-core — RAISE the USD cap by `incrementUsd` (the budget an approved "Budget cap reached — continue?"
+     * grants). Mutates the governor's ceiling so a freshly-resumed generation isn't immediately re-blocked at the
+     * SAME cap; the run gets real additional headroom. Only the cap-that-asks resume path calls this; the default
+     * terminal-stop path never does, so today's behaviour is unchanged.
+     */
+    raiseCostCap(incrementUsd: number): void;
+    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;
+    private failOnUnknownModel;
+    constructor(cfg: PerDelegateBudget, rootSlug: string, pricing?: {
+        prices?: Record<string, Price>;
+        priceFeed?: PriceFeed;
+    } & PricingOpts);
+    /** 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: UsageBreakdown): void;
+    /** The first delegate that has met or exceeded its USD cap, or null. */
+    exceeded(): {
+        slug: string;
+        reason: string;
+    } | null;
+}
 
 interface SwarmContext {
     tenantId: string;
@@ -17,8 +188,63 @@ interface AuthProvider {
     authenticate(req: Request): Promise<AuthContext | null>;
     can?(ctx: AuthContext, capability: string): boolean | Promise<boolean>;
 }
+/**
+ * The PRINCIPAL performing a definition mutation (SP6) — a plain (@mastra-free) discriminated union covering
+ * every kind of actor that can publish/rollback an agent definition. Distinct from `AuthContext` (the run's
+ * end-user identity): an actor models WHO is mutating the swarm's own code, which may be a human in the
+ * no-code builder, a service (CI/seeding pipeline), or a system task.
+ *
+ *   - `human`   → a person acting in a tenant (the no-code builder's authenticated user).
+ *   - `service` → a non-human automation acting in a tenant (CI, a seeding job, a migration runner).
+ *   - `system`  → an internal/un-tenanted operation (bootstrap seed, ops rollback) carrying a `reason`.
+ *   - `agent`   → an AGENT acting on its own behalf. This variant exists for ONE reason: so an agent
+ *                 principal is REPRESENTABLE and can therefore be UNCONDITIONALLY BARRED from mutating a
+ *                 definition (an agent must never be able to rewrite the swarm's own code). The bar is
+ *                 enforced in the repo contract layer (`assertActorMayMutateDefinition`) and CANNOT be
+ *                 overridden by any policy/hook. No code should ever construct an `agent` actor expecting a
+ *                 mutation to succeed — it is the deny sentinel.
+ */
+type SwarmActor = {
+    type: "human";
+    userId: string;
+    tenantId: string;
+} | {
+    type: "service";
+    serviceId: string;
+    tenantId: string;
+} | {
+    type: "system";
+    reason: string;
+} | {
+    type: "agent";
+    agentSlug: string;
+    tenantId: string;
+};
+/**
+ * The NON-BYPASSABLE security invariant for definition mutations (SP6): an `agent` principal can NEVER
+ * publish or roll back an agent definition, regardless of any configured policy/hook. Every writable-repo
+ * mutation path MUST call this FIRST (before the `guardDefinitionMutation` policy hook) so the bar cannot be
+ * weakened by an allow-all hook. Throws `AgentMutationForbidden` for an `agent` actor; a no-op otherwise.
+ *
+ * This lives in the contract layer (not behind a hook) on purpose: the hook is removable/host-configurable
+ * policy, whereas this bar is a framework invariant — fail-closed and non-negotiable.
+ */
+declare function assertActorMayMutateDefinition(actor: SwarmActor): void;
+/** Thrown by `assertActorMayMutateDefinition` when an `agent` principal attempts a definition mutation. A
+ *  named class so callers can distinguish the security bar from an ordinary failure (e.g. a missing version). */
+declare class AgentMutationForbidden extends Error {
+    readonly code: "AGENT_MUTATION_FORBIDDEN";
+    constructor(agentSlug: string);
+}
+/**
+ * The seam a platform vault (SP15-platform) implements: given a secret `ref` + the RUN's identity ctx, it
+ * supplies the secret VALUE. @mastra-free. Resolution is execution-time + ctx-scoped (the connector calls it at
+ * tool-call time with the live run ctx — see @nightowlsdev/mcp connector.ts), so the vault enforces per-tenant
+ * scoping off `ctx.tenantId`: a run must NOT be able to resolve another tenant's secret. Returns `undefined` for
+ * an unknown ref (a tool then sees "no secret") — the resolver should never leak across tenants.
+ */
 interface SecretResolver {
-    resolve(ref: string, ctx: SwarmContext): Promise<string>;
+    resolve(ref: string, ctx: SwarmContext): Promise<string | undefined>;
 }
 /** 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,
@@ -54,6 +280,9 @@ interface EvBase {
     ts: number;
     seq?: number;
     schemaVersion: 1;
+    /** The run's thread (the lane this event belongs to). NOT set on live events — the store fills it in on a
+     *  container restore (listForContainer) so a client can tell a lane side-chat apart from the main thread. */
+    threadId?: string;
 }
 type SwarmEvent = (EvBase & {
     type: "swarm.status";
@@ -65,7 +294,7 @@ type SwarmEvent = (EvBase & {
 }) | (EvBase & {
     type: "swarm.message";
     data: {
-        role: "assistant";
+        role: "assistant" | "user";
         delta?: string;
         text?: string;
     };
@@ -92,6 +321,16 @@ type SwarmEvent = (EvBase & {
         result?: unknown;
         error?: string;
     };
+}) | (EvBase & {
+    type: "swarm.client_action";
+    data: {
+        followupId: string;
+        toolCallId: string;
+        tool: string;
+        input: unknown;
+        needsApproval: boolean;
+        from: string;
+    };
 }) | (EvBase & {
     type: "swarm.question";
     data: {
@@ -110,6 +349,32 @@ type SwarmEvent = (EvBase & {
         from: "user" | string;
         answer: unknown;
     };
+}) | (EvBase & {
+    type: "swarm.usage";
+    data: {
+        slug: string;
+        modelId: string;
+        breakdown: UsageBreakdown;
+        cost: UsageCost;
+        generationId: string;
+    };
+}) | (EvBase & {
+    type: "swarm.turn_usage";
+    data: {
+        breakdown: UsageBreakdown;
+        cost: UsageCost;
+        bySlug: Array<{
+            slug: string;
+            breakdown: UsageBreakdown;
+            cost: UsageCost;
+        }>;
+        generations: number;
+        /** The segment's STARTING generation index — distinct per run/resume segment AND retry-stable (it's the
+         *  monotonic, snapshot-persisted generation counter, not a fresh per-append seq). A host keys a PER-TURN
+         *  billing debit on it so each segment of a suspend/resume run is charged exactly once (run segment = 0;
+         *  each resume = the snapshot's next genIndex). The engine never prices — this is just a stable turn id. */
+        segmentIndex: number;
+    };
 }) | (EvBase & {
     type: "swarm.run_failed";
     data: {
@@ -142,6 +407,118 @@ interface AgentMemoryOverride {
     };
     observationalMemory?: boolean | Record<string, unknown>;
 }
+/** Enforcement level a rule declares. `advise` = prompt-injected guidance; `enforce` = decision-hook veto. */
+type RuleLevel = "advise" | "enforce";
+/** Declarative match over a hook event. Empty = match-all within the resolved seam. */
+interface RuleCondition {
+    /** agentSlug glob/exact. For a delegation the gate sees the PARENT (orchestrator) slug. */
+    agent?: string | string[];
+    /** toolName glob/exact (tool seam). */
+    tool?: string | string[];
+    /** tool provenance. */
+    origin?: "first-party" | "mcp";
+    /** modelId glob/exact (generation seam). */
+    model?: string | string[];
+}
+interface RuleAction {
+    do: "deny" | "ask";
+    reason?: string;
+}
+interface RuleSpec {
+    id: string;
+    statement: string;
+    when: RuleCondition;
+    level: RuleLevel;
+    /** REQUIRED when level==="enforce". `ask` is TOOL-SEAM ONLY (preGeneration cannot suspend). */
+    action?: RuleAction;
+    /** Seam; inferred from `when` when omitted (model ⇒ generation, else tool). */
+    on?: "tool" | "generation";
+}
+/** A normalized, engine-held rule (the output of `defineRule`). */
+interface RuleDef {
+    id: string;
+    statement: string;
+    when: RuleCondition;
+    level: RuleLevel;
+    action?: RuleAction;
+    /** Resolved seam. */
+    seam: "tool" | "generation";
+    /** Set when authored via `defineAgent` (per-agent scope); undefined ⇒ swarm-wide. */
+    scopeAgent?: string;
+}
+/** Workflow compliance. v1: `advisory` (prompt) | `strict` (driver, Phase B — rejected by defineSwarm in Phase A). */
+type WorkflowCompliance = "advisory" | "strict";
+/** A flat data reference resolved at runtime: `{ $ref: "input" }` | `{ $ref: "steps.<id>" }`. */
+type WorkflowRef = {
+    $ref: string;
+};
+interface WorkflowTransition {
+    to: string;
+    when?: {
+        $ref: string;
+        eq?: unknown;
+        exists?: boolean;
+    };
+}
+interface WorkflowStep {
+    id: string;
+    /** exactly ONE kind: */
+    agent?: string;
+    tool?: string;
+    human?: {
+        prompt: string;
+        field?: AskField;
+    };
+    /** agent steps: */
+    instruction?: string;
+    /** tool steps (values may be a WorkflowRef): */
+    args?: Record<string, unknown>;
+    /** agent steps (values may be a WorkflowRef): */
+    input?: Record<string, unknown>;
+    next?: string | WorkflowTransition[];
+    onError?: "fail" | {
+        to: string;
+    } | {
+        retry: number;
+    };
+}
+interface WorkflowSpec {
+    name: string;
+    compliance: WorkflowCompliance;
+    description?: string;
+    steps: WorkflowStep[];
+    start?: string;
+}
+/** A normalized, engine-held workflow (the output of `defineWorkflow`). */
+interface WorkflowDef {
+    name: string;
+    compliance: WorkflowCompliance;
+    description?: string;
+    steps: WorkflowStep[];
+    /** Resolved start step id (default: steps[0].id). */
+    start: string;
+    /** Set when authored via `defineAgent.workflow` (per-agent scope). */
+    scopeAgent?: string;
+}
+/**
+ * The durable state of an in-flight STRICT workflow run (Phase B). Rides the existing run snapshot payload
+ * (not a new table). `cursor` = the step to run next; `outputs` = accumulated step results (for `$ref`);
+ * `generationIndex` = the monotonic per-run reserve counter continued across steps; `pending` marks a
+ * human/approval suspend so `resume()` re-enters the driver (synthetic `followupId`+`toolCallId` satisfy the
+ * resume-auth cross-check). Progress snapshotting only — NOT crash-mid-step replay.
+ */
+interface WorkflowRunState {
+    workflow: string;
+    cursor: string;
+    outputs: Record<string, unknown>;
+    generationIndex: number;
+    pending?: {
+        kind: "human" | "approval";
+        stepId: string;
+        followupId: string;
+        toolCallId: string;
+    };
+}
 interface AgentDef {
     slug: string;
     head: AgentVersion;
@@ -154,6 +531,82 @@ interface AgentDef {
     skills?: {
         name: string;
     }[];
+    /** Per-agent rules (engine-local, v1) — `defineAgent` stamps `scopeAgent` so `defineSwarm` can collect them. */
+    rules?: RuleDef[];
+    /** Per-agent workflow/procedure (engine-local, v1) — `scopeAgent`-stamped by `defineAgent`. */
+    workflow?: WorkflowDef;
+}
+/** A closure dependency satisfied by ANOTHER bundle: a delegate slug that is not a member of this bundle. Carried
+ *  as a flat min-version floor (no transitive resolution in v1). */
+interface BundleDep {
+    slug: string;
+    minVersion: number;
+}
+/**
+ * BN1 — a declarative connector grant: a member may invoke a connector's actions. The action names are folded into
+ * that member's `skillNames`, so the host's connector-tools resolver (`SwarmConfig.connectorTools`) materializes
+ * them per-tenant at CALL time, gated by the SP5 approval floor. The bundle carries NAMES ONLY — never a token,
+ * connection id, or backend; the host wires the connector + per-tenant credentials. A granted action need not have
+ * a first-party skill handle (it is connector-backed), so it is the explicit, validated exception to BN0's
+ * "every skill must resolve to a handle" closure rule.
+ */
+interface ConnectorGrant {
+    /** The bundle member granted these actions (must be one of the bundle's `agents`). */
+    agentSlug: string;
+    /** The connector provider, e.g. `"slack"` — informational, and the prefix used to expand a short action name. */
+    provider: string;
+    /** Connector action names — full (`"slack.post_message"`) or short (`"post_message"`, expanded to `provider.action`). */
+    actions: string[];
+}
+/** Authoring input for `defineBundle`. It composes `defineAgent` OUTPUTS — it does not replace them. */
+interface BundleSpec {
+    slug: string;
+    title?: string;
+    /** The composed members — exactly the output of `defineAgent` (skill handles ride along on each `AgentDef`). */
+    agents: AgentDef[];
+    /** SWARM-scoped rules (per-agent rules ride on the `AgentDef`s via `defineAgent`'s `scopeAgent` stamp). */
+    rules?: RuleDef[];
+    /** SWARM-scoped workflows (per-agent workflows ride on the `AgentDef`s). */
+    workflows?: WorkflowDef[];
+    /** BN1 — connector grants: a member may invoke a provider's actions (names only; the host materializes them). */
+    connectorGrants?: ConnectorGrant[];
+    /** Delegates that live in ANOTHER bundle (a delegate slug not among `agents`) — declared so closure validation
+     *  can distinguish a legitimate external dependency from a typo. */
+    requires?: BundleDep[];
+}
+/** The validated, closure-checked composition `mergeBundle` folds into a `SwarmConfig`. The members carry any
+ *  BN1 connector-grant action names folded into their `skillNames`. */
+interface BundleDef {
+    slug: string;
+    title?: string;
+    agents: AgentDef[];
+    rules: RuleDef[];
+    workflows: WorkflowDef[];
+    connectorGrants: ConnectorGrant[];
+    requires: BundleDep[];
+}
+/** The publishable bundle payload (version is derived, not authored — mirrors `AgentVersionContent`). */
+interface BundleVersionContent {
+    slug: string;
+    title?: string;
+    /** Composed members as serializable heads (no skill handles). */
+    agents: AgentVersionContent[];
+    rules: RuleDef[];
+    workflows: WorkflowDef[];
+    connectorGrants: ConnectorGrant[];
+    requires: BundleDep[];
+}
+/** One immutable, append-only bundle version (mirrors `AgentVersion` one level up). */
+interface BundleVersion extends BundleVersionContent {
+    version: number;
+}
+/** A bundle version's summary row (for `listVersions` — mirrors `AgentVersionInfo`). */
+interface BundleVersionInfo {
+    version: number;
+    title: string;
+    status: string;
+    isCurrent: boolean;
+    memberCount: number;
 }
 interface RunRow {
     runId: string;
@@ -210,6 +663,11 @@ 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[]>;
+    /** The full event log for a CONTAINER — every run in the conversation (the root thread + lane sub-threads
+     *  `<container>:<slug>`), globally ordered by the generated `seq`. Lets a host rebuild a thread's RICH timeline
+     *  (tool calls + delegation cards) on reload, where message-history is text-only. Tenant-scoped. Optional: a
+     *  store without an events table may omit it (the host then falls back to message history). */
+    listForContainer?(tenantId: string, container: string): Promise<SwarmEvent[]>;
     subscribe(runId: string): AsyncIterable<SwarmEvent>;
 }
 interface RunStore {
@@ -247,6 +705,24 @@ interface MessageStore {
      *  `engine.history` (Mastra recall, scoped by resourceId=tenant:user). Kept for contract consistency. */
     history(tenantId: string, threadId: string, limit?: number): Promise<SwarmMessage[]>;
 }
+/** The thread (conversation container) a run references. `runs.thread_id` is a NOT NULL FK to this row, so the
+ *  row MUST exist before the first run/message of a conversation. `ThreadStore.ensure` is the supported,
+ *  schema-private way to create it idempotently — without it a host has to reach into the engine's raw pool and
+ *  hardcode `nightowls.threads`'s columns (FR-009). */
+interface ThreadStore {
+    /**
+     * Idempotently create the thread row a run will reference (insert-or-ignore on `id`). Safe to call before
+     * every run. `orgId` is the tenant; `userId` the conversation owner; `projectId` an optional host-owned
+     * sub-scope. Never throws on a pre-existing row. The engine calls this at run start when the adapter provides
+     * it, so `messages.append` cannot throw `unknown thread` through the supported path.
+     */
+    ensure(spec: {
+        id: string;
+        orgId: string;
+        userId: string;
+        projectId?: string;
+    }): Promise<void>;
+}
 /** Scratchpad caps (intentionally lossy — working memory, not a system of record). */
 declare const SCRATCHPAD_MAX_ENTRY_CHARS = 4000;
 declare const SCRATCHPAD_MAX_KEYS = 64;
@@ -276,11 +752,82 @@ interface AgentRepo {
     getVersion(tenantId: string, slug: string, version: number): Promise<AgentVersion | null>;
     listSlugs(tenantId: string): Promise<string[]>;
 }
+/** The publishable content of one agent version — everything an `AgentVersion` carries EXCEPT the `version`
+ *  number, which is derived (append-only `max+1`) by the repo, never supplied by the caller. */
+type AgentVersionContent = Omit<AgentVersion, "version">;
+/** One row of an agent's version history (for the no-code builder's rollback UX). Plain/@mastra-free. */
+interface AgentVersionInfo {
+    version: number;
+    role: string;
+    modelId: string;
+    status: string;
+    isCurrent: boolean;
+}
+/**
+ * The WRITABLE agent definition contract (SP6) — "the one true framework extension" the no-code builder hangs
+ * off. Extends the read-only `AgentRepo` with the append-only mutation surface:
+ *   - `publish`      → commit a new head version of `content`; returns the derived version number.
+ *   - `rollback`     → republish a prior version's content as a NEW head (append-only, `git revert` not
+ *                      `reset`); returns the new version + the source it was restored from.
+ *   - `listVersions` → the agent's version history (oldest→newest), flagging the current head.
+ *
+ * Every mutation takes a `SwarmActor` (the principal) — NOT a bare string — and the implementation MUST:
+ *   1. call `assertActorMayMutateDefinition(actor)` FIRST (the non-bypassable agent-bar), then
+ *   2. consult the configured `guardDefinitionMutation` policy hook (if any),
+ * before committing. `listVersions` takes the actor too so an impl can authorize reads consistently (and so
+ * the agent-bar applies uniformly); reads do not mutate, so an impl MAY allow an `agent` actor to list, but
+ * the shipped impls apply the same bar for symmetry.
+ */
+interface VersionedRepo extends AgentRepo {
+    publish(tenantId: string, slug: string, content: AgentVersionContent, actor: SwarmActor): Promise<{
+        version: number;
+    }>;
+    rollback(tenantId: string, slug: string, toVersion: number, actor: SwarmActor): Promise<{
+        version: number;
+        restoredFrom: number;
+    }>;
+    listVersions(tenantId: string, slug: string, actor: SwarmActor): Promise<AgentVersionInfo[]>;
+}
+/** BN2 — the read-only bundle version repo (head/getVersion/listSlugs). Structurally identical to `AgentRepo`,
+ *  one level up: a `BundleVersion` is the unit, not an agent. */
+interface BundleRepo {
+    head(tenantId: string, slug: string): Promise<BundleVersion | null>;
+    getVersion(tenantId: string, slug: string, version: number): Promise<BundleVersion | null>;
+    listSlugs(tenantId: string): Promise<string[]>;
+}
+/** BN2 — the WRITABLE bundle version repo (append-only publish/rollback/listVersions). Mirrors `VersionedRepo`;
+ *  every mutation enforces the same non-bypassable actor-bar (an `agent` principal can never publish a bundle). */
+interface BundleWritableRepo extends BundleRepo {
+    publish(tenantId: string, slug: string, content: BundleVersionContent, actor: SwarmActor): Promise<{
+        version: number;
+    }>;
+    rollback(tenantId: string, slug: string, toVersion: number, actor: SwarmActor): Promise<{
+        version: number;
+        restoredFrom: number;
+    }>;
+    listVersions(tenantId: string, slug: string, actor: SwarmActor): Promise<BundleVersionInfo[]>;
+}
 interface StorageAdapter {
+    /** Read-only agent definitions (always present). The supabase adapter's `agents` is also a `VersionedRepo`,
+     *  but the base contract stays `AgentRepo` so a read-only adapter compiles without growing a write path. */
     agents: AgentRepo;
+    /** Opt-in WRITABLE agent definitions (SP6). Present on adapters that back a definition store (the supabase
+     *  adapter); omitted by read-only adapters (storage-local, the in-memory dev store) — a no-code builder
+     *  requires an adapter that provides it. When present it is the SAME object as `agents` (a `VersionedRepo`
+     *  IS an `AgentRepo`), surfaced under a distinct field so the writable surface is explicit + tree-checkable. */
+    agentsWritable?: VersionedRepo;
+    /** BN2 — opt-in WRITABLE bundle versions (append-only, same actor-bar). Present on adapters that back a bundle
+     *  store (the supabase adapter); omitted by read-only/in-memory adapters. `bundles` is the read surface,
+     *  `bundlesWritable` the same object's write surface — mirrors the `agents`/`agentsWritable` pattern. */
+    bundles?: BundleRepo;
+    bundlesWritable?: BundleWritableRepo;
     runs: RunStore;
     events: EventStore;
     messages: MessageStore;
+    /** Opt-in thread (conversation container) creation (FR-009). When present, the engine idempotently ensures the
+     *  run's thread row exists before the first message/event write, so a host need not pre-create it with raw SQL.
+     *  Optional so existing adapters keep compiling; a host whose threads are externally managed may omit it. */
+    threads?: ThreadStore;
     /** Opt-in container scratchpad (Part D). Optional so existing adapters keep compiling. */
     scratchpad?: ScratchpadStore;
     /**
@@ -292,11 +839,16 @@ interface StorageAdapter {
      */
     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.
+     * Mark a followup 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. Tenant-scoped.
+     *
+     * **Compare-and-set (K4):** returns `true` if THIS call transitioned the followup unanswered→answered, `false`
+     * if it was already answered. An out-of-band reply path uses this as the single answer-once guard — two
+     * distinct inbound replies for one followup race here, and only the `true` winner resumes (the loser ACKs).
+     * The engine's own resume ignores the return (it already passed `findSuspended`).
      */
-    markFollowupAnswered?(followupId: string, tenantId: string): void | Promise<void>;
+    markFollowupAnswered?(followupId: string, tenantId: string): boolean | Promise<boolean>;
     /**
      * 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
@@ -304,6 +856,12 @@ interface StorageAdapter {
      * is the only staleness bound there). The supabase adapter uses Postgres LISTEN/NOTIFY.
      */
     subscribeInvalidations?(onInvalidate: (key: string) => void): () => void;
+    /**
+     * FR-016 — enumerate the engine's tenants (org ids) so a host can idempotently backfill every tenant's crew
+     * (`engine.run` resolves agents per-tenant from the DB, so each tenant must be seeded before its first run).
+     * Optional: a read-only / in-memory adapter may omit it. The supabase adapter reads `nightowls.orgs`.
+     */
+    listTenants?(): Promise<string[]>;
 }
 interface ModelProvider {
     resolve(modelId: string, ctx: {
@@ -357,7 +915,29 @@ interface RunInput {
      * (those come from `SwarmContext`); treat its contents as opaque, attacker-controllable input.
      */
     context?: Record<string, unknown>;
+    /**
+     * Phase B: run a named STRICT workflow via the step-driver instead of the free-form agent turn. Engine/host-
+     * side seam — set by a host calling the runner/engine directly; NOT exposed on the public chat route or MCP
+     * (the wall promise). An unknown name throws before the run row is created.
+     */
+    workflow?: string;
 }
+/** The verdict from a {@link CompletionVerifier}: was the user's request actually satisfied, and if not, a
+ *  short description of what's still missing (used to build a targeted continue-nudge). */
+interface CompletionVerdict {
+    complete: boolean;
+    missing?: string;
+}
+/**
+ * Completion supervisor hook (reliability) — see EngineOpts.verifyCompletion. Given the original request + a
+ * transcript of what the run produced, decide whether the task is genuinely done. Host-supplied (typically a
+ * cheap LLM judge). FAIL-SAFE at the call site: a throw/timeout is treated as "complete" (never trap a run).
+ */
+type CompletionVerifier = (args: {
+    request: string;
+    transcript: string;
+    ctx: SwarmContext;
+}) => Promise<CompletionVerdict> | CompletionVerdict;
 interface Runner {
     run(input: RunInput, ctx: SwarmContext): AsyncIterable<SwarmEvent>;
     enqueue(input: RunInput, ctx: SwarmContext): Promise<{
@@ -369,6 +949,22 @@ interface Runner {
         followupId: string;
         answer: unknown;
     }, ctx: SwarmContext): AsyncIterable<SwarmEvent>;
+    /**
+     * Durable resume (symmetric with `enqueue`): wake a suspended run and return its `runId` WITHOUT streaming the
+     * continuation — the resumed events reach the client over its EXISTING Realtime subscription. A streaming-only
+     * runner omits this; the durable runner provides it. Streaming the resume instead would never close (the
+     * Realtime subscribe has no terminal), so the client's `answer()` would hang. Also re-wakes a continuation lost
+     * to a process restart, from the durable snapshot (see the background runner).
+     */
+    resumeEnqueue?(args: {
+        runId: string;
+        toolCallId: string;
+        followupId: string;
+        answer: unknown;
+        context?: Record<string, unknown>;
+    }, ctx: SwarmContext): Promise<{
+        runId: string;
+    }>;
 }
 
 type ByType<T extends SwarmEvent["type"]> = Extract<SwarmEvent, {
@@ -382,6 +978,23 @@ declare function ev<T extends SwarmEvent["type"]>(type: T, base: {
 }, data: ByType<T>["data"]): ByType<T>;
 declare function isEvent<T extends SwarmEvent["type"]>(e: SwarmEvent, type: T): e is ByType<T>;
 
+/**
+ * The per-run mutable store a first-party tool sees on `SwarmToolContext.state`. A simple keyed bag plus an
+ * `entries()` snapshot the `onRunEnd` drain reads. Reads of an unset key yield `undefined`; it never throws.
+ */
+interface RunStateHandle {
+    get<T = unknown>(key: string): T | undefined;
+    set(key: string, value: unknown): void;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    /** A point-in-time DEEP snapshot of all current entries — what `onRunEnd` flushes and the engine persists into
+     *  the run snapshot. Deep-copied so a later in-place mutation of a stored object can't corrupt an already-taken
+     *  snapshot. Values must be JSON-serializable (they ride the run snapshot). */
+    entries(): Record<string, unknown>;
+}
+/** Build a fresh, Map-backed run-state handle. `seed` (e.g. from `onRunStart`) pre-populates it. */
+declare function createRunState(seed?: Record<string, unknown>): RunStateHandle;
+
 /** 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". */
@@ -422,88 +1035,116 @@ declare class InMemoryContainerFloor implements ContainerFloor {
 /** 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;
-    };
+type ModelTier = "swift" | "genius";
+type ModelRef = string;
+/** Context handed to the per-task escalation hook so it can decide whether a specific generation needs Genius. */
+interface TierEscalationContext {
+    tenantId: string;
+    /** The agent the generation is for. */
+    agentSlug: string;
+    /** The agent's declared modelId (a tier sentinel when it opted into routing; the concrete pin otherwise). */
+    pinnedModelId?: 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.
+ * The tier configuration (lives on `SwarmConfig.models.tier` → `EngineOpts.tier`). @mastra-free.
+ *   - `tiers.swift`  — the cheap DEFAULT model. REQUIRED (the floor every non-pinned agent lands on).
+ *   - `tiers.genius` — the frontier model. OPTIONAL; reachable ONLY through the premium gate below.
+ *   - `default`      — the tier the bare `"tier:"` sentinel resolves to. Default `"swift"` (cheap-default).
+ *   - `allowGenius`  — the SERVER-ENFORCED OPT-IN GATE. Default `false`. This is NOT a user-facing "smart"
+ *                      slider: it lives in the platform-set EngineOpts so a pack/agent config CANNOT grant itself
+ *                      Genius. With it false, any Genius request (a `tier:genius` agent OR an escalation) is
+ *                      DOWNGRADED to Swift so the run still proceeds cheaply (deny-vs-downgrade: we DOWNGRADE).
+ *   - `escalate`     — optional per-task hook (configurable per pack): given the generation's context it may bump
+ *                      the chosen tier to `"genius"` (e.g. an ambiguous case). STILL subject to `allowGenius` —
+ *                      escalation cannot bypass the premium gate.
  */
-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;
-    }>;
+interface TierConfig {
+    tiers: {
+        swift: ModelRef;
+        genius?: ModelRef;
+    };
+    default?: ModelTier;
+    allowGenius?: boolean;
+    escalate?: (ctx: TierEscalationContext) => ModelTier | undefined;
 }
-/** 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;
+/** The outcome of routing a single generation's model. `modelId` is always the EFFECTIVE id to use next. */
+interface TierResolution {
+    /** The effective modelId to hand to the allow-list + factory. */
+    modelId: string;
+    /** The tier actually landed on. Undefined when the agent pinned a concrete model (a pin is not a tier). */
+    tier?: ModelTier;
+    /** True when a Genius request was downgraded to Swift (gate closed, or no genius model configured). */
+    downgraded: boolean;
+    /** The tier that was REQUESTED before gating (set when it differs from `tier`, i.e. on a downgrade). */
+    requestedTier?: ModelTier;
+    /** True when the escalation hook bumped the tier (to genius) and that bump survived the gate. */
+    escalated?: boolean;
 }
+/** Is this declared modelId a tier sentinel (opting into routing) rather than a concrete pin? */
+declare function isTierSentinel(modelId: string | undefined): boolean;
+/**
+ * Resolve the effective model for ONE generation, applying tier routing + the premium Genius gate + escalation.
+ *
+ * Order of precedence:
+ *   1. A CONCRETE PIN (non-sentinel modelId) is returned verbatim — routing/escalation never touch a pin.
+ *   2. Otherwise the requested tier = the sentinel's tier (or the config default for a bare `"tier:"`).
+ *   3. The optional `escalate` hook may bump the request to `"genius"`.
+ *   4. THE GATE: a `"genius"` request survives ONLY when `allowGenius` is true AND a `genius` model is
+ *      configured; otherwise it DOWNGRADES to `"swift"` (the run proceeds cheaply; `downgraded` is flagged).
+ */
+declare function resolveTier(modelId: string, cfg: TierConfig, ctx: TierEscalationContext): TierResolution;
+/**
+ * The engine-facing convenience: given an agent's declared modelId, return the EFFECTIVE modelId after tier
+ * routing. When no tier config is configured this is the identity function (today's behaviour). The resulting
+ * modelId then flows through the SAME allow-list validation + factory mapping as before — a tier model is never
+ * exempt from the allow-list.
+ */
+declare function tierModelId(modelId: string, cfg: TierConfig | undefined, ctx: TierEscalationContext): string;
 
 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). */
+    /**
+     * SP10 — the cheap-model router (Swift/Genius tiers). @mastra-free. When set, the per-agent model resolver
+     * routes a tier-sentinel `modelId` (`"tier:swift"` / `"tier:genius"` / bare `"tier:"`) to the configured tier
+     * model; a concrete pinned `modelId` is kept verbatim (routing layers OVER pinning). `tiers.swift` is the
+     * cheap DEFAULT every non-pinned agent lands on; `tiers.genius` is reachable ONLY through the server-enforced
+     * `allowGenius` premium gate (default false) — set HERE in EngineOpts so a pack/agent config cannot grant itself
+     * Genius. An optional per-task `escalate` hook may bump a generation to Genius, still subject to the gate. When
+     * a Genius request is denied by the gate it DOWNGRADES to Swift so the run proceeds cheaply. Omit ⇒ no routing
+     * (identical to today: the agent's own `modelId` flows through, still allow-list-validated). The routed model
+     * is ALWAYS re-validated by the allow-list `model` provider — a tier model is never exempt.
+     */
+    tier?: TierConfig;
+    /** Global per-run caps + metering config (SP1) + optional per-delegate sub-budgets (R5: `perDelegate` stops
+     *  one runaway sub-agent from burning the whole turn before the global `maxCostUsd` notices).
+     *  - `prices`: static per-model overrides, merged over PRICE_TABLE.
+     *  - `priceFeed`: optional live price seam (numbers only — engine wall). Merged over `prices`.
+     *  - `failOnUnknownModel` (default false): an unpriced model THROWS instead of pricing at $0.
+     *  - `onCapHit` (SP9-core, default "stop"): the GLOBAL run-level cost/step cap's behaviour when reached.
+     *      "stop" (DEFAULT) = today's terminal `run_failed` stage "cost" — byte-identical to before.
+     *      "ask"  = PAUSE the run and ASK the user "Budget cap reached — continue?" (a CONSUMER-context opt-in),
+     *               reusing SP5's suspend→swarm.question→resume machinery. Resume-approve RAISES the budget by
+     *               `capIncrementUsd` and continues; resume-reject terminally stops (stage "cost"). The
+     *               per-delegate cap (`perDelegate`) is NOT folded into the ask flow — it stays terminal.
+     *  - `capIncrementUsd` (SP9-core): the additional USD headroom an "ask" APPROVE grants (`maxCostUsd +=`).
+     *      Defaults to the original `maxCostUsd` ("another budget's worth"). Only meaningful with `onCapHit:"ask"`. */
     cost: {
         maxSteps: number;
         maxCostUsd: number;
         perDelegate?: PerDelegateBudget;
+        prices?: Record<string, Price>;
+        priceFeed?: PriceFeed;
+        failOnUnknownModel?: boolean;
+        onCapHit?: "stop" | "ask";
+        capIncrementUsd?: number;
     };
     /** Per-swarm skill resolver. When omitted, agents expose only built-in tools. */
     resolveSkill?: (name: string) => SwarmSkill | undefined;
+    /** PR2 — opt-in per-request connector-tools resolver (tenant-scoped). Forwarded verbatim to `buildMastraAgent`
+     *  for the orchestrator + every sub-agent. Connector-agnostic: core never imports `@nightowlsdev/connectors`. */
+    connectorTools?: (ctx: SwarmContext) => Promise<SwarmTool[]>;
     /**
      * Mastra storage backend for suspend/resume snapshots. Resume is storage-gated
      * (SPIKE-FINDINGS item 5): the in-memory default cannot survive process death.
@@ -531,9 +1172,79 @@ interface EngineOpts {
     };
     /** Opt-in `recall_lane` tool (Part E). Read-only peer-lane transcript read. */
     recallLane?: boolean;
+    /** Phase A soft tier: per-agent soft-policy lines (advise rules + advisory-workflow summaries) appended to
+     *  each agent's system prompt. Built by `defineSwarm` from the swarm's rules/workflows. Omit ⇒ no policy. */
+    softPolicy?: (slug: string) => string[];
+    /** Phase B: swarm-level STRICT workflows, runnable by name via `RunInput.workflow`. Built by `defineSwarm`. */
+    workflows?: WorkflowDef[];
+    /** Phase B: per-agent STRICT workflows (keyed by agent slug) — replace that agent's turn when it owns the run. */
+    agentWorkflows?: Record<string, WorkflowDef>;
     /** 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;
+    /** Decision/observer hook dispatcher (SP2). `defineSwarm` always supplies one (allow-all when no hooks are
+     *  configured). When omitted (e.g. an engine built directly in a unit test), the engine defaults to an
+     *  allow-all dispatcher — behaviour identical to today. The engine AWAITS `preGeneration` before every model
+     *  launch; a `deny` vetoes the generation (terminal `run_failed` stage `"reserve"`). The same dispatcher's
+     *  `preToolCall` powers SP5's action-approval gate. */
+    hooks?: HookDispatcher;
+    /**
+     * SP5 — the NON-REMOVABLE tool-approval policy (a P0 SAFETY control: spend caps limit cost, not harm). Forces
+     * human approval on side-effecting tools regardless of the per-tool `needsApproval` flag, so a consumer pack
+     * can't ship a `needsApproval:false` $0.50 action that causes $50k of damage. `defineSwarm` bakes this into the
+     * `hooks` dispatcher (which combines policy + flag + the `preToolCall` hook), so when `hooks` is supplied THAT
+     * dispatcher's policy is authoritative. This standalone field lets a DIRECT engine builder (e.g. a unit test
+     * that passes no dispatcher) set the policy; the engine then builds an allow-all-hooks dispatcher WITH it.
+     * Default `{ mode: "flag" }` — today's behaviour (only `needsApproval:true` tools gate).
+     */
+    toolApproval?: ToolApprovalPolicy;
+    /**
+     * SP15 — the optional SecretResolver the platform vault (SP15-platform) implements. When set, the engine
+     * injects it on every run's RequestContext (SAME seam as SP5's ToolGate) so a first-party tool body can
+     * `await ctx.secrets.resolve(ref)` to fetch a tenant-scoped secret at execution time. @mastra-free. Omit ⇒
+     * `ctx.secrets.resolve(...)` yields `undefined` (no vault) and the no-secrets path is unchanged from today.
+     */
+    secrets?: SecretResolver;
+    /**
+     * SP3 — best-effort per-event OBSERVER, fired by the engine AFTER each event is persisted (in `emit`), for
+     * BOTH `run` and `resume`. Transport-agnostic: it sees every event regardless of how it reaches the client
+     * (interactive SSE vs durable + realtime), so platform metering (debit on `swarm.turn_usage`, settle on a
+     * terminal) can live HERE rather than teeing the route's stream. Awaited but FAIL-SAFE — a throwing observer
+     * is swallowed (the host logs its own errors), NEVER breaking the run, exactly like `telemetry`. Omit ⇒ no-op.
+     */
+    onEvent?: (ev: SwarmEvent, ctx: SwarmContext) => void | Promise<void>;
+    /**
+     * Completion supervisor (reliability) — an optional host check fired when a turn would END, to decide whether
+     * the user's request was actually SATISFIED. The engine passes the original request + a transcript of what the
+     * run produced; it returns `{ complete, missing? }`. When not complete the engine re-invokes the orchestrator
+     * with a TARGETED nudge built from `missing` (same thread, full context), up to MAX_CONTINUE_NUDGES. If still
+     * incomplete, the run ends `run_failed` stage "incomplete" (retryable) — a clear non-delivery the host can
+     * refund — instead of a silent `done`. FAIL-SAFE: a throwing/rejecting verifier is treated as "complete"
+     * (fail-open — never trap a run in a verify loop). Omit ⇒ the cheap structural "did the root speak last?"
+     * fallback nudge is used instead.
+     */
+    verifyCompletion?: CompletionVerifier;
+    /**
+     * FR-003 — per-run lifecycle hooks (fired on `run()`). `onRunStart` is awaited once when a run begins (after the
+     * run row + thread are ensured, before the first model launch), receiving the run's `input` and a fresh
+     * `RunStateHandle` to seed (e.g. from `input.context`). `onRunEnd` is awaited once at the run's terminal boundary
+     * (done / failed / suspended / thrown / abandoned — it fires from the run's `finally`), receiving the final
+     * `state` and the `outcome`, so a host can flush/persist deterministically. Both are FAIL-SAFE (a throw is
+     * swallowed + logged, never breaking the run). `state` is the SAME handle the run's tools saw via `ctx.state`.
+     * `onRunEnd` fires at EACH segment's terminal: a suspend ends the run() segment with outcome `"suspended"`, and
+     * the resume segment fires its own `onRunEnd` (`"done"`/`"failed"`/`"suspended"`) — a host keys billing/persist
+     * on the terminal outcome. A `resume` RESTORES the per-run `state` persisted at suspend (so a client-tool /
+     * evolving-document flow keeps state across the answer); `onRunStart` fires on `run()` only. State values must be
+     * JSON-serializable (they ride the run snapshot). Omit ⇒ no-op.
+     */
+    onRunStart?: (ctx: SwarmContext, info: {
+        input: RunInput;
+        state: RunStateHandle;
+    }) => void | Promise<void>;
+    onRunEnd?: (ctx: SwarmContext, info: {
+        state: RunStateHandle;
+        outcome: "done" | "failed" | "suspended";
+    }) => void | Promise<void>;
 }
 declare class SwarmEngine {
     private opts;
@@ -541,11 +1252,56 @@ declare class SwarmEngine {
     private rowCache;
     private memory;
     private floor;
+    private hooks;
     constructor(opts: EngineOpts);
+    /** SP1: the swarm's metering config, in the shape DelegateBudgets/priceUsage expect. CostGovernor reads the
+     *  same fields directly off `opts.cost`; this packs them for the per-delegate tracker so both caps price
+     *  tokens identically (built-in PRICE_TABLE ← static `prices` ← live `priceFeed`, with `failOnUnknownModel`). */
+    private pricingOpts;
+    /** Fire the best-effort per-event observer (`EngineOpts.onEvent`). Awaited so an async observer (e.g. a
+     *  metering debit) completes in order, but FAIL-SAFE: a throw is swallowed (the host logs its own), never
+     *  breaking the run — same contract as the telemetry exporter. No-op when no observer is configured. */
+    private notifyEvent;
+    /** 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. */
+    private safeVerify;
+    /** Best-effort recall of the run's ORIGINAL request (first user message on the thread) for the completion
+     *  verifier on RESUME, where the engine doesn't hold the opening message. Empty on any failure / no verifier. */
+    private recallRequest;
     /** Cached agent-row load shared by the three dynamic agent fns AND run/resume. */
     private loadRow;
+    /** Resolve an agent's STORED modelId — which may be a tier sentinel (`"tier:"` / `"tier:swift"`) — to the
+     *  CONCRETE model id the generation actually runs on, so metering/pricing + the preGeneration event see the
+     *  real model, not the sentinel (which has no price → every tier-routed turn would meter at $0). Mirrors
+     *  mastra-map's modelFor routing; with no tier config it returns the id unchanged. (SP10 pricing follow-up.) */
+    private priceModelId;
     private agent;
     private requestContext;
+    /**
+     * SP5 — the action-approval gate handed to every gated tool via the RequestContext. Bound once (stable
+     * reference). Delegates to the dispatcher's `preToolCall`, which is fail-closed (a throwing configured hook ⇒
+     * deny) and applies the non-removable policy. The defineTool wrapper turns the returned `ToolDecision` into:
+     * allow → run; deny → blocked result; ask → suspend-and-ask (the existing `swarm.question`/resume machinery).
+     */
+    private readonly toolGate;
+    /**
+     * SP5 truth-fix — resolve whether a tool WILL require approval, for the `swarm.tool_call` event's
+     * `needsApproval` (the react reducer reads it to render an approval card). The mapChunk emit currently
+     * hardcodes `false` (the truth-bug). This computes the truthful value from the SAME policy + per-tool flag the
+     * gate uses: the tool's resolved `needsApproval` (its own flag, defaulting by origin) run through the
+     * dispatcher's SYNC `policyDecision` — `ask` ⇒ true (it will gate), else false. The async `preToolCall` hook
+     * can still escalate a specific call at execute time, but the policy-derived baseline is the truthful default
+     * the UI needs without speculatively running the hook for every tool_call event.
+     */
+    private gatesApproval;
+    /**
+     * SP2: the preGeneration DECISION seam. Awaited immediately before each model launch (run + resume). The
+     * dispatcher is fail-closed (a throwing hook ⇒ deny), so this only ever sees a clean `allow`/`deny`; a `deny`
+     * THROWS `ReserveDenied` so the model call below never happens and the run/resume catch-all maps it to a
+     * terminal `run_failed` stage "reserve" (NOT the generic "exception"). Allow-all + zero-overhead when no
+     * hooks are configured (the default dispatcher returns allow synchronously-ish without invoking anything).
+     */
+    private guardGeneration;
     /** Per-call Mastra memory ids + delegation, only when memory is configured (else stream is unchanged). */
     private memoryOpts;
     /**
@@ -606,11 +1362,28 @@ declare class SwarmEngine {
     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 full, globally-ordered event log for a thread's CONTAINER (all its runs + lane sub-threads) — lets a host
+     *  rebuild the RICH timeline (tool calls + delegation cards) on reload, since message history is text-only.
+     *  Returns [] when the store has no events table (`listForContainer` unset). */
+    threadEvents(threadId: string, ctx: SwarmContext): Promise<SwarmEvent[]>;
     /** 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>;
+    /**
+     * Phase B — drive a STRICT workflow IN PLACE OF the free-form continue-nudge loop. Shared by `run()` (fresh)
+     * and `resume()` (re-entry after a human/approval suspend). An `agent` step reuses `this.agent().stream()`
+     * with a per-step requestContext (agentSlug = the step's agent) so it inherits persona/tools/gate/model/cost;
+     * a `tool` step runs `executeToolWithGate`; a `human`/approval pause suspends SP9-style. Reserve, usage, and
+     * the terminal turn_usage flow through the caller's machinery (`m`). Handles the terminal status/setStatus.
+     */
+    private driveWorkflow;
+    /** A workflow `agent` step: stream `slug` with `message` (a per-step requestContext so it inherits the agent's
+     *  persona/tools/gate/model), reserving + metering through the caller's machinery, returning the final text. */
+    private streamWorkflowAgentStep;
+    /** A workflow `tool` step: run the gate-free tool body through `executeToolWithGate` (the engine-owned gate). */
+    private runWorkflowToolStep;
     resume(args: {
         runId: string;
         toolCallId: string;
@@ -619,6 +1392,24 @@ declare class SwarmEngine {
         context?: Record<string, unknown>;
     }, ctx: SwarmContext): AsyncIterable<SwarmEvent>;
 }
+/**
+ * SP2: a typed veto thrown when the `preGeneration` decision hook DENIES a model launch. Caught explicitly in
+ * the run/resume catch-all so it maps to a TERMINAL `run_failed` stage `"reserve"` (mirroring the cost cap's
+ * `"cost"` stage) instead of falling through to the generic `"exception"` stage. The model call has NOT
+ * happened when this throws — the seam is BEFORE `stream`/`resumeStream`.
+ */
+declare class ReserveDenied extends Error {
+    readonly stage: "reserve";
+    constructor(reason: string);
+}
+
+/** The bound, run-scoped resolver handed to a tool body via `ctx.secrets`. `resolve(ref)` carries no ctx arg —
+ *  the run's tenant/auth scope is captured by the binding, so a tool can never resolve another tenant's secret
+ *  (the scope comes from the trusted RequestContext, NOT from tool args). Returns `undefined` when no resolver is
+ *  configured or the ref is unknown. */
+interface BoundSecrets {
+    resolve(ref: string): Promise<string | undefined>;
+}
 
 interface ToolSpec<I, O> {
     name: string;
@@ -633,9 +1424,23 @@ interface SwarmToolContext {
     tenantId: string;
     userId: string;
     runId: string;
-    secrets?: {
-        resolve(ref: string): Promise<string>;
-    };
+    /**
+     * SP15 — a run-scoped secret resolver (always present; bound to THIS run's tenant/auth ctx). A first-party
+     * tool body calls `await ctx.secrets.resolve(ref)` to fetch a scoped secret value at execution time, mirroring
+     * how the MCP connector resolves a credentialRef. The run's tenant scope is captured by the binding (NOT passed
+     * by the tool), so a tool can never resolve another tenant's secret. Resolves to `undefined` when the swarm has
+     * no SecretResolver configured (no vault) or the ref is unknown — never throws. Optional in the type only for
+     * back-compat with code that constructs a bare ctx; the engine always populates it.
+     */
+    secrets?: BoundSecrets;
+    /**
+     * FR-003 — the per-run mutable state store. The SAME handle across every tool call in this run (orchestrator
+     * AND delegated sub-agents), so a chain of tools (`addPrimitive → addStageZone → …`) can read the previous
+     * tool's result and write the next. Seeded by `SwarmConfig.onRunStart` (e.g. from the client payload), drained
+     * by `onRunEnd`. GC'd with the run — no module-level registry. Optional in the type only for back-compat with a
+     * hand-constructed bare ctx; the engine always populates it.
+     */
+    state?: RunStateHandle;
 }
 interface SwarmTool {
     name: string;
@@ -645,6 +1450,20 @@ interface SwarmTool {
 type SwarmSkill = SwarmTool;
 declare function defineTool<I, O>(spec: ToolSpec<I, O>): SwarmTool;
 declare function defineSkill(tool: SwarmTool): SwarmSkill;
+interface ClientToolSpec<I, O> {
+    name: string;
+    description?: string;
+    inputSchema: z.ZodType<I>;
+    outputSchema?: z.ZodType<O>;
+    /** Ask the UI to confirm before the client runs the action (the handler renders an approval step). Default false. */
+    needsApproval?: boolean;
+}
+/** Thrown when a client tool's handler reports an error (the browser posted `{ error }`) — surfaces as a failed
+ *  tool_result so the model sees the action did not succeed. */
+declare class ClientToolError extends Error {
+    constructor(toolName: string, reason?: string);
+}
+declare function defineClientTool<I, O>(spec: ClientToolSpec<I, O>): SwarmTool;
 interface AgentSpec {
     slug: string;
     role?: "orchestrator" | "specialist";
@@ -655,22 +1474,100 @@ interface AgentSpec {
     modelId?: string;
     /** Per-agent memory OPTIONS override (R9), merged over the swarm `memory` config. Infra stays swarm-wide. */
     memory?: AgentMemoryOverride;
+    /** Per-agent rules (additive over swarm rules for THIS agent). Engine-local in v1 (not persisted/versioned). */
+    rules?: RuleDef[];
+    /** Per-agent workflow/procedure. Engine-local in v1. A strict one is rejected by `defineSwarm` until Phase B. */
+    workflow?: WorkflowDef;
 }
 declare function defineAgent(spec: AgentSpec): AgentDef;
+/**
+ * Normalize + validate a `RuleSpec` into a `RuleDef`. Plain data (no engine types) — the compiled rule the
+ * engine holds. Validation is compile-time (throws): `enforce` requires an `action`; `ask` is TOOL-SEAM ONLY
+ * (preGeneration is binary allow/deny — it cannot suspend); an `ask` cannot explicitly target a delegation
+ * (`agent-*`) because `gateDelegation` defers `ask` to the sub-agent's inner gates (use `deny`).
+ */
+declare function defineRule(spec: RuleSpec): RuleDef;
+/**
+ * Normalize + validate a `WorkflowSpec` into a `WorkflowDef`. Validation is GRAPH-ONLY (pure code): unique step
+ * ids, exactly one kind per step, `start`/`next`/`to`/`$ref` reference known steps, no cycles. Agent/tool
+ * EXISTENCE is NOT validated here (it's runtime — `defineSwarm` doesn't validate delegate slugs and tenant DB
+ * rows make it impossible; an unknown agent/tool surfaces as a runtime `run_failed` stage "workflow").
+ */
+declare function defineWorkflow(spec: WorkflowSpec): WorkflowDef;
 /** Build a per-swarm skill resolver from the agents' attached skill handles. */
 declare function buildSkillResolver(agents: AgentDef[]): (name: string) => SwarmSkill | undefined;
+/**
+ * Compose + CLOSURE-VALIDATE a capability bundle from `defineAgent` outputs (BN0 static composition + BN1 connector
+ * grants). Pure normalizer/validator (no storage, no Mastra) — same posture as `defineRule`/`defineWorkflow`.
+ * Validates, at author time, that the bundle is self-contained:
+ *  - every member `skillName` resolves to a first-party **handle** present on the bundle, OR is a declared
+ *    **connector grant** for that member (BN1 — connector-backed, materialized per-tenant by the host at runtime);
+ *  - every member delegate is a bundle member or a declared `requires` dependency;
+ *  - every tool-seam rule ref and every workflow `step.tool` resolves to a handle or any declared grant;
+ *  - no workflow step embeds a credential/connection ref.
+ * So a missing handle/grant fails LOUD here, not as a runtime `run_failed`. Connector grants fold their action names
+ * into the granted member's `skillNames` so the host's `connectorTools` resolver grants them by membership at call time.
+ */
+declare function defineBundle(spec: BundleSpec): BundleDef;
+/**
+ * Fold a validated bundle into a `SwarmConfig` (its agents + swarm-scoped rules/workflows) so the result is a
+ * drop-in `defineSwarm` input. Per-agent rules/workflows ride on the merged `AgentDef`s and are collected by
+ * `defineSwarm` exactly as for hand-authored agents — the bundle is a FRONT-END to `defineSwarm`, not a parallel
+ * engine, so it adds no new runtime path. A bundle that re-declares an existing agent slug is a conflict (fail loud).
+ */
+declare function mergeBundle(cfg: SwarmConfig, bundle: BundleDef): SwarmConfig;
+/**
+ * Project a `BundleDef` (in-process, carrying skill HANDLES) into its SERIALIZABLE `BundleVersionContent` for
+ * persistence (BN2): each member becomes its head's `AgentVersionContent` (the `version` + the handles dropped),
+ * and the rules/workflows/connector-grants/deps carry through as the plain data they already are. This is the
+ * bridge from BN0/BN1 (compose in-process) to BN2 (persist + version). The result has `skillNames` but no
+ * handles — re-hydrating it into a live swarm (BN3 apply) needs a host-supplied handle manifest.
+ */
+declare function toBundleContent(def: BundleDef): BundleVersionContent;
 declare const ASK_TOOL_NAME = "ask";
 interface SwarmConfig {
     storage: StorageAdapter;
     agents: AgentDef[];
+    /**
+     * The model allow-list + optional SP10 cheap-model router. `allow` is the per-tenant allow-set every
+     * resolved model (incl. a tier model) must pass. `tier` (optional) enables Swift/Genius routing: a non-pinning
+     * agent (tier-sentinel `modelId`) lands on the cheap `swift` model by default; `genius` is reachable ONLY via
+     * the server-enforced `allowGenius` premium gate (a pack/agent config cannot grant itself Genius). See TierConfig.
+     */
     models: {
         allow: string[];
+        tier?: TierConfig;
     };
     modelFactory: (modelId: string, agentSlug?: string) => unknown;
+    /**
+     * PR2 — opt-in connector tools. Build with `materializeConnectors(connectors, backend)` from
+     * `@nightowlsdev/connectors`; an agent gets a connector action only if the action `name` is in its
+     * `skillNames` (i.e. it listed the action among its `skills`). Tenant-scoped + materialized per request.
+     * Omit ⇒ no connector tools.
+     */
+    connectorTools?: (ctx: SwarmContext) => Promise<SwarmTool[]>;
+    /**
+     * Global per-run caps + metering config (SP1). `prices` statically overrides the built-in PRICE_TABLE;
+     * `priceFeed` is an optional live seam supplying NUMBERS only (engine wall); `failOnUnknownModel` (default
+     * false) makes an unpriced model THROW instead of pricing at $0. `perDelegate` adds optional per-delegate
+     * USD sub-budgets (R5). All metering fields are threaded into the engine's CostGovernor + DelegateBudgets.
+     *
+     * SP9-core — the cap-that-asks (`onCapHit` + `capIncrementUsd`). `onCapHit:"ask"` (DEFAULT "stop") turns a
+     * GLOBAL cost/step-cap hit into a PAUSE-and-ASK ("Budget cap reached — continue?") instead of a terminal
+     * `run_failed`, so a consumer run can be granted more budget mid-task rather than dying. A pack sets this
+     * SERVER-SIDE (it is not a per-agent flag). Resume-approve raises `maxCostUsd` by `capIncrementUsd` (default
+     * = the original `maxCostUsd`) and continues; resume-reject terminally stops (stage "cost"). The per-delegate
+     * cap is unaffected — it stays terminal. Leave `onCapHit` unset for today's behaviour (terminal stop).
+     */
     cost: {
         maxSteps: number;
         maxCostUsd: number;
         perDelegate?: PerDelegateBudget;
+        prices?: Record<string, Price>;
+        priceFeed?: PriceFeed;
+        failOnUnknownModel?: boolean;
+        onCapHit?: "stop" | "ask";
+        capIncrementUsd?: number;
     };
     /**
      * Telemetry exporter(s). One or many — many are composed best-effort
@@ -701,6 +1598,71 @@ interface SwarmConfig {
     /** 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;
+    /**
+     * Opt-in decision/observer hooks (SP2). Types-only / engine-free (from `@nightowlsdev/hooks`). Today exposes a
+     * `preGeneration` DECISION hook that the engine AWAITS immediately before EACH model launch (run + resume):
+     * an `allow` proceeds, a `deny` VETOES the generation (terminal `run_failed` stage `"reserve"`, no model call).
+     * Decision hooks are FAIL-CLOSED — a throwing hook is treated as a deny (a billing/safety veto must never
+     * silently allow on error). Omit ⇒ allow-all, identical to prior behaviour with zero overhead. This is the
+     * seam the platform's per-generation billing RESERVE (SP3) plugs into.
+     */
+    hooks?: SwarmHooks;
+    /**
+     * SP5 — the NON-REMOVABLE action-approval policy (a P0 SAFETY control). Forces human approval on
+     * side-effecting tools regardless of the per-tool `needsApproval` flag, so a consumer pack cannot ship a
+     * `needsApproval:false` $0.50 action that causes $50k of damage (spend caps limit cost, not harm). Two modes:
+     *   - `{ mode: "flag" }` (DEFAULT): today's behaviour — only `needsApproval:true` tools gate.
+     *   - `{ mode: "all-side-effecting" }`: force-ask EVERY non-read-only tool (every MCP tool + every first-party
+     *     tool not on the read-only allowlist), regardless of the per-tool flag. The safe default for an untrusted
+     *     consumer pack. Optionally override `readOnly` to customise the exempt set.
+     * Baked into the `hooks` dispatcher, which combines policy + flag + the optional `preToolCall` hook into the
+     * effective decision (allow / deny / ask-the-human). A `preToolCall` hook (in `hooks`) can add a richer gate.
+     */
+    toolApproval?: ToolApprovalPolicy;
+    /**
+     * SP15 — opt-in secret resolution for first-party tools. Pass a `SecretResolver` (the platform vault,
+     * SP15-platform) and the engine scopes it per-run so a tool body can `await ctx.secrets.resolve(ref)` to fetch
+     * a tenant-scoped secret at execution time — the same security posture as the MCP connector's credentialRef
+     * resolution (resolve at execution, scoped by the live ctx, never from tool args). @mastra-free. Omit for
+     * today's behaviour: `ctx.secrets.resolve(...)` yields `undefined` (no vault).
+     */
+    secrets?: SecretResolver;
+    /**
+     * SP3 — best-effort per-event OBSERVER, fired by the engine after each event is persisted (run + resume).
+     * Transport-agnostic (sees every event regardless of interactive-SSE vs durable+realtime delivery), so the
+     * platform's metering — debit on `swarm.turn_usage`, settle on a terminal — lives HERE instead of teeing the
+     * route's stream. Awaited but FAIL-SAFE: a throwing observer is swallowed (log your own), never breaking the
+     * run. The `preGeneration` reserve hook (above) + this observer are the two halves of the credit ledger.
+     */
+    onEvent?: (ev: SwarmEvent, ctx: SwarmContext) => void | Promise<void>;
+    /**
+     * Completion supervisor (reliability) — see EngineOpts.verifyCompletion. When set, the engine asks this at a
+     * turn's end whether the user's request was actually satisfied, nudges the orchestrator with the specific gap
+     * if not, and ends `run_failed:incomplete` (refundable) instead of a silent `done` if it still can't finish.
+     * Omit ⇒ the cheap structural "did the root speak last?" fallback nudge.
+     */
+    verifyCompletion?: CompletionVerifier;
+    /**
+     * FR-003 — per-run lifecycle hooks. `onRunStart(ctx, { input, state })` seeds the run's mutable `ctx.state`
+     * store (e.g. `state.set("sceneCode", input.context?.currentCode ?? "")`) once before the first generation;
+     * `onRunEnd(ctx, { state, outcome })` drains it deterministically at the run's terminal boundary (done /
+     * failed / suspended / thrown). The SAME `state` handle flows into every tool call of the run (orchestrator +
+     * delegated sub-agents) via `ctx.state`. Both are FAIL-SAFE. Omit ⇒ no per-run state seeding/draining.
+     */
+    onRunStart?: EngineOpts["onRunStart"];
+    onRunEnd?: EngineOpts["onRunEnd"];
+    /**
+     * Declarative conditional policy (Phase A). `advise` rules are injected into the system prompt; `enforce`
+     * rules compile into the decision hooks (deny/ask), folding in the non-removable SP5 policy floor. Per-agent
+     * rules are authored via `defineAgent({ rules })` and applied additively.
+     */
+    rules?: RuleDef[];
+    /**
+     * Authorable procedures (Phase A: `advisory` only — an `advisory` workflow's `description` is injected as a
+     * suggested procedure; `compliance: "strict"` is REJECTED until the Phase-B step-driver). Per-agent
+     * procedures are authored via `defineAgent({ workflow })`.
+     */
+    workflows?: WorkflowDef[];
 }
 interface Swarm {
     engine: SwarmEngine;
@@ -748,10 +1710,7 @@ declare class SpanCollector {
      * 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;
+    closeGeneration(usage: UsageBreakdown, costUsd: number): void;
     openTool(toolCallId: string, name: string): void;
     closeTool(toolCallId: string, ok: boolean): void;
     /**
@@ -778,6 +1737,64 @@ declare class RowCache<V> {
     invalidate(key: string): void;
 }
 
+/** Drain an `engine.run(...)` (an `AsyncIterable<SwarmEvent>`) into the eval-shaped trajectory + final output. The
+ *  output is the concatenation of the assistant `swarm.message` texts (the model's visible reply), in stream order. */
+declare function drainTrajectory(stream: AsyncIterable<SwarmEvent>): Promise<{
+    events: SwarmEvent[];
+    output: string;
+}>;
+/** FR-018 — run one input through a built `Swarm`/`SwarmEngine` and return its full trajectory + output. This is
+ *  the seam a host hands to `@nightowlsdev/eval` (`RunAgent = (case) => Promise<{ events, output }>`): no SSE,
+ *  no engine internals. `ctx` defaults to an ephemeral local context when omitted. */
+declare function runToTrajectory(target: Swarm | SwarmEngine, input: RunInput | string, ctx?: Partial<SwarmContext> & {
+    agentSlug: string;
+}): Promise<{
+    events: SwarmEvent[];
+    output: string;
+}>;
+/** Options for {@link runAgent}. The model wiring is the only required part (the same `modelFactory` a swarm
+ *  uses); everything else mirrors the `SwarmConfig` fields and defaults to the single-agent/ephemeral case. */
+interface RunAgentOpts {
+    /** Same `(modelId, agentSlug?) => model` factory `defineSwarm` takes (e.g. `openaiModels()`). Required. */
+    modelFactory: SwarmConfig["modelFactory"];
+    /** Model allow-list + optional tier router. Defaults to allowing the agent's own `modelId` (+ tier models). */
+    models?: {
+        allow?: string[];
+        tier?: TierConfig;
+    };
+    /** Per-run caps. Defaults to a generous single-run budget (`{ maxSteps: 50, maxCostUsd: 10 }`). */
+    cost?: Partial<SwarmConfig["cost"]>;
+    /** Bring your own adapter (e.g. to inspect events afterwards). Defaults to a fresh `InMemoryStorage`. */
+    storage?: StorageAdapter;
+    /** Pass-throughs onto the one-agent SwarmConfig — identical semantics to `defineSwarm`. */
+    telemetry?: SwarmConfig["telemetry"];
+    memory?: SwarmConfig["memory"];
+    hooks?: SwarmConfig["hooks"];
+    toolApproval?: SwarmConfig["toolApproval"];
+    secrets?: SwarmConfig["secrets"];
+    onEvent?: SwarmConfig["onEvent"];
+    onRunStart?: SwarmConfig["onRunStart"];
+    onRunEnd?: SwarmConfig["onRunEnd"];
+    pageContext?: SwarmConfig["pageContext"];
+    mastraStore?: SwarmConfig["mastraStore"];
+    /** Override the ephemeral run context (tenantId/userId/run/thread ids). */
+    ctx?: Partial<SwarmContext>;
+}
+/** Build a one-agent `Swarm` from an `AgentDef` + options — the standalone equivalent of `defineSwarm` for a
+ *  single agent. Useful when you want the built engine (e.g. to call `resume`) rather than a one-shot run. */
+declare function buildSingleAgentSwarm(def: AgentDef, opts: RunAgentOpts): Swarm;
+/**
+ * FR-019 — run a single `AgentDef` to completion and return its trajectory + final output, with NO Supabase
+ * adapter and NO publish required. Honors tier resolution + cost cap + tool-approval (it builds the real engine).
+ *
+ * @example
+ *   const { output } = await runAgent(titleAgent, "Summarize: …", { modelFactory: openaiModels() });
+ */
+declare function runAgent(def: AgentDef, input: RunInput | string, opts: RunAgentOpts): Promise<{
+    events: SwarmEvent[];
+    output: string;
+}>;
+
 declare class InMemoryStorage implements StorageAdapter {
     private evts;
     private seq;
@@ -789,13 +1806,22 @@ declare class InMemoryStorage implements StorageAdapter {
     private agentRows;
     private heads;
     private pads;
+    private threadRows;
     seedAgent(v: AgentVersion, tenantId?: string): void;
     recordSuspend(runId: string, tenantId: string, followupId: string, toolCallId: string): void;
-    markFollowupAnswered(followupId: string, tenantId: string): void;
+    markFollowupAnswered(followupId: string, tenantId: string): boolean;
     /** Test/host helper: read a run row (the RunStore interface is write-mostly). */
     getRun(runId: string): RunRow | undefined;
     events: EventStore;
     runs: RunStore;
+    threads: ThreadStore;
+    /** Test/host helper: read a recorded thread row. */
+    getThread(id: string): {
+        id: string;
+        orgId: string;
+        userId: string;
+        projectId?: string;
+    } | undefined;
     messages: MessageStore;
     scratchpad: ScratchpadStore;
     agents: AgentRepo;
@@ -806,9 +1832,57 @@ declare function composeSystemPrompt(row: AgentVersion): {
     role: "system";
     content: string;
 }[];
+/**
+ * Render the soft-policy lines for an agent (advise-rule statements + advisory-workflow summaries, from
+ * `softPolicyFor`) as a single system message. Returns `[]` when there are none (zero overhead / no message).
+ */
+declare function composePolicyPrompt(lines: string[]): {
+    role: "system";
+    content: string;
+}[];
 
 declare const customAuth: (fn: AuthProvider["authenticate"]) => AuthProvider;
 
+interface RateLimitConfig {
+    /** Window length in seconds. */
+    windowSec: number;
+    /** Max allowed events per window. */
+    max: number;
+}
+interface RateLimitState {
+    count: number;
+    windowStartSec: number;
+}
+interface RateLimitDecision {
+    allow: boolean;
+    /** Remaining allowance in the current window (0 when denied). */
+    remaining: number;
+    /** Seconds until the window resets (when the count clears). */
+    resetSec: number;
+}
+/**
+ * Pure fixed-window rate-limit decision. If there's no prior state or the window has elapsed, a fresh window
+ * starts at count 1 (this event). Otherwise the count increments. Allow while count ≤ max. Returns the decision
+ * AND the next state to persist. Fixed-window is chosen for simplicity + O(1) state (one counter); its known
+ * burst-at-boundary tradeoff is acceptable for an abuse backstop (not a billing meter).
+ */
+declare function decideFixedWindow(prev: RateLimitState | null, cfg: RateLimitConfig, nowSec: number): {
+    decision: RateLimitDecision;
+    state: RateLimitState;
+};
+interface RateLimitStore {
+    /** Record one event for `key` under `cfg` and return the decision. */
+    hit(key: string, cfg: RateLimitConfig, nowSec: number): Promise<RateLimitDecision>;
+}
+/**
+ * In-memory fixed-window store — a REAL limiter for a SINGLE instance. Keeps one window per key in a Map and
+ * prunes expired keys opportunistically so memory stays bounded. NOT shared across instances: a horizontally
+ * scaled deploy must back this with Redis/Postgres (same interface) or limits are per-instance.
+ */
+declare function createInMemoryRateLimitStore(): RateLimitStore;
+/** Parse a "max/window" config from env (e.g. "60" with a default window), clamped to sane positive values. */
+declare function rateConfig(max: number | undefined, windowSec: number, fallbackMax: number): RateLimitConfig;
+
 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 };
+export { ASK_TOOL_NAME, type ActiveRun, type AgentDef, type AgentMemoryOverride, AgentMutationForbidden, type AgentRepo, type AgentSpec, type AgentSummary, type AgentVersion, type AgentVersionContent, type AgentVersionInfo, type AskField, type AskFieldOption, type AuthContext, type AuthProvider, type BoundSecrets, type BundleDef, type BundleDep, type BundleRepo, type BundleSpec, type BundleVersion, type BundleVersionContent, type BundleVersionInfo, type BundleWritableRepo, CapturingExporter, ClientToolError, type ClientToolSpec, type CompletionVerdict, type CompletionVerifier, type ConnectorGrant, type ContainerFloor, CostGovernor, DelegateBudgets, type EngineOpts, type EventStore, type FloorHolder, GUARDRAILS, InMemoryContainerFloor, InMemoryStorage, type MemoryConfig, type MessageStore, type ModelProvider, type ModelRef, type ModelTier, type NewRun, PRICE_TABLE, type PerDelegateBudget, type Price, type PriceFeed, type PricingOpts, type RateLimitConfig, type RateLimitDecision, type RateLimitState, type RateLimitStore, type Release, ReserveDenied, RowCache, type RuleAction, type RuleCondition, type RuleDef, type RuleLevel, type RuleSpec, type RunAgentOpts, type RunInput, type RunRow, type RunStateHandle, type RunStatus, type RunStore, type Runner, SCRATCHPAD_MAX_ENTRY_CHARS, SCRATCHPAD_MAX_KEYS, type ScratchpadEntry, type ScratchpadStore, type SecretResolver, type SlugUsage, SpanCollector, type StorageAdapter, type Swarm, type SwarmActor, type SwarmConfig, type SwarmContext, SwarmEngine, type SwarmEvent, type SwarmMessage, type SwarmSkill, type SwarmSpan, type SwarmTool, type SwarmToolContext, type TelemetryExporter, type ThreadStore, type ThreadSummary, type TierConfig, type TierEscalationContext, type TierResolution, type ToolSpec, type TurnUsage, type UsageBreakdown, type UsageCost, VERSION, type VersionedRepo, type WorkflowCompliance, type WorkflowDef, type WorkflowRef, type WorkflowRunState, type WorkflowSpec, type WorkflowStep, type WorkflowTransition, allowListModelProvider, assertActorMayMutateDefinition, buildSingleAgentSwarm, buildSkillResolver, composePolicyPrompt, composeSystemPrompt, compositeTelemetry, containerFloor, createInMemoryRateLimitStore, createRunState, customAuth, customTelemetry, decideFixedWindow, defineAgent, defineBundle, defineClientTool, defineRule, defineSkill, defineSwarm, defineTool, defineWorkflow, drainTrajectory, ev, isEvent, isTierSentinel, mergeBundle, priceUsage, rateConfig, resolveTelemetry, resolveTier, runAgent, runToTrajectory, sumBreakdowns, sumTurnUsage, tierModelId, toBundleContent };