@nightowlsdev/core 0.3.0 → 0.5.0

package/dist/index.cjs

@@ -20,14 +20,21 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ALLOW: () => import_hooks4.ALLOW,
+  ALLOW_TOOL: () => import_hooks4.ALLOW_TOOL,
   ASK_TOOL_NAME: () => ASK_TOOL_NAME,
+  AgentMutationForbidden: () => AgentMutationForbidden,
   CapturingExporter: () => CapturingExporter,
+  ClientToolError: () => ClientToolError,
   CostGovernor: () => CostGovernor,
+  DEFAULT_READ_ONLY_TOOLS: () => import_hooks4.DEFAULT_READ_ONLY_TOOLS,
   DelegateBudgets: () => DelegateBudgets,
   GUARDRAILS: () => GUARDRAILS,
+  HookDispatcher: () => import_hooks4.HookDispatcher,
   InMemoryContainerFloor: () => InMemoryContainerFloor,
   InMemoryStorage: () => InMemoryStorage,
   PRICE_TABLE: () => PRICE_TABLE,
+  ReserveDenied: () => ReserveDenied,
   RowCache: () => RowCache,
   SCRATCHPAD_MAX_ENTRY_CHARS: () => SCRATCHPAD_MAX_ENTRY_CHARS,
   SCRATCHPAD_MAX_KEYS: () => SCRATCHPAD_MAX_KEYS,
@@ -35,23 +42,61 @@ __export(index_exports, {
   SwarmEngine: () => SwarmEngine,
   VERSION: () => VERSION,
   allowListModelProvider: () => allowListModelProvider,
+  ask: () => import_hooks4.ask,
+  assertActorMayMutateDefinition: () => assertActorMayMutateDefinition,
+  buildSingleAgentSwarm: () => buildSingleAgentSwarm,
   buildSkillResolver: () => buildSkillResolver,
+  composePolicyPrompt: () => composePolicyPrompt,
   composeSystemPrompt: () => composeSystemPrompt,
   compositeTelemetry: () => compositeTelemetry,
   containerFloor: () => containerFloor,
+  createHookDispatcher: () => import_hooks4.createHookDispatcher,
+  createInMemoryRateLimitStore: () => createInMemoryRateLimitStore,
+  createRunState: () => createRunState,
   customAuth: () => customAuth,
   customTelemetry: () => customTelemetry,
+  decideFixedWindow: () => decideFixedWindow,
   defineAgent: () => defineAgent,
+  defineBundle: () => defineBundle,
+  defineClientTool: () => defineClientTool,
+  defineHook: () => import_hooks4.defineHook,
+  defineRule: () => defineRule,
   defineSkill: () => defineSkill,
   defineSwarm: () => defineSwarm,
   defineTool: () => defineTool,
+  defineWorkflow: () => defineWorkflow,
+  deny: () => import_hooks4.deny,
+  drainTrajectory: () => drainTrajectory,
   ev: () => ev,
   isEvent: () => isEvent,
-  resolveTelemetry: () => resolveTelemetry
+  isTierSentinel: () => isTierSentinel,
+  mergeBundle: () => mergeBundle,
+  priceUsage: () => priceUsage,
+  rateConfig: () => rateConfig,
+  resolveTelemetry: () => resolveTelemetry,
+  resolveTier: () => resolveTier,
+  runAgent: () => runAgent,
+  runToTrajectory: () => runToTrajectory,
+  sumBreakdowns: () => sumBreakdowns,
+  sumTurnUsage: () => sumTurnUsage,
+  tierModelId: () => tierModelId,
+  toBundleContent: () => toBundleContent
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/types.ts
+function assertActorMayMutateDefinition(actor) {
+  if (actor.type === "agent") {
+    throw new AgentMutationForbidden(actor.agentSlug);
+  }
+}
+var AgentMutationForbidden = class extends Error {
+  code = "AGENT_MUTATION_FORBIDDEN";
+  constructor(agentSlug) {
+    super(`agent principal "${agentSlug}" may not mutate an agent definition (publish/rollback)`);
+    this.name = "AgentMutationForbidden";
+  }
+};
 var SCRATCHPAD_MAX_ENTRY_CHARS = 4e3;
 var SCRATCHPAD_MAX_KEYS = 64;
 
@@ -66,11 +111,269 @@ function isEvent(e, type) {
 // src/define.ts
 var import_zod4 = require("zod");
 var import_tools4 = require("@mastra/core/tools");
+var import_hooks3 = require("@nightowlsdev/hooks");
 
 // src/engine.ts
 var import_mastra = require("@mastra/core/mastra");
 var import_storage = require("@mastra/core/storage");
 var import_request_context = require("@mastra/core/request-context");
+var import_hooks = require("@nightowlsdev/hooks");
+
+// src/tool-gate.ts
+var TOOL_GATE_KEY = "__nightowlsdev_toolGate";
+var TOOL_EXECUTORS = /* @__PURE__ */ new WeakMap();
+function setToolExecutor(handle, exec) {
+  TOOL_EXECUTORS.set(handle, exec);
+}
+function getToolExecutor(handle) {
+  return TOOL_EXECUTORS.get(handle);
+}
+var ToolBlockedError = class extends Error {
+  constructor(toolName, reason) {
+    super(`tool "${toolName}" blocked: ${reason}`);
+    this.toolName = toolName;
+    this.reason = reason;
+    this.name = "ToolBlockedError";
+  }
+  toolName;
+  reason;
+  blocked = true;
+};
+function approvalSuspendPayload(args) {
+  const prompt = args.reason?.trim() ? `Approve \`${args.toolName}\`? ${args.reason.trim()}` : `Approve running \`${args.toolName}\`?`;
+  return {
+    to: "user",
+    prompt,
+    field: { kind: "confirm", confirmLabel: "Approve", rejectLabel: "Reject" },
+    asker: args.asker,
+    kind: "approval",
+    toolName: args.toolName
+  };
+}
+function isApproved(answer) {
+  if (typeof answer === "boolean") return answer;
+  if (typeof answer === "string") {
+    return /^(y|yes|approve|approved|ok|true|confirm|confirmed)$/i.test(answer.trim());
+  }
+  return false;
+}
+function gateErrMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+async function executeToolWithGate(opts) {
+  let decision;
+  try {
+    decision = await opts.gate(opts.ev);
+  } catch (err) {
+    return { ok: false, error: gateErrMessage(err), reason: gateErrMessage(err) };
+  }
+  if (decision.action === "deny") return { ok: false, error: decision.reason, reason: decision.reason };
+  if (decision.action === "ask") return { ok: false, suspended: true, reason: decision.reason };
+  try {
+    return { ok: true, result: await opts.run() };
+  } catch (err) {
+    return { ok: false, error: gateErrMessage(err) };
+  }
+}
+function toolPreCallEvent(args) {
+  return {
+    runId: args.runId,
+    tenantId: args.tenantId,
+    agentSlug: args.agentSlug,
+    toolName: args.toolName,
+    origin: args.origin,
+    needsApproval: args.needsApproval,
+    args: args.args
+  };
+}
+
+// src/secrets.ts
+var SECRET_RESOLVER_KEY = "__nightowlsdev_secretResolver";
+function bindSecrets(resolver, ctx) {
+  return {
+    resolve: (ref) => resolver ? resolver.resolve(ref, ctx) : Promise.resolve(void 0)
+  };
+}
+
+// src/run-state.ts
+var RUN_STATE_KEY = "__nightowls_run_state__";
+function snapshotCopy(store) {
+  const plain = Object.fromEntries(store);
+  try {
+    return (globalThis.structuredClone ?? ((v) => JSON.parse(JSON.stringify(v))))(plain);
+  } catch {
+    try {
+      return JSON.parse(JSON.stringify(plain));
+    } catch {
+      return plain;
+    }
+  }
+}
+function createRunState(seed) {
+  const m = new Map(seed ? Object.entries(seed) : void 0);
+  return {
+    get: (key) => m.get(key),
+    set: (key, value) => void m.set(key, value),
+    has: (key) => m.has(key),
+    delete: (key) => m.delete(key),
+    entries: () => snapshotCopy(m)
+  };
+}
+
+// src/step-driver.ts
+function initialWorkflowState(wf) {
+  return { workflow: wf.name, cursor: wf.start, outputs: {}, generationIndex: 0 };
+}
+function resolveRef(ref, state, input) {
+  if (ref === "input") return input.message;
+  if (ref.startsWith("steps.")) return state.outputs[ref.slice("steps.".length)];
+  return void 0;
+}
+function resolveValue(v, state, input) {
+  if (v && typeof v === "object" && "$ref" in v) {
+    const ref = String(v.$ref);
+    if (ref.startsWith("steps.")) {
+      const id = ref.slice("steps.".length);
+      if (!(id in state.outputs)) {
+        throw new Error(`workflow $ref "${ref}" references step "${id}" which has not run (skipped branch or forward reference)`);
+      }
+    }
+    return resolveRef(ref, state, input);
+  }
+  return v;
+}
+function resolveMap(o, state, input) {
+  if (!o) return void 0;
+  const out = {};
+  for (const [k, v] of Object.entries(o)) out[k] = resolveValue(v, state, input);
+  return out;
+}
+function agentMessage(step, resolvedInput) {
+  const base2 = step.instruction ?? "";
+  if (resolvedInput && Object.keys(resolvedInput).length) return `${base2}
+
+Context:
+${JSON.stringify(resolvedInput)}`;
+  return base2;
+}
+var DEAD_END = /* @__PURE__ */ Symbol("dead-end");
+function nextStep(step, state, input) {
+  if (step.next === void 0) return void 0;
+  if (typeof step.next === "string") return step.next;
+  for (const t of step.next) {
+    if (!t.when) return t.to;
+    const v = resolveRef(t.when.$ref, state, input);
+    if (t.when.exists !== void 0) {
+      if (v !== void 0 === t.when.exists) return t.to;
+      continue;
+    }
+    if (t.when.eq !== void 0) {
+      if (v === t.when.eq) return t.to;
+      continue;
+    }
+    return t.to;
+  }
+  return DEAD_END;
+}
+var StepDriver = class {
+  constructor(wf, deps) {
+    this.wf = wf;
+    this.deps = deps;
+  }
+  wf;
+  deps;
+  ts = 0;
+  base(ctx) {
+    return { runId: ctx.runId, agentSlug: ctx.agentSlug, ts: this.deps.nextTs ? this.deps.nextTs() : this.ts++ };
+  }
+  /**
+   * Drive the workflow from `state` (fresh or resumed). Yields the run's SwarmEvents. Returns a `DriveOutcome`
+   * so the engine can finalize. B2 scope: linear `agent`/`tool` steps + `$ref` wiring + per-step snapshot.
+   */
+  async *drive(state, ctx, input) {
+    const byId = new Map(this.wf.steps.map((s) => [s.id, s]));
+    let guard = 0;
+    let retryStep = "";
+    let retriesLeft = 0;
+    const budget = this.wf.steps.length * 8 + 8;
+    while (true) {
+      if (guard++ > budget) return { kind: "failed", stage: "workflow", message: "step budget exceeded" };
+      const step = byId.get(state.cursor);
+      if (!step) return { kind: "failed", stage: "workflow", message: `unknown step "${state.cursor}"` };
+      yield ev("swarm.status", this.base(ctx), { state: step.tool ? "tool" : "thinking", note: `step:${step.id}` });
+      let stepError;
+      if (step.agent !== void 0) {
+        try {
+          const msg = agentMessage(step, resolveMap(step.input, state, input));
+          const { text } = yield* this.deps.runAgentStep(step.agent, msg, state.generationIndex, ctx);
+          state.outputs[step.id] = text;
+          state.generationIndex += 1;
+        } catch (err) {
+          if (err && typeof err === "object" && "stage" in err) throw err;
+          stepError = err instanceof Error ? err.message : String(err);
+        }
+      } else if (step.tool !== void 0) {
+        let args;
+        try {
+          args = resolveMap(step.args, state, input) ?? {};
+        } catch (err) {
+          stepError = err instanceof Error ? err.message : String(err);
+        }
+        if (args !== void 0) {
+          const toolCallId = `${ctx.runId}:wf:${step.id}`;
+          yield ev("swarm.tool_call", this.base(ctx), { toolCallId, name: step.tool, args, needsApproval: false });
+          const r = await this.deps.runToolStep(step.tool, args, ctx);
+          yield ev("swarm.tool_result", this.base(ctx), { toolCallId, ok: r.ok, result: r.result, error: r.error });
+          if (r.ok) state.outputs[step.id] = r.result;
+          else if (r.suspended) {
+            const followupId = `${ctx.runId}:wf:${step.id}`;
+            yield ev("swarm.question", this.base(ctx), { followupId, toolCallId: followupId, to: "user", prompt: r.reason ?? `Approve "${step.tool}"?`, field: { kind: "confirm" } });
+            state.pending = { kind: "approval", stepId: step.id, followupId, toolCallId: followupId };
+            await this.deps.saveState(ctx.runId, state);
+            return { kind: "suspended", state };
+          } else stepError = r.error ?? r.reason ?? "blocked";
+        }
+      } else if (step.human !== void 0) {
+        if (!(step.id in state.outputs)) {
+          const followupId = `${ctx.runId}:wf:${step.id}`;
+          yield ev("swarm.question", this.base(ctx), { followupId, toolCallId: followupId, to: "user", prompt: step.human.prompt, field: step.human.field });
+          state.pending = { kind: "human", stepId: step.id, followupId, toolCallId: followupId };
+          await this.deps.saveState(ctx.runId, state);
+          return { kind: "suspended", state };
+        }
+        state.pending = void 0;
+      }
+      if (stepError !== void 0) {
+        const oe = step.onError ?? "fail";
+        if (oe === "fail") return { kind: "failed", stage: "workflow", message: `step "${step.id}" failed: ${stepError}` };
+        if (typeof oe === "object" && "to" in oe) {
+          state.cursor = oe.to;
+          retryStep = "";
+          await this.deps.saveState(ctx.runId, state);
+          continue;
+        }
+        if (typeof oe === "object" && "retry" in oe) {
+          if (retryStep !== step.id) {
+            retryStep = step.id;
+            retriesLeft = oe.retry;
+          }
+          if (retriesLeft > 0) {
+            retriesLeft -= 1;
+            await this.deps.saveState(ctx.runId, state);
+            continue;
+          }
+          return { kind: "failed", stage: "workflow", message: `step "${step.id}" failed after retries: ${stepError}` };
+        }
+      }
+      retryStep = "";
+      const next = nextStep(step, state, input);
+      if (next === DEAD_END) return { kind: "failed", stage: "workflow", message: `no transition from step "${step.id}"` };
+      state.cursor = next ?? state.cursor;
+      await this.deps.saveState(ctx.runId, state);
+      if (next === void 0) return { kind: "done" };
+    }
+  }
+};
 
 // src/mastra-map.ts
 var import_agent = require("@mastra/core/agent");
@@ -94,6 +397,16 @@ function composeSystemPrompt(row) {
     { role: "system", content: persona }
   ];
 }
+function composePolicyPrompt(lines) {
+  if (!lines.length) return [];
+  return [
+    {
+      role: "system",
+      content: `Policy \u2014 follow these unless the user explicitly overrides:
+${lines.map((l) => `- ${l}`).join("\n")}`
+    }
+  ];
+}
 function composeScratchpadPrompt(entries) {
   const render = (section) => {
     const rows = entries.filter((e) => e.section === section).map((e) => `- [${e.key}] (${e.author} \u2190 ${e.requestedBy}) ${e.content}`);
@@ -109,20 +422,100 @@ ${render("meta")}`
   return { role: "system", content };
 }
 
+// src/tier.ts
+var SENTINEL = "tier:";
+function isTierSentinel(modelId) {
+  return typeof modelId === "string" && modelId.startsWith(SENTINEL);
+}
+function requestedTierFrom(modelId, cfg) {
+  const suffix = modelId.slice(SENTINEL.length).trim();
+  if (suffix === "swift" || suffix === "genius") return suffix;
+  return cfg.default ?? "swift";
+}
+function resolveTier(modelId, cfg, ctx) {
+  if (!isTierSentinel(modelId)) {
+    return { modelId, downgraded: false };
+  }
+  let requested = requestedTierFrom(modelId, cfg);
+  let escalated = false;
+  if (cfg.escalate) {
+    const bumped = cfg.escalate(ctx);
+    if (bumped === "genius" && requested !== "genius") {
+      requested = "genius";
+      escalated = true;
+    }
+  }
+  if (requested === "genius") {
+    const geniusAllowed = cfg.allowGenius === true && typeof cfg.tiers.genius === "string";
+    if (geniusAllowed) {
+      return { modelId: cfg.tiers.genius, tier: "genius", downgraded: false, ...escalated ? { escalated: true } : {} };
+    }
+    return { modelId: cfg.tiers.swift, tier: "swift", downgraded: true, requestedTier: "genius" };
+  }
+  return { modelId: cfg.tiers.swift, tier: "swift", downgraded: false };
+}
+function tierModelId(modelId, cfg, ctx) {
+  if (!cfg) return modelId;
+  return resolveTier(modelId, cfg, ctx).modelId;
+}
+
 // src/mastra-map.ts
+async function gateDelegation(rc, subSlug) {
+  const gate = rc.get(TOOL_GATE_KEY);
+  if (!gate) return;
+  const decision = await gate(
+    toolPreCallEvent({
+      runId: rc.get("runId") ?? "",
+      tenantId: rc.get("tenantId") ?? "default",
+      // The agent doing the delegating is the run owner / the parent in the path (the requestContext's agentSlug).
+      agentSlug: rc.get("agentSlug") ?? "",
+      toolName: `agent-${subSlug}`,
+      origin: "first-party",
+      // A delegation has no per-tool `needsApproval` flag; surface false so a "flag"-mode policy leaves it
+      // un-gated (today's behaviour) and only an "all-side-effecting" policy / an explicit hook can deny it.
+      needsApproval: false,
+      args: void 0
+    })
+  );
+  if (decision.action === "deny") {
+    throw new Error(`delegation to "${subSlug}" denied: ${decision.reason}`);
+  }
+}
 var MAX_DELEGATION_DEPTH = 4;
+var CONNECTOR_TOOLS_CACHE_KEY = "__nightowls_connector_tools";
 function memoryFor(args, row) {
   return args.resolveMemory ? args.resolveMemory(row) : args.memory;
 }
-function toolsFor(args, row) {
+function toolsFor(args, row, connectorByName) {
   const out = { ...args.builtinTools ?? {} };
   for (const name of row.skillNames) {
-    const skill = args.resolveSkill(name);
+    const skill = args.resolveSkill(name) ?? connectorByName?.[name];
     const mt = skill && __getMastraTool(skill);
     if (mt) out[name] = mt;
   }
   return out;
 }
+async function connectorByNameFor(args, rc, agentSlug) {
+  if (!args.connectorTools) return {};
+  const cached = rc.get(CONNECTOR_TOOLS_CACHE_KEY);
+  if (cached) return cached;
+  const resolve = args.connectorTools;
+  const build = (async () => {
+    const ctx = {
+      tenantId: rc.get("tenantId") ?? "default",
+      userId: rc.get("userId") ?? "",
+      runId: rc.get("runId") ?? "",
+      agentSlug,
+      // informational — materialize is tenant-scoped; first caller's slug seeds the shared cache
+      threadId: rc.get("threadId") ?? ""
+    };
+    const out = {};
+    for (const t of await resolve(ctx)) out[t.name] = t;
+    return out;
+  })();
+  rc.set?.(CONNECTOR_TOOLS_CACHE_KEY, build);
+  return build;
+}
 async function withScratchpad(args, base2, rc) {
   if (!args.loadScratchpad) return base2;
   const tenantId = rc.get("tenantId") ?? "default";
@@ -130,8 +523,13 @@ async function withScratchpad(args, base2, rc) {
   const entries = await args.loadScratchpad(container, tenantId);
   return [...base2, composeScratchpadPrompt(entries)];
 }
+function withSoftPolicy(args, base2, slug) {
+  const soft = args.softPolicy?.(slug) ?? [];
+  return soft.length ? [...base2, ...composePolicyPrompt(soft)] : base2;
+}
 async function modelFor(args, row, tenantId) {
-  const id = await args.model.resolve(row.modelId, { tenantId });
+  const effective = tierModelId(row.modelId, args.tier, { tenantId, agentSlug: row.slug, pinnedModelId: row.modelId });
+  const id = await args.model.resolve(effective, { tenantId });
   return args.modelFactory(id, row.slug);
 }
 function buildSubAgent(args, row, depth, path) {
@@ -143,9 +541,12 @@ function buildSubAgent(args, row, depth, path) {
     // personality so the orchestrator's LLM knows WHAT this delegate is for (role is a coarse enum).
     description: row.personality || `Agent ${row.slug} (${row.role})`,
     ...memoryFor(args, row) ? { memory: memoryFor(args, row) } : {},
-    instructions: async ({ requestContext }) => withScratchpad(args, composeSystemPrompt(row), requestContext),
+    instructions: async ({ requestContext }) => {
+      await gateDelegation(requestContext, row.slug);
+      return withScratchpad(args, withSoftPolicy(args, composeSystemPrompt(row), row.slug), requestContext);
+    },
     model: async ({ requestContext }) => await modelFor(args, row, requestContext.get("tenantId") ?? "default"),
-    tools: toolsFor(args, row),
+    tools: (async ({ requestContext }) => toolsFor(args, row, await connectorByNameFor(args, requestContext, row.slug))),
     agents: async ({ requestContext }) => await buildSubAgentMap(
       args,
       row.delegateSlugs ?? [],
@@ -174,9 +575,16 @@ function buildMastraAgent(args) {
     // request). If Mastra rejects a dynamic `memory`, fall back to the static swarm Memory (root override is
     // then sub-agents-only — see the spec's accepted limitation).
     ...args.resolveMemory || args.memory ? { memory: (async ({ requestContext }) => memoryFor(args, await load(requestContext))) } : {},
-    instructions: async ({ requestContext }) => withScratchpad(args, composeSystemPrompt(await load(requestContext)), requestContext),
+    instructions: async ({ requestContext }) => {
+      const row = await load(requestContext);
+      return withScratchpad(args, withSoftPolicy(args, composeSystemPrompt(row), row.slug), requestContext);
+    },
     model: async ({ requestContext }) => await modelFor(args, await load(requestContext), requestContext.get("tenantId") ?? "default"),
-    tools: async ({ requestContext }) => ({ ...args.extraTools ?? {}, ...toolsFor(args, await load(requestContext)) }),
+    tools: (async ({ requestContext }) => {
+      const row = await load(requestContext);
+      const connectorByName = await connectorByNameFor(args, requestContext, row.slug);
+      return { ...args.extraTools ?? {}, ...toolsFor(args, row, connectorByName) };
+    }),
     // Delegation: the orchestrator's delegateSlugs become `agent-<slug>` tools (Mastra-native).
     agents: async ({ requestContext }) => {
       const row = await load(requestContext);
@@ -191,7 +599,7 @@ var import_tools = require("@mastra/core/tools");
 var import_zod = require("zod");
 
 // src/page-context.ts
-var PAGE_CONTEXT_KEY = "nightowls.pageContext";
+var PAGE_CONTEXT_KEY = "__nightowlsdev_pageContext";
 function attachPageContext(rc, value) {
   rc.set(PAGE_CONTEXT_KEY, value ?? {});
 }
@@ -398,7 +806,7 @@ var InMemoryContainerFloor = class {
     s.held = who;
     if (s.timer) clearTimeout(s.timer);
     s.timer = setTimeout(() => {
-      console.warn(`[nightowls] container floor force-released after ${this.maxHoldMs}ms: ${container} (held by ${who.label})`);
+      console.warn(`[@nightowlsdev/core] container floor force-released after ${this.maxHoldMs}ms: ${container} (held by ${who.label})`);
       this.release(container, s, who);
     }, this.maxHoldMs);
     if (typeof s.timer.unref === "function") s.timer.unref();
@@ -433,25 +841,84 @@ var PRICE_TABLE = {
   "openai/gpt-5.5": { inUsdPerMtok: 2.5, outUsdPerMtok: 10 },
   "openai/gpt-5.5-mini": { inUsdPerMtok: 0.3, outUsdPerMtok: 1.2 }
 };
-function priceUsage(prices, modelId, u) {
-  const p = prices[modelId] ?? { inUsdPerMtok: 0, outUsdPerMtok: 0 };
-  return u.inputTokens / 1e6 * p.inUsdPerMtok + u.outputTokens / 1e6 * p.outUsdPerMtok;
+function priceUsage(prices, modelId, u, opts = {}) {
+  const p = prices[modelId];
+  if (!p) {
+    if (opts.failOnUnknownModel) {
+      throw new Error(
+        `[@nightowlsdev/core] no price entry for model '${modelId}' (failOnUnknownModel=true). Add it to PRICE_TABLE, the swarm cost.prices map, or a priceFeed.`
+      );
+    }
+    return 0;
+  }
+  const cacheReadRate = p.cacheReadUsdPerMtok ?? p.inUsdPerMtok;
+  const cacheWriteRate = p.cacheWriteUsdPerMtok ?? p.inUsdPerMtok;
+  const reasoningRate = p.reasoningUsdPerMtok ?? p.outUsdPerMtok;
+  const M = 1e6;
+  return (u.inputTokens ?? 0) / M * p.inUsdPerMtok + (u.outputTokens ?? 0) / M * p.outUsdPerMtok + (u.cacheReadTokens ?? 0) / M * cacheReadRate + (u.cacheWriteTokens ?? 0) / M * cacheWriteRate + (u.reasoningTokens ?? 0) / M * reasoningRate;
+}
+var OPTIONAL_USAGE_CLASSES = [
+  "cacheReadTokens",
+  "cacheWriteTokens",
+  "reasoningTokens",
+  "toolCalls",
+  "agentActivations"
+];
+function sumBreakdowns(items) {
+  const total = { inputTokens: 0, outputTokens: 0 };
+  for (const b of items) {
+    total.inputTokens += b.inputTokens ?? 0;
+    total.outputTokens += b.outputTokens ?? 0;
+    for (const k of OPTIONAL_USAGE_CLASSES) {
+      const v = b[k];
+      if (v != null) total[k] = (total[k] ?? 0) + v;
+    }
+  }
+  return total;
+}
+function sumTurnUsage(items) {
+  const order = [];
+  const breakdownsBySlug = /* @__PURE__ */ new Map();
+  const usdBySlug = /* @__PURE__ */ new Map();
+  for (const it of items) {
+    if (!breakdownsBySlug.has(it.slug)) {
+      order.push(it.slug);
+      breakdownsBySlug.set(it.slug, []);
+      usdBySlug.set(it.slug, 0);
+    }
+    breakdownsBySlug.get(it.slug).push(it.breakdown);
+    usdBySlug.set(it.slug, usdBySlug.get(it.slug) + it.cost.usd);
+  }
+  const bySlug = order.map((slug) => {
+    const breakdown2 = sumBreakdowns(breakdownsBySlug.get(slug));
+    const usd2 = usdBySlug.get(slug);
+    return { slug, breakdown: breakdown2, cost: { usd: usd2, breakdown: breakdown2 } };
+  });
+  const breakdown = sumBreakdowns(items.map((it) => it.breakdown));
+  const usd = items.reduce((a, it) => a + it.cost.usd, 0);
+  return { breakdown, cost: { usd, breakdown }, bySlug };
 }
 var CostGovernor = class {
   constructor(opts) {
     this.opts = opts;
-    this.prices = { ...PRICE_TABLE, ...opts.prices ?? {} };
+    this.prices = { ...PRICE_TABLE, ...opts.prices ?? {}, ...opts.priceFeed?.prices() ?? {} };
+    this.failOnUnknownModel = opts.failOnUnknownModel ?? false;
   }
   opts;
   steps = 0;
   usd = 0;
   prices;
+  failOnUnknownModel;
   step() {
     this.steps++;
   }
   /** Price a single usage WITHOUT accumulating it (for per-generation telemetry cost). */
   priceOf(modelId, u) {
-    return priceUsage(this.prices, modelId, u);
+    return priceUsage(this.prices, modelId, u, { failOnUnknownModel: this.failOnUnknownModel });
+  }
+  /** Price a single usage WITHOUT accumulating it, returning the usd + the breakdown it was priced from. */
+  costOf(modelId, u) {
+    return { usd: this.priceOf(modelId, u), breakdown: u };
   }
   addUsage(modelId, u) {
     this.usd += this.priceOf(modelId, u);
@@ -459,6 +926,19 @@ var CostGovernor = class {
   costUsd() {
     return this.usd;
   }
+  /** The current USD cap (SP9-core: the cap-that-asks reads this to surface "spend / cap" + to compute the raise). */
+  get maxCostUsd() {
+    return this.opts.maxCostUsd;
+  }
+  /**
+   * 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) {
+    this.opts.maxCostUsd += incrementUsd;
+  }
   shouldStop() {
     if (this.steps >= this.opts.maxSteps) return { stop: true, reason: "step cap reached" };
     if (this.usd >= this.opts.maxCostUsd) return { stop: true, reason: "USD cap reached" };
@@ -466,15 +946,17 @@ var CostGovernor = class {
   }
 };
 var DelegateBudgets = class {
-  constructor(cfg, rootSlug, prices) {
+  constructor(cfg, rootSlug, pricing) {
     this.cfg = cfg;
     this.rootSlug = rootSlug;
-    this.prices = { ...PRICE_TABLE, ...prices ?? {} };
+    this.prices = { ...PRICE_TABLE, ...pricing?.prices ?? {}, ...pricing?.priceFeed?.prices() ?? {} };
+    this.failOnUnknownModel = pricing?.failOnUnknownModel ?? false;
   }
   cfg;
   rootSlug;
   usd = /* @__PURE__ */ new Map();
   prices;
+  failOnUnknownModel;
   /** The USD cap for a delegate: its `bySlug` override if present, else the default. `undefined` → uncapped. */
   capFor(slug) {
     return this.cfg.bySlug?.[slug]?.maxCostUsd ?? this.cfg.maxCostUsd;
@@ -482,7 +964,10 @@ var DelegateBudgets = class {
   /** Accumulate one generation's usage against a delegate. No-op for the root orchestrator (not a delegate). */
   addUsage(slug, modelId, u) {
     if (slug === this.rootSlug) return;
-    this.usd.set(slug, (this.usd.get(slug) ?? 0) + priceUsage(this.prices, modelId, u));
+    this.usd.set(
+      slug,
+      (this.usd.get(slug) ?? 0) + priceUsage(this.prices, modelId, u, { failOnUnknownModel: this.failOnUnknownModel })
+    );
   }
   /** The first delegate that has met or exceeded its USD cap, or null. */
   exceeded() {
@@ -510,7 +995,7 @@ function compositeTelemetry(exporters) {
       const results = await Promise.allSettled(exporters.map((e) => e.export(spans)));
       for (const r of results) {
         if (r.status === "rejected") {
-          console.warn("[nightowls] telemetry exporter failed:", r.reason);
+          console.warn("[@nightowlsdev/core] telemetry exporter failed:", r.reason);
         }
       }
     }
@@ -557,10 +1042,17 @@ var SpanCollector = class {
    */
   closeGeneration(usage, costUsd) {
     if (!this.gen) return;
+    const extra = {};
+    if (usage.cacheReadTokens != null) extra.cacheReadTokens = usage.cacheReadTokens;
+    if (usage.cacheWriteTokens != null) extra.cacheWriteTokens = usage.cacheWriteTokens;
+    if (usage.reasoningTokens != null) extra.reasoningTokens = usage.reasoningTokens;
+    if (usage.toolCalls != null) extra.toolCalls = usage.toolCalls;
+    if (usage.agentActivations != null) extra.agentActivations = usage.agentActivations;
     this.gen.attributes = {
       ...this.gen.attributes,
       inputTokens: usage.inputTokens,
       outputTokens: usage.outputTokens,
+      ...extra,
       costUsd: Math.max(0, costUsd)
     };
     this.gen.endedAt = this.now();
@@ -644,6 +1136,21 @@ var RowCache = class {
 
 // src/engine.ts
 var AGENT_KEY = "swarm";
+var MAX_CONTINUE_NUDGES = 2;
+var CONTINUE_NUDGE = "[automated] Your previous turn ended without any message or tool call. If you have fully completed everything that was asked, give the final result now. Otherwise continue and finish every remaining step you intended \u2014 do not end your turn until the task is done.";
+function verifyNudge(missing) {
+  const gap = (missing ?? "").trim();
+  return gap ? `[automated] The task is NOT finished yet \u2014 still missing: ${gap}. Continue now and complete every remaining step. Do not end your turn until it is fully done.` : CONTINUE_NUDGE;
+}
+var VERIFY_TRANSCRIPT_CAP = 6e3;
+function appendTranscript(t, e) {
+  let add = "";
+  if (e.type === "swarm.message") add = e.data.delta ?? e.data.text ?? "";
+  else if (e.type === "swarm.tool_call") add = `
+\xAB${e.agentSlug} \u2192 ${e.data.name}\xBB
+`;
+  return add ? (t + add).slice(-VERIFY_TRANSCRIPT_CAP) : t;
+}
 var SwarmEngine = class {
   constructor(opts) {
     this.opts = opts;
@@ -653,6 +1160,7 @@ var SwarmEngine = class {
     const { memory, resolveMemory } = opts.memory ? buildMemoryResolver(opts.memory) : { memory: void 0, resolveMemory: void 0 };
     this.memory = memory;
     this.floor = opts.floor ?? containerFloor;
+    this.hooks = opts.hooks ?? new import_hooks.HookDispatcher({}, opts.toolApproval ?? { mode: "flag" });
     opts.storage.subscribeInvalidations?.((key) => this.rowCache.invalidate(key));
     const agent = buildMastraAgent({
       loadRow: (slug, tenantId) => this.loadRow(tenantId, slug),
@@ -660,6 +1168,8 @@ var SwarmEngine = class {
       resolveSkill: (n) => opts.resolveSkill?.(n),
       model: opts.model,
       modelFactory: opts.modelFactory,
+      // SP10: hand the cheap-model router to the per-agent model resolver. Undefined ⇒ no routing (today).
+      tier: opts.tier,
       builtinTools: {
         [ASK_TOOL_NAME]: buildAskMastraTool(),
         ...opts.scratchpad ? { scratchpad_write: buildScratchpadTool(opts.storage.scratchpad, typeof opts.scratchpad === "object" ? opts.scratchpad : void 0) } : {},
@@ -669,6 +1179,9 @@ var SwarmEngine = class {
       // ONLY (never sub-agents) so the model can pull the host page's advisory RunInput.context.
       ...opts.pageContext ? { extraTools: { get_page_context: buildPageContextTool() } } : {},
       loadScratchpad: opts.scratchpad ? (c, t) => opts.storage.scratchpad.list(t, c) : void 0,
+      softPolicy: opts.softPolicy,
+      // PR2: per-request connector-tools resolver, granted to the orchestrator + sub-agents by skillNames.
+      connectorTools: opts.connectorTools,
       memory
     });
     this.mastra = new import_mastra.Mastra({
@@ -687,6 +1200,51 @@ var SwarmEngine = class {
   // Typed `unknown` to keep the engine wall: no engine-vendor type escapes the public surface.
   memory;
   floor;
+  // SP2: the decision-hook dispatcher. Always present — defaults to an allow-all dispatcher when the engine is
+  // built without one (e.g. unit tests), so the preGeneration seam is uniform with no per-call null checks.
+  hooks;
+  /** 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`). */
+  pricingOpts() {
+    return {
+      prices: this.opts.cost.prices,
+      priceFeed: this.opts.cost.priceFeed,
+      failOnUnknownModel: this.opts.cost.failOnUnknownModel
+    };
+  }
+  /** 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. */
+  async notifyEvent(e, ctx) {
+    if (!this.opts.onEvent) return;
+    try {
+      await this.opts.onEvent(e, ctx);
+    } catch {
+    }
+  }
+  /** 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. */
+  async safeVerify(request, transcript, ctx) {
+    if (!this.opts.verifyCompletion) return { complete: true };
+    try {
+      return await this.opts.verifyCompletion({ request, transcript, ctx });
+    } catch (err) {
+      console.error(`[@nightowlsdev/core] verifyCompletion threw for run ${ctx.runId} \u2014 treating as complete:`, err);
+      return { complete: true };
+    }
+  }
+  /** 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. */
+  async recallRequest(ctx) {
+    if (!this.opts.verifyCompletion) return "";
+    try {
+      const msgs = await this.history(ctx.threadId, ctx, { limit: 50 });
+      return msgs.find((m) => m.role === "user")?.text ?? "";
+    } catch {
+      return "";
+    }
+  }
   /** Cached agent-row load shared by the three dynamic agent fns AND run/resume. */
   loadRow(tenantId, slug) {
     return this.rowCache.get(`${tenantId}:${slug}`, async () => {
@@ -695,16 +1253,60 @@ var SwarmEngine = class {
       return row;
     });
   }
+  /** 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.) */
+  priceModelId(rawModelId, tenantId, agentSlug) {
+    return tierModelId(rawModelId, this.opts.tier, { tenantId, agentSlug, pinnedModelId: rawModelId });
+  }
   agent() {
     return this.mastra.getAgent(AGENT_KEY);
   }
-  requestContext(ctx) {
+  requestContext(ctx, state) {
     const rc = new import_request_context.RequestContext();
     for (const [k, v] of Object.entries(ctx)) {
       if (v !== void 0) rc.set(k, v);
     }
+    rc.set(TOOL_GATE_KEY, this.toolGate);
+    if (this.opts.secrets) rc.set(SECRET_RESOLVER_KEY, this.opts.secrets);
+    if (state) rc.set(RUN_STATE_KEY, state);
     return rc;
   }
+  /**
+   * 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).
+   */
+  toolGate = (ev2) => this.hooks.preToolCall(ev2);
+  /**
+   * 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.
+   */
+  gatesApproval(toolName) {
+    const skill = this.opts.resolveSkill?.(toolName);
+    const origin = skill?.origin ?? "first-party";
+    const needsApproval = skill?.needsApproval ?? origin === "mcp";
+    const decision = this.hooks.policyDecision({ runId: "", agentSlug: "", toolName, origin, needsApproval });
+    return decision.action === "ask";
+  }
+  /**
+   * 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).
+   */
+  async guardGeneration(ev2) {
+    const decision = await this.hooks.preGeneration(ev2);
+    if (decision.action === "deny") throw new ReserveDenied(decision.reason);
+  }
   /** Per-call Mastra memory ids + delegation, only when memory is configured (else stream is unchanged). */
   memoryOpts(ctx) {
     if (!this.opts.memory) return {};
@@ -914,6 +1516,13 @@ var SwarmEngine = class {
   async activeRuns(container, ctx) {
     return this.opts.storage.runs.listActive(ctx.tenantId, container);
   }
+  /** 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). */
+  async threadEvents(threadId, ctx) {
+    const container = threadId.split(":")[0] || threadId;
+    return await this.opts.storage.events.listForContainer?.(ctx.tenantId, container) ?? [];
+  }
   /** 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. */
@@ -928,7 +1537,12 @@ var SwarmEngine = class {
     }));
   }
   async *run(input, ctx) {
-    const modelId = (await this.loadRow(ctx.tenantId, ctx.agentSlug)).modelId ?? "unknown";
+    const modelId = this.priceModelId((await this.loadRow(ctx.tenantId, ctx.agentSlug)).modelId ?? "unknown", ctx.tenantId, ctx.agentSlug);
+    const workflowDef = input.workflow ? this.opts.workflows?.find((w) => w.name === input.workflow) : this.opts.agentWorkflows?.[ctx.agentSlug];
+    if (input.workflow && !workflowDef) throw new Error(`unknown workflow: ${input.workflow}`);
+    if (this.opts.storage.threads) {
+      await this.opts.storage.threads.ensure({ id: ctx.threadId, orgId: ctx.tenantId, userId: ctx.userId });
+    }
     await this.opts.storage.runs.create({
       runId: ctx.runId,
       tenantId: ctx.tenantId,
@@ -936,18 +1550,40 @@ var SwarmEngine = class {
       threadId: ctx.threadId,
       agentSlug: ctx.agentSlug
     });
-    const modelIdFor = (slug) => this.rowCache.peek(`${ctx.tenantId}:${slug}`)?.modelId ?? modelId;
+    const modelIdFor = (slug) => {
+      const raw = this.rowCache.peek(`${ctx.tenantId}:${slug}`)?.modelId;
+      return raw ? this.priceModelId(raw, ctx.tenantId, slug) : modelId;
+    };
+    const gatesApproval = (name) => this.gatesApproval(name);
     const gov = new CostGovernor(this.opts.cost);
-    const delegateBudgets = this.opts.cost.perDelegate ? new DelegateBudgets(this.opts.cost.perDelegate, ctx.agentSlug) : null;
+    const delegateBudgets = this.opts.cost.perDelegate ? new DelegateBudgets(this.opts.cost.perDelegate, ctx.agentSlug, this.pricingOpts()) : null;
     const streamed = /* @__PURE__ */ new Set();
-    const rc = this.requestContext(ctx);
+    const activity = /* @__PURE__ */ new Map();
+    const turnUsage = [];
+    const runState = createRunState();
+    const rc = this.requestContext(ctx, runState);
     if (this.opts.pageContext) attachPageContext(rc, input.context);
+    let outcome = "failed";
+    if (this.opts.onRunStart) {
+      try {
+        await this.opts.onRunStart(ctx, { input, state: runState });
+      } catch (err) {
+        console.error(`[@nightowlsdev/core] onRunStart threw for run ${ctx.runId}:`, err);
+      }
+    }
     const collector = this.opts.telemetry ? new SpanCollector(ctx.runId, () => Date.now(), "run", { agentSlug: ctx.agentSlug }) : null;
     let ts = 0;
     const emit = async (e) => {
       e.seq = await this.opts.storage.events.append(e);
+      await this.notifyEvent(e, ctx);
       return e;
     };
+    let turnEmitted = false;
+    const emitTurn = async () => {
+      if (turnEmitted) return null;
+      turnEmitted = true;
+      return emit(turnUsageEvent(ctx, ts++, turnUsage, 0));
+    };
     const floorKey = ctx.threadId;
     const me = { label: titleCase(ctx.agentSlug), runId: ctx.runId };
     const floorAbort = new AbortController();
@@ -961,96 +1597,298 @@ var SwarmEngine = class {
         if (floorAbort.signal.aborted) return;
       }
       yield await emit(ev("swarm.status", base(ctx, ts++), { state: "thinking" }));
+      if (workflowDef) {
+        const wfMessage = input.message.replace(/^(\[user:[^\]]*\]\s*)+/, "");
+        await emit(ev("swarm.message", base(ctx, ts++), { role: "user", text: wfMessage }));
+        outcome = yield* this.driveWorkflow(workflowDef, initialWorkflowState(workflowDef), ctx, { message: wfMessage, context: input.context }, {
+          gov,
+          modelIdFor,
+          streamed,
+          delegateBudgets,
+          activity,
+          gatesApproval,
+          turnUsage,
+          nextTs: () => ts++,
+          emit,
+          emitTurn,
+          segmentIndex: 0,
+          // FR-004: a run segment starts at generation 0
+          state: runState
+          // FR-003: workflow steps' tools see the run's ctx.state
+        });
+        return;
+      }
+      const generationIndex = 0;
+      await this.guardGeneration({ runId: ctx.runId, tenantId: ctx.tenantId, agentSlug: ctx.agentSlug, modelId, generationIndex, kind: "run" });
       const userMessage = input.message.replace(/^(\[user:[^\]]*\]\s*)+/, "");
-      const result = await this.agent().stream(userMessage, { runId: ctx.runId, requestContext: rc, ...this.memoryOpts(ctx) });
-      for await (const part of result.fullStream) {
-        if (part?.type === "step-finish") gov.step();
-        if (part?.type === "tool-call-suspended") {
-          const payload = part.payload ?? {};
-          const toolCallId = payload.toolCallId ?? "";
-          const followupId = `${ctx.runId}:${toolCallId}`;
-          const sp = payload.suspendPayload ?? {};
-          await recordSuspend(this.opts.storage, ctx, followupId, toolCallId);
-          await this.opts.storage.runs.setStatus(ctx.runId, "suspended");
-          await this.opts.storage.runs.saveSnapshot(ctx.runId, { pending: { toolCallId } });
-          yield await emit(ev("swarm.status", base(ctx, ts++), { state: "waiting" }));
-          yield await emit(
-            ev("swarm.question", base(ctx, ts++), {
-              followupId,
-              toolCallId,
-              to: sp.to ?? "user",
-              from: sp.asker || ctx.agentSlug,
-              // the agent that actually asked (a delegate), for UI attribution
-              prompt: sp.prompt ?? "",
-              field: sp.field
-            })
-          );
-          return;
-        }
-        if (part?.type === "error") {
-          await this.opts.storage.runs.setStatus(ctx.runId, "failed");
-          yield await emit(
-            ev("swarm.run_failed", base(ctx, ts++), {
-              stage: "stream",
-              message: streamErrorMessage(part),
-              retryable: false
-            })
-          );
-          return;
+      await emit(ev("swarm.message", base(ctx, ts++), { role: "user", text: userMessage }));
+      let turnMessage = userMessage;
+      let continueNudges = 0;
+      let transcript = "";
+      let incompleteVerdict = null;
+      for (; ; ) {
+        const result = await this.agent().stream(turnMessage, { runId: ctx.runId, requestContext: rc, ...this.memoryOpts(ctx) });
+        let sawStep = false;
+        let lastOutputSlug;
+        for await (const part of result.fullStream) {
+          if (part?.type === "step-finish") {
+            gov.step();
+            sawStep = true;
+          }
+          if (part?.type === "tool-call-suspended") {
+            const payload = part.payload ?? {};
+            const toolCallId = payload.toolCallId ?? "";
+            const followupId = `${ctx.runId}:${toolCallId}`;
+            const sp = payload.suspendPayload ?? {};
+            await recordSuspend(this.opts.storage, ctx, followupId, toolCallId);
+            await this.opts.storage.runs.setStatus(ctx.runId, "suspended");
+            await this.opts.storage.runs.saveSnapshot(ctx.runId, { pending: { toolCallId }, genIndex: generationIndex + 1, state: runState.entries() });
+            {
+              const t = await emitTurn();
+              if (t) yield t;
+            }
+            yield await emit(ev("swarm.status", base(ctx, ts++), { state: "waiting" }));
+            yield await emit(clientActionOrQuestion(ctx, ts++, followupId, toolCallId, sp));
+            outcome = "suspended";
+            return;
+          }
+          if (part?.type === "error") {
+            await this.opts.storage.runs.setStatus(ctx.runId, "failed");
+            {
+              const t = await emitTurn();
+              if (t) yield t;
+            }
+            yield await emit(
+              ev("swarm.run_failed", base(ctx, ts++), {
+                stage: "stream",
+                message: streamErrorMessage(part),
+                retryable: false
+              })
+            );
+            return;
+          }
+          for (const e of mapChunk(part, ctx, gov, modelIdFor, () => ts++, streamed, delegateBudgets, activity, gatesApproval, turnUsage, 0)) {
+            if (e.type === "swarm.message" || e.type === "swarm.tool_call") {
+              lastOutputSlug = e.agentSlug;
+              if (this.opts.verifyCompletion) transcript = appendTranscript(transcript, e);
+            }
+            yield await emit(e);
+          }
+          collectSpans(collector, part, modelId, gov);
+          const overDelegate = delegateBudgets?.exceeded();
+          const stop = gov.shouldStop();
+          if (stop.stop || overDelegate) {
+            if (this.opts.cost.onCapHit === "ask" && stop.stop && !overDelegate) {
+              const followupId = `${ctx.runId}:${CAP_FOLLOWUP_SUFFIX}`;
+              await recordSuspend(this.opts.storage, ctx, followupId, CAP_FOLLOWUP_SUFFIX);
+              await this.opts.storage.runs.setStatus(ctx.runId, "suspended");
+              await this.opts.storage.runs.saveSnapshot(ctx.runId, {
+                capHit: { message: userMessage, spentUsd: gov.costUsd() },
+                genIndex: generationIndex + 1,
+                state: runState.entries()
+                // FR-003: persist per-run state across the cap-ask boundary
+              });
+              {
+                const t = await emitTurn();
+                if (t) yield t;
+              }
+              yield await emit(ev("swarm.status", base(ctx, ts++), { state: "waiting" }));
+              yield await emit(ev("swarm.question", base(ctx, ts++), capQuestion(ctx, followupId, gov)));
+              outcome = "suspended";
+              return;
+            }
+            await this.opts.storage.runs.setStatus(ctx.runId, "failed");
+            {
+              const t = await emitTurn();
+              if (t) yield t;
+            }
+            yield await emit(
+              ev("swarm.run_failed", base(ctx, ts++), {
+                stage: "cost",
+                message: overDelegate?.reason ?? stop.reason,
+                retryable: false
+              })
+            );
+            return;
+          }
         }
-        for (const e of mapChunk(part, ctx, gov, modelIdFor, () => ts++, streamed, delegateBudgets)) yield await emit(e);
-        collectSpans(collector, part, modelId, gov);
-        const overDelegate = delegateBudgets?.exceeded();
-        if (gov.shouldStop().stop || overDelegate) {
-          await this.opts.storage.runs.setStatus(ctx.runId, "failed");
-          yield await emit(
-            ev("swarm.run_failed", base(ctx, ts++), {
-              stage: "cost",
-              message: overDelegate?.reason ?? gov.shouldStop().reason,
-              retryable: false
-            })
-          );
-          return;
+        if (this.opts.verifyCompletion) {
+          const verdict = await this.safeVerify(userMessage, transcript, ctx);
+          if (!verdict.complete && continueNudges < MAX_CONTINUE_NUDGES) {
+            continueNudges++;
+            turnMessage = verifyNudge(verdict.missing);
+            continue;
+          }
+          incompleteVerdict = verdict.complete ? null : verdict;
+        } else if (sawStep && lastOutputSlug !== ctx.agentSlug && continueNudges < MAX_CONTINUE_NUDGES) {
+          continueNudges++;
+          turnMessage = CONTINUE_NUDGE;
+          continue;
         }
+        break;
       }
       await this.mirrorDelegations(ctx);
       await this.attributeRun(ctx);
-      await this.opts.storage.runs.setStatus(ctx.runId, "done");
-      yield await emit(ev("swarm.status", base(ctx, ts++), { state: "done" }));
+      if (incompleteVerdict) {
+        await this.opts.storage.runs.setStatus(ctx.runId, "failed");
+        {
+          const t = await emitTurn();
+          if (t) yield t;
+        }
+        yield await emit(ev("swarm.run_failed", base(ctx, ts++), { stage: "incomplete", message: incompleteVerdict.missing ?? "The task was not completed.", retryable: true }));
+      } else {
+        await this.opts.storage.runs.setStatus(ctx.runId, "done");
+        {
+          const t = await emitTurn();
+          if (t) yield t;
+        }
+        yield await emit(ev("swarm.status", base(ctx, ts++), { state: "done" }));
+        outcome = "done";
+      }
     } catch (err) {
-      console.error(`[nightowls] run ${ctx.runId} threw:`, err);
+      const stage = err instanceof ReserveDenied ? "reserve" : "exception";
+      if (stage !== "reserve") console.error(`[@nightowlsdev/core] run ${ctx.runId} threw:`, err);
       try {
         await this.opts.storage.runs.setStatus(ctx.runId, "failed");
       } catch {
       }
-      yield await emit(ev("swarm.run_failed", base(ctx, ts++), { stage: "exception", message: errMessage(err), retryable: false }));
+      {
+        const t = await emitTurn();
+        if (t) yield t;
+      }
+      yield await emit(ev("swarm.run_failed", base(ctx, ts++), { stage, message: errMessage(err), retryable: false }));
     } finally {
+      if (this.opts.onRunEnd) {
+        try {
+          await this.opts.onRunEnd(ctx, { state: runState, outcome });
+        } catch (err) {
+          console.error(`[@nightowlsdev/core] onRunEnd threw for run ${ctx.runId}:`, err);
+        }
+      }
       floorAbort.abort();
       await releaseFloor?.();
       await exportSpans(this.opts.telemetry, collector);
     }
   }
+  /**
+   * 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.
+   */
+  async *driveWorkflow(wf, state, ctx, input, m) {
+    const driver = new StepDriver(wf, {
+      nextTs: m.nextTs,
+      runAgentStep: (slug, message, genIndex) => this.streamWorkflowAgentStep(slug, message, genIndex, ctx, input, m),
+      runToolStep: (toolName, args) => this.runWorkflowToolStep(toolName, args, ctx, m.state),
+      saveState: (rid, st) => this.opts.storage.runs.saveSnapshot(rid, { workflow: st })
+    });
+    const it = driver.drive(state, ctx, input);
+    let r = await it.next();
+    while (!r.done) {
+      yield await m.emit(r.value);
+      r = await it.next();
+    }
+    const outcome = r.value;
+    if (outcome.kind === "suspended") {
+      const p = outcome.state.pending;
+      await recordSuspend(this.opts.storage, ctx, p.followupId, p.toolCallId);
+      await this.opts.storage.runs.setStatus(ctx.runId, "suspended");
+      yield await m.emit(ev("swarm.status", base(ctx, m.nextTs()), { state: "waiting" }));
+      {
+        const t = await m.emitTurn();
+        if (t) yield t;
+      }
+      return "suspended";
+    }
+    if (outcome.kind === "failed") {
+      await this.opts.storage.runs.setStatus(ctx.runId, "failed");
+      {
+        const t = await m.emitTurn();
+        if (t) yield t;
+      }
+      yield await m.emit(ev("swarm.run_failed", base(ctx, m.nextTs()), { stage: outcome.stage, message: outcome.message, retryable: true }));
+      return "failed";
+    }
+    await this.mirrorDelegations(ctx);
+    await this.attributeRun(ctx);
+    await this.opts.storage.runs.setStatus(ctx.runId, "done");
+    {
+      const t = await m.emitTurn();
+      if (t) yield t;
+    }
+    yield await m.emit(ev("swarm.status", base(ctx, m.nextTs()), { state: "done" }));
+    return "done";
+  }
+  /** 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. */
+  async *streamWorkflowAgentStep(slug, message, genIndex, ctx, input, m) {
+    await this.guardGeneration({ runId: ctx.runId, tenantId: ctx.tenantId, agentSlug: slug, modelId: m.modelIdFor(slug), generationIndex: genIndex, kind: "run" });
+    const sctx = { ...ctx, agentSlug: slug };
+    const stepRc = this.requestContext(sctx, m.state);
+    if (this.opts.pageContext) attachPageContext(stepRc, input.context);
+    const result = await this.agent().stream(message, { runId: ctx.runId, requestContext: stepRc, ...this.memoryOpts(sctx) });
+    let text = "";
+    for await (const part of result.fullStream) {
+      if (part?.type === "step-finish") m.gov.step();
+      for (const e of mapChunk(part, sctx, m.gov, m.modelIdFor, m.nextTs, m.streamed, m.delegateBudgets, m.activity, m.gatesApproval, m.turnUsage, m.segmentIndex)) {
+        if (e.type === "swarm.message") text += e.data.delta ?? e.data.text ?? "";
+        yield e;
+      }
+    }
+    return { text };
+  }
+  /** A workflow `tool` step: run the gate-free tool body through `executeToolWithGate` (the engine-owned gate). */
+  async runWorkflowToolStep(toolName, args, ctx, state) {
+    const skill = this.opts.resolveSkill?.(toolName);
+    const exec = skill ? getToolExecutor(skill) : void 0;
+    if (!skill || !exec) return { ok: false, error: `unknown tool "${toolName}"` };
+    const toolCtx = { tenantId: ctx.tenantId, userId: ctx.userId, runId: ctx.runId, secrets: bindSecrets(this.opts.secrets, ctx), state };
+    return executeToolWithGate({
+      ev: toolPreCallEvent({ runId: ctx.runId, tenantId: ctx.tenantId, agentSlug: ctx.agentSlug, toolName, origin: skill.origin ?? "first-party", needsApproval: this.gatesApproval(toolName), args }),
+      gate: this.toolGate,
+      run: () => exec(args, toolCtx)
+    });
+  }
   async *resume(args, ctx) {
     const snap = await this.opts.storage.runs.loadSnapshot(ctx.tenantId, args.runId);
     if (!snap) throw new Error(`no suspended run: ${args.runId}`);
+    const resumedState = createRunState(snap.state ?? void 0);
+    const generationIndex = typeof snap.genIndex === "number" ? snap.genIndex : 1;
+    const capHit = snap.capHit;
     await this.opts.storage.markFollowupAnswered?.(args.followupId, ctx.tenantId);
     await this.opts.storage.runs.setStatus(args.runId, "running");
-    const modelId = (await this.loadRow(ctx.tenantId, ctx.agentSlug)).modelId ?? "unknown";
-    const modelIdFor = (slug) => this.rowCache.peek(`${ctx.tenantId}:${slug}`)?.modelId ?? modelId;
+    const modelId = this.priceModelId((await this.loadRow(ctx.tenantId, ctx.agentSlug)).modelId ?? "unknown", ctx.tenantId, ctx.agentSlug);
+    const modelIdFor = (slug) => {
+      const raw = this.rowCache.peek(`${ctx.tenantId}:${slug}`)?.modelId;
+      return raw ? this.priceModelId(raw, ctx.tenantId, slug) : modelId;
+    };
+    const gatesApproval = (name) => this.gatesApproval(name);
     const gov = new CostGovernor(this.opts.cost);
-    const delegateBudgets = this.opts.cost.perDelegate ? new DelegateBudgets(this.opts.cost.perDelegate, ctx.agentSlug) : null;
+    const delegateBudgets = this.opts.cost.perDelegate ? new DelegateBudgets(this.opts.cost.perDelegate, ctx.agentSlug, this.pricingOpts()) : null;
     const streamed = /* @__PURE__ */ new Set();
+    const activity = /* @__PURE__ */ new Map();
+    const turnUsage = [];
     const collector = this.opts.telemetry ? new SpanCollector(args.runId, () => Date.now(), "resume", { agentSlug: ctx.agentSlug }) : null;
     let ts = 1e3;
     const emit = async (e) => {
       e.seq = await this.opts.storage.events.append(e);
+      await this.notifyEvent(e, ctx);
       return e;
     };
+    let turnEmitted = false;
     const floorKey = ctx.threadId;
     const me = { label: titleCase(ctx.agentSlug), runId: args.runId };
     const floorAbort = new AbortController();
     let releaseFloor = await this.floor.tryAcquire(floorKey, me);
     const rctx = { ...ctx, runId: args.runId };
+    const emitTurn = async () => {
+      if (turnEmitted) return null;
+      turnEmitted = true;
+      return emit(turnUsageEvent(rctx, ts++, turnUsage, generationIndex));
+    };
+    let resumeOutcome = "failed";
     try {
       if (!releaseFloor) {
         const held = await this.floor.holder(floorKey);
@@ -1066,84 +1904,285 @@ var SwarmEngine = class {
           answer: args.answer
         })
       );
-      const rc = this.requestContext({ ...ctx, runId: args.runId });
-      if (this.opts.pageContext) attachPageContext(rc, args.context);
-      const result = await this.agent().resumeStream(
-        { answer: args.answer },
-        { runId: args.runId, toolCallId: args.toolCallId, requestContext: rc, ...this.memoryOpts({ ...ctx, runId: args.runId }) }
-      );
-      for await (const part of result.fullStream) {
-        if (part?.type === "step-finish") gov.step();
-        if (part?.type === "tool-call-suspended") {
-          const payload = part.payload ?? {};
-          const toolCallId = payload.toolCallId ?? "";
-          const followupId = `${args.runId}:${toolCallId}`;
-          const sp = payload.suspendPayload ?? {};
-          await recordSuspend(this.opts.storage, rctx, followupId, toolCallId);
-          await this.opts.storage.runs.setStatus(args.runId, "suspended");
-          await this.opts.storage.runs.saveSnapshot(args.runId, { pending: { toolCallId } });
-          yield await emit(ev("swarm.status", base(rctx, ts++), { state: "waiting" }));
-          yield await emit(
-            ev("swarm.question", base(rctx, ts++), {
-              followupId,
-              toolCallId,
-              to: sp.to ?? "user",
-              from: sp.asker || rctx.agentSlug,
-              prompt: sp.prompt ?? "",
-              field: sp.field
-            })
-          );
-          return;
-        }
-        if (part?.type === "error") {
+      const wfState = snap.workflow;
+      if (wfState) {
+        const wf = this.opts.workflows?.find((w) => w.name === wfState.workflow) ?? this.opts.agentWorkflows?.[ctx.agentSlug];
+        if (!wf) {
           await this.opts.storage.runs.setStatus(args.runId, "failed");
-          yield await emit(
-            ev("swarm.run_failed", base(rctx, ts++), {
-              stage: "stream",
-              message: streamErrorMessage(part),
-              retryable: false
-            })
-          );
+          {
+            const t = await emitTurn();
+            if (t) yield t;
+          }
+          yield await emit(ev("swarm.run_failed", base(rctx, ts++), { stage: "workflow", message: `unknown workflow: ${wfState.workflow}`, retryable: false }));
           return;
         }
-        collectSpans(collector, part, modelId, gov);
-        for (const e of mapChunk(part, rctx, gov, modelIdFor, () => ts++, streamed, delegateBudgets)) yield await emit(e);
-        const overDelegate = delegateBudgets?.exceeded();
-        if (gov.shouldStop().stop || overDelegate) {
-          await this.opts.storage.runs.setStatus(args.runId, "failed");
-          yield await emit(
-            ev("swarm.run_failed", base(rctx, ts++), {
-              stage: "cost",
-              message: overDelegate?.reason ?? gov.shouldStop().reason,
-              retryable: false
-            })
-          );
-          return;
+        if (wfState.pending) {
+          wfState.outputs[wfState.pending.stepId] = args.answer;
+          wfState.pending = void 0;
+        }
+        resumeOutcome = yield* this.driveWorkflow(wf, wfState, rctx, { message: "", context: args.context }, {
+          gov,
+          modelIdFor,
+          streamed,
+          delegateBudgets,
+          activity,
+          gatesApproval,
+          turnUsage,
+          nextTs: () => ts++,
+          emit,
+          emitTurn,
+          segmentIndex: generationIndex,
+          // FR-004: a resume segment starts at the snapshot's genIndex
+          state: resumedState
+          // FR-003: workflow steps' tools see the restored ctx.state
+        });
+        return;
+      }
+      if (capHit && !isApproved(args.answer)) {
+        await this.opts.storage.runs.setStatus(args.runId, "failed");
+        {
+          const t = await emitTurn();
+          if (t) yield t;
         }
+        yield await emit(
+          ev("swarm.run_failed", base(rctx, ts++), {
+            stage: "cost",
+            message: "budget cap reached \u2014 continuation declined by the user",
+            retryable: false
+          })
+        );
+        return;
+      }
+      const rc = this.requestContext({ ...ctx, runId: args.runId }, resumedState);
+      if (this.opts.pageContext) attachPageContext(rc, args.context);
+      await this.guardGeneration({ runId: args.runId, tenantId: ctx.tenantId, agentSlug: ctx.agentSlug, modelId, generationIndex, kind: "resume" });
+      let resumeNudges = 0;
+      let firstPass = true;
+      const request = await this.recallRequest(rctx);
+      let nudgeMessage = CONTINUE_NUDGE;
+      let transcript = "";
+      let incompleteVerdict = null;
+      for (; ; ) {
+        const result = firstPass ? capHit ? await (async () => {
+          gov.raiseCostCap(this.opts.cost.capIncrementUsd ?? this.opts.cost.maxCostUsd);
+          return this.agent().stream(capHit.message, { runId: args.runId, requestContext: rc, ...this.memoryOpts({ ...ctx, runId: args.runId }) });
+        })() : await this.agent().resumeStream(
+          { answer: args.answer },
+          { runId: args.runId, toolCallId: args.toolCallId, requestContext: rc, ...this.memoryOpts({ ...ctx, runId: args.runId }) }
+        ) : await this.agent().stream(nudgeMessage, { runId: args.runId, requestContext: rc, ...this.memoryOpts({ ...ctx, runId: args.runId }) });
+        firstPass = false;
+        let sawStep = false;
+        let lastOutputSlug;
+        for await (const part of result.fullStream) {
+          if (part?.type === "step-finish") {
+            gov.step();
+            sawStep = true;
+          }
+          if (part?.type === "tool-call-suspended") {
+            const payload = part.payload ?? {};
+            const toolCallId = payload.toolCallId ?? "";
+            const followupId = `${args.runId}:${toolCallId}`;
+            const sp = payload.suspendPayload ?? {};
+            await recordSuspend(this.opts.storage, rctx, followupId, toolCallId);
+            await this.opts.storage.runs.setStatus(args.runId, "suspended");
+            await this.opts.storage.runs.saveSnapshot(args.runId, { pending: { toolCallId }, genIndex: generationIndex + 1, state: resumedState.entries() });
+            {
+              const t = await emitTurn();
+              if (t) yield t;
+            }
+            yield await emit(ev("swarm.status", base(rctx, ts++), { state: "waiting" }));
+            yield await emit(clientActionOrQuestion(rctx, ts++, followupId, toolCallId, sp));
+            resumeOutcome = "suspended";
+            return;
+          }
+          if (part?.type === "error") {
+            await this.opts.storage.runs.setStatus(args.runId, "failed");
+            {
+              const t = await emitTurn();
+              if (t) yield t;
+            }
+            yield await emit(
+              ev("swarm.run_failed", base(rctx, ts++), {
+                stage: "stream",
+                message: streamErrorMessage(part),
+                retryable: false
+              })
+            );
+            return;
+          }
+          collectSpans(collector, part, modelId, gov);
+          for (const e of mapChunk(part, rctx, gov, modelIdFor, () => ts++, streamed, delegateBudgets, activity, gatesApproval, turnUsage, generationIndex)) {
+            if (e.type === "swarm.message" || e.type === "swarm.tool_call") {
+              lastOutputSlug = e.agentSlug;
+              if (this.opts.verifyCompletion) transcript = appendTranscript(transcript, e);
+            }
+            yield await emit(e);
+          }
+          const overDelegate = delegateBudgets?.exceeded();
+          const stop = gov.shouldStop();
+          if (stop.stop || overDelegate) {
+            if (this.opts.cost.onCapHit === "ask" && stop.stop && !overDelegate && capHit) {
+              const followupId = `${args.runId}:${CAP_FOLLOWUP_SUFFIX}`;
+              await recordSuspend(this.opts.storage, rctx, followupId, CAP_FOLLOWUP_SUFFIX);
+              await this.opts.storage.runs.setStatus(args.runId, "suspended");
+              await this.opts.storage.runs.saveSnapshot(args.runId, {
+                capHit: { message: capHit.message, spentUsd: gov.costUsd() },
+                genIndex: generationIndex + 1,
+                state: resumedState.entries()
+                // FR-003: persist per-run state across the cap-ask boundary
+              });
+              {
+                const t = await emitTurn();
+                if (t) yield t;
+              }
+              yield await emit(ev("swarm.status", base(rctx, ts++), { state: "waiting" }));
+              yield await emit(ev("swarm.question", base(rctx, ts++), capQuestion(rctx, followupId, gov)));
+              resumeOutcome = "suspended";
+              return;
+            }
+            await this.opts.storage.runs.setStatus(args.runId, "failed");
+            {
+              const t = await emitTurn();
+              if (t) yield t;
+            }
+            yield await emit(
+              ev("swarm.run_failed", base(rctx, ts++), {
+                stage: "cost",
+                message: overDelegate?.reason ?? stop.reason,
+                retryable: false
+              })
+            );
+            return;
+          }
+        }
+        if (this.opts.verifyCompletion) {
+          const verdict = await this.safeVerify(request, transcript, rctx);
+          if (!verdict.complete && resumeNudges < MAX_CONTINUE_NUDGES) {
+            resumeNudges++;
+            nudgeMessage = verifyNudge(verdict.missing);
+            continue;
+          }
+          incompleteVerdict = verdict.complete ? null : verdict;
+        } else if (sawStep && lastOutputSlug !== rctx.agentSlug && resumeNudges < MAX_CONTINUE_NUDGES) {
+          resumeNudges++;
+          continue;
+        }
+        break;
       }
       await this.attributeRun(rctx);
-      await this.opts.storage.runs.setStatus(args.runId, "done");
-      yield await emit(ev("swarm.status", base(rctx, ts++), { state: "done" }));
+      if (incompleteVerdict) {
+        await this.opts.storage.runs.setStatus(args.runId, "failed");
+        {
+          const t = await emitTurn();
+          if (t) yield t;
+        }
+        yield await emit(ev("swarm.run_failed", base(rctx, ts++), { stage: "incomplete", message: incompleteVerdict.missing ?? "The task was not completed.", retryable: true }));
+      } else {
+        await this.opts.storage.runs.setStatus(args.runId, "done");
+        {
+          const t = await emitTurn();
+          if (t) yield t;
+        }
+        yield await emit(ev("swarm.status", base(rctx, ts++), { state: "done" }));
+        resumeOutcome = "done";
+      }
     } catch (err) {
-      console.error(`[nightowls] resume ${args.runId} threw:`, err);
+      const stage = err instanceof ReserveDenied ? "reserve" : "exception";
+      if (stage !== "reserve") console.error(`[@nightowlsdev/core] resume ${args.runId} threw:`, err);
       try {
         await this.opts.storage.runs.setStatus(args.runId, "failed");
       } catch {
       }
-      yield await emit(ev("swarm.run_failed", base(rctx, ts++), { stage: "exception", message: errMessage(err), retryable: false }));
+      {
+        const t = await emitTurn();
+        if (t) yield t;
+      }
+      yield await emit(ev("swarm.run_failed", base(rctx, ts++), { stage, message: errMessage(err), retryable: false }));
     } finally {
+      if (this.opts.onRunEnd) {
+        try {
+          await this.opts.onRunEnd(ctx, { state: resumedState, outcome: resumeOutcome });
+        } catch (err) {
+          console.error(`[@nightowlsdev/core] onRunEnd threw for resume ${args.runId}:`, err);
+        }
+      }
       floorAbort.abort();
       await releaseFloor?.();
       await exportSpans(this.opts.telemetry, collector);
     }
   }
 };
+var ReserveDenied = class extends Error {
+  stage = "reserve";
+  constructor(reason) {
+    super(reason);
+    this.name = "ReserveDenied";
+  }
+};
 function errMessage(err) {
   return err instanceof Error ? err.message : String(err);
 }
 function base(ctx, ts) {
   return { runId: ctx.runId, agentSlug: ctx.agentSlug, ts };
 }
+function clientActionOrQuestion(ctx, ts, followupId, toolCallId, sp) {
+  if (sp.clientAction) {
+    return ev("swarm.client_action", base(ctx, ts), {
+      followupId,
+      toolCallId,
+      tool: sp.clientAction.tool,
+      input: sp.clientAction.input,
+      needsApproval: sp.clientAction.needsApproval ?? false,
+      from: sp.asker || ctx.agentSlug
+    });
+  }
+  return ev("swarm.question", base(ctx, ts), {
+    followupId,
+    toolCallId,
+    to: sp.to ?? "user",
+    from: sp.asker || ctx.agentSlug,
+    prompt: sp.prompt ?? "",
+    field: sp.field
+  });
+}
+var CAP_FOLLOWUP_SUFFIX = "cap";
+function capQuestion(ctx, followupId, gov) {
+  const spent = gov.costUsd();
+  const cap = gov.maxCostUsd;
+  return {
+    followupId,
+    toolCallId: CAP_FOLLOWUP_SUFFIX,
+    to: "user",
+    from: ctx.agentSlug,
+    prompt: `Budget cap reached \u2014 continue? This run has spent **$${spent.toFixed(2)}** of its $${cap.toFixed(2)} budget. Approve to grant more budget and keep going, or decline to stop the run here.`,
+    field: {
+      kind: "confirm",
+      confirmLabel: "Continue",
+      rejectLabel: "Stop"
+    }
+  };
+}
+function turnUsageEvent(ctx, ts, turnUsage, segmentIndex) {
+  const total = sumTurnUsage(turnUsage);
+  return ev("swarm.turn_usage", base(ctx, ts), {
+    breakdown: total.breakdown,
+    cost: total.cost,
+    bySlug: total.bySlug,
+    generations: turnUsage.length,
+    segmentIndex
+  });
+}
+function extractUsage(usage) {
+  const u = usage ?? {};
+  const cacheRead = u.cachedInputTokens ?? u.inputTokenDetails?.cacheReadTokens ?? u.raw?.inputTokenDetails?.cacheReadTokens;
+  const cacheWrite = u.inputTokenDetails?.cacheWriteTokens ?? u.raw?.inputTokenDetails?.cacheWriteTokens;
+  const reasoning = u.reasoningTokens ?? u.outputTokenDetails?.reasoningTokens ?? u.raw?.outputTokenDetails?.reasoningTokens;
+  const b = { inputTokens: u.inputTokens ?? 0, outputTokens: u.outputTokens ?? 0 };
+  if (cacheRead != null) b.cacheReadTokens = cacheRead;
+  if (cacheWrite != null) b.cacheWriteTokens = cacheWrite;
+  if (reasoning != null) b.reasoningTokens = reasoning;
+  return b;
+}
 function titleCase(slug) {
   return slug.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
 }
@@ -1175,8 +2214,7 @@ function collectSpans(collector, part, modelId, gov) {
       break;
     case "step-finish": {
       const output = p.output;
-      const usage = output?.usage;
-      const u = { inputTokens: usage?.inputTokens ?? 0, outputTokens: usage?.outputTokens ?? 0 };
+      const u = extractUsage(output?.usage);
       collector.openGeneration(modelId);
       collector.closeGeneration(u, gov.priceOf(modelId, u));
       break;
@@ -1197,14 +2235,19 @@ async function recordSuspend(storage, ctx, followupId, toolCallId) {
   if (!storage.recordSuspend && !warnedNoRecordSuspend) {
     warnedNoRecordSuspend = true;
     console.warn(
-      "[nightowls] storage adapter does not implement recordSuspend() \u2014 human-in-the-loop resume will be forbidden (the followup index is never written). Implement recordSuspend on your StorageAdapter."
+      "[@nightowlsdev/core] storage adapter does not implement recordSuspend() \u2014 human-in-the-loop resume will be forbidden (the followup index is never written). Implement recordSuspend on your StorageAdapter."
     );
   }
   await storage.recordSuspend?.(ctx.runId, ctx.tenantId, followupId, toolCallId);
 }
-function mapChunk(part, ctx, gov, modelIdFor, nextTs, streamed, delegateBudgets) {
+function mapChunk(part, ctx, gov, modelIdFor, nextTs, streamed, delegateBudgets, activity, gatesApproval, turnUsage, segmentIndex) {
   const p = part.payload ?? {};
   const modelId = modelIdFor(ctx.agentSlug);
+  const act = (slug) => {
+    let a = activity.get(slug);
+    if (!a) activity.set(slug, a = { toolCalls: 0, agentActivations: 0 });
+    return a;
+  };
   switch (part.type) {
     case "text-delta":
       return [ev("swarm.message", base(ctx, nextTs()), { role: "assistant", delta: p.text ?? "" })];
@@ -1214,17 +2257,21 @@ function mapChunk(part, ctx, gov, modelIdFor, nextTs, streamed, delegateBudgets)
         const to = name.slice("agent-".length);
         const a = typeof p.args === "string" ? safeParse(p.args) : p.args;
         const task = a?.prompt ?? "";
+        act(ctx.agentSlug).agentActivations++;
         return [
           ev("swarm.handoff", base(ctx, nextTs()), { from: ctx.agentSlug, to, task }),
           ev("swarm.status", base(ctx, nextTs()), { state: "delegating", note: to })
         ];
       }
+      act(ctx.agentSlug).toolCalls++;
       return [
         ev("swarm.tool_call", base(ctx, nextTs()), {
           toolCallId: p.toolCallId,
           name,
           args: p.args,
-          needsApproval: false
+          // SP5 truth-fix: emit the RESOLVED needsApproval (policy + the tool's flag), not a hardcoded false, so
+          // the UI reflects reality — a tool that will suspend-for-approval is shown as needing approval.
+          needsApproval: gatesApproval(name)
         })
       ];
     }
@@ -1253,9 +2300,19 @@ function mapChunk(part, ctx, gov, modelIdFor, nextTs, streamed, delegateBudgets)
       const output = p.output;
       const usage = output?.usage;
       if (usage) {
-        const u = { inputTokens: usage.inputTokens ?? 0, outputTokens: usage.outputTokens ?? 0 };
+        const counters = activity.get(ctx.agentSlug);
+        const u = extractUsage(usage);
+        if (counters && (counters.toolCalls || counters.agentActivations)) {
+          u.toolCalls = counters.toolCalls;
+          u.agentActivations = counters.agentActivations;
+        }
+        activity.delete(ctx.agentSlug);
         gov.addUsage(modelId, u);
         delegateBudgets?.addUsage(ctx.agentSlug, modelId, u);
+        const cost = gov.costOf(modelId, u);
+        const generationId = `${ctx.runId}:${segmentIndex}:${turnUsage.length}`;
+        turnUsage.push({ slug: ctx.agentSlug, breakdown: u, cost });
+        return [ev("swarm.usage", base(ctx, nextTs()), { slug: ctx.agentSlug, modelId, breakdown: u, cost, generationId })];
       }
       return [];
     }
@@ -1266,7 +2323,7 @@ function mapChunk(part, ctx, gov, modelIdFor, nextTs, streamed, delegateBudgets)
       const inner = p.output;
       if (!inner || typeof inner.type !== "string") return [];
       if (inner.type === "text-delta") streamed.add(p.toolCallId);
-      return mapChunk(inner, { ...ctx, agentSlug: subSlug }, gov, modelIdFor, nextTs, streamed, delegateBudgets);
+      return mapChunk(inner, { ...ctx, agentSlug: subSlug }, gov, modelIdFor, nextTs, streamed, delegateBudgets, activity, gatesApproval, turnUsage, segmentIndex);
     }
     case "tool-error": {
       const name = p.toolName ?? "";
@@ -1295,8 +2352,121 @@ function allowListModelProvider(opts) {
   };
 }
 
+// src/rules.ts
+var import_hooks2 = require("@nightowlsdev/hooks");
+var GLOB_CACHE = /* @__PURE__ */ new Map();
+function globRegex(pattern) {
+  let re = GLOB_CACHE.get(pattern);
+  if (!re) {
+    re = new RegExp("^" + pattern.replace(/[.*+?^${}()|[\]\\]/g, (c) => c === "*" ? ".*" : "\\" + c) + "$");
+    GLOB_CACHE.set(pattern, re);
+  }
+  return re;
+}
+function globMatch(pattern, value) {
+  if (pattern === value) return true;
+  if (!pattern.includes("*")) return false;
+  return globRegex(pattern).test(value);
+}
+function matchField(field, value) {
+  if (field === void 0) return true;
+  const arr = Array.isArray(field) ? field : [field];
+  return arr.some((p) => globMatch(p, value));
+}
+function ruleMatchesTool(rule, ev2) {
+  if (rule.seam !== "tool") return false;
+  if (rule.scopeAgent !== void 0 && rule.scopeAgent !== ev2.agentSlug) return false;
+  const w = rule.when;
+  if (!matchField(w.agent, ev2.agentSlug)) return false;
+  if (!matchField(w.tool, ev2.toolName)) return false;
+  if (w.origin !== void 0 && w.origin !== ev2.origin) return false;
+  return true;
+}
+function ruleMatchesGeneration(rule, ev2) {
+  if (rule.seam !== "generation") return false;
+  if (rule.scopeAgent !== void 0 && rule.scopeAgent !== ev2.agentSlug) return false;
+  const w = rule.when;
+  if (!matchField(w.agent, ev2.agentSlug)) return false;
+  if (!matchField(w.model, ev2.modelId)) return false;
+  return true;
+}
+var TOOL_RANK = { deny: 2, ask: 1, allow: 0 };
+function mostRestrictiveTool(a, b) {
+  return TOOL_RANK[b.action] > TOOL_RANK[a.action] ? b : a;
+}
+function errMessage2(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function composeToolHooks(opts) {
+  const rules = opts.rules.filter((r) => r.seam === "tool" && r.level === "enforce");
+  return async (ev2) => {
+    let decision = (0, import_hooks2.toolPolicyDecision)(ev2, opts.policy);
+    if (opts.host) {
+      try {
+        decision = mostRestrictiveTool(decision, await opts.host(ev2));
+      } catch (err) {
+        return (0, import_hooks2.deny)(`preToolCall hook threw: ${errMessage2(err)}`);
+      }
+    }
+    if (decision.action === "deny") return decision;
+    for (const r of rules) {
+      if (!ruleMatchesTool(r, ev2)) continue;
+      const rd = r.action.do === "deny" ? (0, import_hooks2.deny)(r.action.reason ?? r.statement) : (0, import_hooks2.ask)(r.action.reason ?? r.statement);
+      decision = mostRestrictiveTool(decision, rd);
+      if (decision.action === "deny") return decision;
+    }
+    return decision;
+  };
+}
+function composeGenerationHooks(opts) {
+  const rules = opts.rules.filter((r) => r.seam === "generation" && r.level === "enforce");
+  if (!rules.length && !opts.host) return void 0;
+  return async (ev2) => {
+    if (opts.host) {
+      try {
+        const d = await opts.host(ev2);
+        if (d.action === "deny") return d;
+      } catch (err) {
+        return (0, import_hooks2.deny)(`preGeneration hook threw: ${errMessage2(err)}`);
+      }
+    }
+    for (const r of rules) {
+      if (ruleMatchesGeneration(r, ev2)) return (0, import_hooks2.deny)(r.action?.reason ?? r.statement);
+    }
+    return { action: "allow" };
+  };
+}
+function softPolicyFor(slug, rules, workflows) {
+  const out = [];
+  for (const r of rules) {
+    if (r.level !== "advise") continue;
+    if (r.scopeAgent !== void 0 && r.scopeAgent !== slug) continue;
+    if (!matchField(r.when.agent, slug)) continue;
+    out.push(r.statement);
+  }
+  for (const w of workflows) {
+    if (w.compliance !== "advisory" || !w.description) continue;
+    if (w.scopeAgent !== void 0 && w.scopeAgent !== slug) continue;
+    out.push(`Suggested procedure "${w.name}": ${w.description}`);
+  }
+  return out;
+}
+
 // src/define.ts
 var MASTRA = /* @__PURE__ */ new WeakMap();
+var APPROVAL_SUSPEND_SCHEMA = import_zod4.z.object({
+  to: import_zod4.z.string(),
+  prompt: import_zod4.z.string(),
+  field: import_zod4.z.object({
+    kind: import_zod4.z.enum(["confirm", "buttons", "select", "multiselect", "number", "text", "textarea"]),
+    confirmLabel: import_zod4.z.string().optional(),
+    rejectLabel: import_zod4.z.string().optional()
+  }).optional(),
+  asker: import_zod4.z.string().optional(),
+  kind: import_zod4.z.literal("approval").optional(),
+  toolName: import_zod4.z.string().optional()
+});
+var APPROVAL_RESUME_SCHEMA = import_zod4.z.object({ answer: import_zod4.z.any() });
 function defineTool(spec) {
   const origin = spec.origin ?? "first-party";
   const needsApproval = spec.needsApproval ?? origin === "mcp";
@@ -1305,26 +2475,135 @@ function defineTool(spec) {
     description: spec.description ?? spec.name,
     inputSchema: spec.inputSchema,
     outputSchema: spec.outputSchema,
+    // SP5: declare suspend/resume schemas so the action-approval gate can suspend-and-ask via
+    // context.agent.suspend (Mastra gates `suspend` on a declared suspendSchema — same as the built-in `ask`).
+    // The suspend payload is `ask`-shaped (+ approval metadata) so the engine emits the existing `swarm.question`;
+    // resume carries the human's `{ answer }` (a confirm → boolean approve/reject).
+    suspendSchema: APPROVAL_SUSPEND_SCHEMA,
+    resumeSchema: APPROVAL_RESUME_SCHEMA,
     // Mastra 1.38 (per SPIKE-FINDINGS item 3): execute is `(inputData, context) => out`
     // with TWO positional args. `inputData` is the parsed input; tenant/user/run come
-    // off `context.requestContext`.
+    // off `context.requestContext`. `context.agent` (when an agent drives the call) carries the
+    // suspend/resumeData handles SP5's action-approval gate uses to suspend-and-ask the human.
+    //
+    // SP5 — the mandatory action-approval HITL gate (the enforcement POINT). Before the side effect runs we
+    // resolve the effective ToolDecision via the per-run `ToolGate` the engine injected on the RequestContext
+    // (policy + the resolved needsApproval + the preToolCall hook):
+    //   • allow → execute as today.
+    //   • deny  → return a blocked tool-result; the side effect NEVER runs.
+    //   • ask   → SUSPEND via context.agent.suspend(...) with an `ask`-SHAPED payload, so the engine's existing
+    //             `tool-call-suspended` handler emits the SAME `swarm.question`; on resume the tool re-executes
+    //             with context.agent.resumeData = { answer } → approve runs the side effect, reject blocks it.
+    // We reuse the EXISTING suspend/resume + question/answer machinery — no parallel one.
     execute: async (inputData, context) => {
       const rc = context?.requestContext;
+      const tenantId = rc?.get?.("tenantId") ?? "default";
+      const userId = rc?.get?.("userId") ?? "";
+      const runId = rc?.get?.("runId") ?? "";
+      const resolver = rc?.get?.(SECRET_RESOLVER_KEY);
+      const scopedCtx = {
+        tenantId,
+        userId,
+        runId,
+        agentSlug: rc?.get?.("agentSlug") ?? "",
+        threadId: rc?.get?.("threadId") ?? "",
+        ...(() => {
+          const v = rc?.get?.("agentVersion");
+          return typeof v === "number" ? { agentVersion: v } : {};
+        })()
+      };
       const ctx = {
-        tenantId: rc?.get?.("tenantId") ?? "default",
-        userId: rc?.get?.("userId") ?? "",
-        runId: rc?.get?.("runId") ?? ""
+        tenantId,
+        userId,
+        runId,
+        secrets: bindSecrets(resolver, scopedCtx),
+        // FR-003: the per-run state handle the engine put on the rc (same object across the run's tool calls +
+        // delegated sub-agents). Absent on a raw test stream built without the engine — then `ctx.state` is
+        // undefined, unchanged from prior behaviour.
+        state: rc?.get?.(RUN_STATE_KEY)
       };
-      return spec.execute(inputData, ctx);
+      const run = () => spec.execute(inputData, ctx);
+      const agentCtx = context?.agent;
+      if (agentCtx?.resumeData !== void 0 && agentCtx.resumeData !== null) {
+        const answer = agentCtx.resumeData.answer;
+        if (isApproved(answer)) return run();
+        throw new ToolBlockedError(spec.name, "rejected by approver");
+      }
+      const gate = rc?.get?.(TOOL_GATE_KEY);
+      if (!gate || typeof agentCtx?.suspend !== "function") return run();
+      const agentSlug = deriveAsker(agentCtx, rc);
+      const decision = await gate(
+        toolPreCallEvent({
+          runId: ctx.runId,
+          tenantId: ctx.tenantId,
+          agentSlug,
+          toolName: spec.name,
+          origin,
+          needsApproval,
+          args: inputData
+        })
+      );
+      if (decision.action === "allow") return run();
+      if (decision.action === "deny") throw new ToolBlockedError(spec.name, decision.reason);
+      await agentCtx.suspend(approvalSuspendPayload({ toolName: spec.name, asker: agentSlug, reason: decision.reason }));
+      throw new ToolBlockedError(spec.name, "awaiting approval");
     }
   });
   const handle = { name: spec.name, needsApproval, origin };
   MASTRA.set(handle, mastraTool);
+  setToolExecutor(handle, (args, c) => spec.execute(args, c));
   return handle;
 }
 function defineSkill(tool) {
   return tool;
 }
+function deriveAsker(agentCtx, rc) {
+  const agentId = agentCtx?.agentId ?? "";
+  if (agentId.startsWith("swarm-sub-")) return agentId.slice("swarm-sub-".length);
+  return rc?.get?.("agentSlug") ?? "";
+}
+var CLIENT_ACTION_SUSPEND_SCHEMA = import_zod4.z.object({
+  clientAction: import_zod4.z.object({ tool: import_zod4.z.string(), input: import_zod4.z.any(), needsApproval: import_zod4.z.boolean().optional() }),
+  asker: import_zod4.z.string().optional()
+});
+var CLIENT_ACTION_RESUME_SCHEMA = import_zod4.z.object({ answer: import_zod4.z.any() });
+var ClientToolError = class extends Error {
+  constructor(toolName, reason) {
+    super(reason ? `client tool ${toolName} failed: ${reason}` : `client tool ${toolName} failed`);
+    this.name = "ClientToolError";
+  }
+};
+function defineClientTool(spec) {
+  const needsApproval = spec.needsApproval ?? false;
+  const mastraTool = (0, import_tools4.createTool)({
+    id: spec.name,
+    description: spec.description ?? spec.name,
+    inputSchema: spec.inputSchema,
+    outputSchema: spec.outputSchema,
+    suspendSchema: CLIENT_ACTION_SUSPEND_SCHEMA,
+    resumeSchema: CLIENT_ACTION_RESUME_SCHEMA,
+    execute: async (inputData, context) => {
+      const rc = context?.requestContext;
+      const agentCtx = context?.agent;
+      if (agentCtx?.resumeData !== void 0 && agentCtx.resumeData !== null) {
+        const answer = agentCtx.resumeData.answer;
+        if (answer && typeof answer === "object" && "error" in answer && answer.error) {
+          throw new ClientToolError(spec.name, String(answer.error));
+        }
+        return answer && typeof answer === "object" && "output" in answer ? answer.output : answer;
+      }
+      if (typeof agentCtx?.suspend !== "function") {
+        throw new ClientToolError(spec.name, "client tools require an agent-driven run (no server execute)");
+      }
+      const asker = deriveAsker(agentCtx, rc);
+      await agentCtx.suspend({ clientAction: { tool: spec.name, input: inputData, needsApproval }, asker });
+      throw new ClientToolError(spec.name, "awaiting client action");
+    }
+  });
+  const handle = { name: spec.name, needsApproval, origin: "first-party" };
+  MASTRA.set(handle, mastraTool);
+  return handle;
+}
 function __getMastraTool(t) {
   return MASTRA.get(t);
 }
@@ -1335,6 +2614,10 @@ function defineAgent(spec) {
     // The concrete skill handles ride along on the def so defineSwarm can build
     // a per-swarm resolver. No module-level registry → no cross-swarm leakage.
     skills,
+    // Per-agent policy rides on the def (engine-local), stamped with this agent's scope so defineSwarm can
+    // collect + apply it without persisting to the versioned AgentVersion row (D3).
+    ...spec.rules ? { rules: spec.rules.map((r) => ({ ...r, scopeAgent: spec.slug })) } : {},
+    ...spec.workflow ? { workflow: { ...spec.workflow, scopeAgent: spec.slug } } : {},
     head: {
       slug: spec.slug,
       version: 1,
@@ -1348,11 +2631,217 @@ function defineAgent(spec) {
     }
   };
 }
+function defineRule(spec) {
+  if (!spec.id) throw new Error("defineRule: `id` is required");
+  if (!spec.statement) throw new Error(`defineRule(${spec.id}): \`statement\` is required`);
+  const tools = spec.when.tool === void 0 ? [] : Array.isArray(spec.when.tool) ? spec.when.tool : [spec.when.tool];
+  const seam = spec.on ?? (spec.when.model !== void 0 ? "generation" : "tool");
+  if (spec.level === "enforce") {
+    if (!spec.action) throw new Error(`defineRule(${spec.id}): enforce rules require an \`action\``);
+    if (!spec.on && spec.when.tool === void 0 && spec.when.model === void 0) {
+      throw new Error(`defineRule(${spec.id}): an enforce rule with an empty \`when\` must set \`on\` ("tool" | "generation")`);
+    }
+    if (spec.action.do === "ask") {
+      if (seam !== "tool") throw new Error(`defineRule(${spec.id}): \`ask\` is tool-seam only (preGeneration cannot suspend)`);
+      if (tools.some((t) => t.startsWith("agent-"))) {
+        throw new Error(`defineRule(${spec.id}): \`ask\` cannot target a delegation (\`agent-*\`) \u2014 gateDelegation defers \`ask\`; use \`deny\``);
+      }
+    }
+  }
+  return { id: spec.id, statement: spec.statement, when: spec.when, level: spec.level, action: spec.action, seam };
+}
+function workflowRefTargets(step) {
+  const out = [];
+  const scan = (o) => {
+    for (const v of Object.values(o ?? {})) {
+      if (v && typeof v === "object" && "$ref" in v) out.push(String(v.$ref));
+    }
+  };
+  scan(step.args);
+  scan(step.input);
+  if (Array.isArray(step.next)) {
+    for (const t of step.next) if (t.when?.$ref) out.push(t.when.$ref);
+  }
+  return out;
+}
+function defineWorkflow(spec) {
+  if (!spec.name) throw new Error("defineWorkflow: `name` is required");
+  if (!spec.steps?.length) throw new Error(`defineWorkflow(${spec.name}): at least one step is required`);
+  const ids = /* @__PURE__ */ new Set();
+  for (const s of spec.steps) {
+    if (ids.has(s.id)) throw new Error(`defineWorkflow(${spec.name}): duplicate step id "${s.id}"`);
+    ids.add(s.id);
+    const kinds = [s.agent !== void 0, s.tool !== void 0, s.human !== void 0].filter(Boolean).length;
+    if (kinds !== 1) throw new Error(`defineWorkflow(${spec.name}): step "${s.id}" must have exactly one of agent/tool/human`);
+  }
+  const start = spec.start ?? spec.steps[0].id;
+  if (!ids.has(start)) throw new Error(`defineWorkflow(${spec.name}): start "${start}" is not a known step`);
+  const nextOf = (s) => {
+    const outs = s.next === void 0 ? [] : typeof s.next === "string" ? [s.next] : s.next.map((t) => t.to);
+    if (s.onError && typeof s.onError === "object" && "to" in s.onError) outs.push(s.onError.to);
+    return outs;
+  };
+  for (const s of spec.steps) {
+    for (const t of nextOf(s)) if (!ids.has(t)) throw new Error(`defineWorkflow(${spec.name}): step "${s.id}" \u2192 unknown step "${t}"`);
+    for (const r of workflowRefTargets(s)) {
+      if (r !== "input" && !(r.startsWith("steps.") && ids.has(r.slice("steps.".length)))) {
+        throw new Error(`defineWorkflow(${spec.name}): step "${s.id}" has an invalid $ref "${r}"`);
+      }
+    }
+  }
+  const byId = new Map(spec.steps.map((s) => [s.id, s]));
+  const seen = /* @__PURE__ */ new Set();
+  const stack = /* @__PURE__ */ new Set();
+  const visit = (id) => {
+    if (stack.has(id)) throw new Error(`defineWorkflow(${spec.name}): cycle detected at step "${id}"`);
+    if (seen.has(id)) return;
+    seen.add(id);
+    stack.add(id);
+    for (const t of nextOf(byId.get(id))) visit(t);
+    stack.delete(id);
+  };
+  visit(start);
+  return { name: spec.name, compliance: spec.compliance, description: spec.description, steps: spec.steps, start };
+}
 function buildSkillResolver(agents) {
   const map = /* @__PURE__ */ new Map();
   for (const a of agents) for (const s of a.skills ?? []) map.set(s.name, s);
   return (name) => map.get(name);
 }
+function isConnectorLooking(name) {
+  return name.includes(".");
+}
+function ruleToolRefs(rule) {
+  if (rule.seam !== "tool") return [];
+  const t = rule.when.tool;
+  const names = t === void 0 ? [] : Array.isArray(t) ? t : [t];
+  return names.filter((n) => !n.includes("*"));
+}
+var CRED_REF_KEYS = /* @__PURE__ */ new Set(["secretref", "credentialref", "connectionid", "owlconnections"]);
+var normKey = (k) => k.toLowerCase().replace(/[-_]/g, "");
+function assertNoCredRefs(obj, where) {
+  const walk = (v) => {
+    if (Array.isArray(v)) {
+      v.forEach(walk);
+      return;
+    }
+    if (v && typeof v === "object") {
+      for (const [k, val] of Object.entries(v)) {
+        if (CRED_REF_KEYS.has(normKey(k))) {
+          throw new Error(`defineBundle: ${where} carries a credential-ref key "${k}" \u2014 a bundle may not embed credential/connection handles; declare the capability and resolve creds per-tenant at call time`);
+        }
+        walk(val);
+      }
+    }
+  };
+  walk(obj);
+}
+function defineBundle(spec) {
+  if (!spec.slug) throw new Error("defineBundle: `slug` is required");
+  if (!spec.agents?.length) throw new Error(`defineBundle(${spec.slug}): at least one agent is required`);
+  const members = /* @__PURE__ */ new Set();
+  const handles = /* @__PURE__ */ new Set();
+  for (const a of spec.agents) {
+    if (members.has(a.slug)) throw new Error(`defineBundle(${spec.slug}): duplicate agent slug "${a.slug}"`);
+    members.add(a.slug);
+    for (const s of a.skills ?? []) handles.add(s.name);
+  }
+  const requires = spec.requires ?? [];
+  const requiredSlugs = new Set(requires.map((r) => r.slug));
+  const connectorGrants = spec.connectorGrants ?? [];
+  const grantedByMember = /* @__PURE__ */ new Map();
+  const allGranted = /* @__PURE__ */ new Set();
+  for (const g of connectorGrants) {
+    if (!members.has(g.agentSlug)) {
+      throw new Error(`defineBundle(${spec.slug}): connector grant targets unknown agent "${g.agentSlug}" (not a bundle member)`);
+    }
+    const set = grantedByMember.get(g.agentSlug) ?? /* @__PURE__ */ new Set();
+    for (const action of g.actions) {
+      const full = action.includes(".") ? action : `${g.provider}.${action}`;
+      set.add(full);
+      allGranted.add(full);
+    }
+    grantedByMember.set(g.agentSlug, set);
+  }
+  const agents = spec.agents.map((a) => {
+    const granted = grantedByMember.get(a.slug);
+    if (!granted || granted.size === 0) return a;
+    const extra = [...granted].filter((n) => !a.head.skillNames.includes(n));
+    return extra.length ? { ...a, head: { ...a.head, skillNames: [...a.head.skillNames, ...extra] } } : a;
+  });
+  const requireResolvable = (name, allowed, where) => {
+    if (handles.has(name)) return;
+    if (allowed?.has(name)) return;
+    if (isConnectorLooking(name)) {
+      throw new Error(`defineBundle(${spec.slug}): ${where} references connector action "${name}" with no first-party handle and no matching connector grant \u2014 add a \`connectorGrants\` entry, or attach a first-party handle`);
+    }
+    throw new Error(`defineBundle(${spec.slug}): ${where} references skill/tool "${name}" with no first-party handle in the bundle`);
+  };
+  for (const a of agents) {
+    const granted = grantedByMember.get(a.slug);
+    for (const name of a.head.skillNames) requireResolvable(name, granted, `agent "${a.slug}"`);
+    for (const d of a.head.delegateSlugs) {
+      if (!members.has(d) && !requiredSlugs.has(d)) {
+        throw new Error(`defineBundle(${spec.slug}): agent "${a.slug}" delegates to "${d}", which is neither a bundle member nor a declared \`requires\` dependency`);
+      }
+    }
+  }
+  const allRules = [...spec.rules ?? [], ...spec.agents.flatMap((a) => a.rules ?? [])];
+  for (const r of allRules) {
+    for (const t of ruleToolRefs(r)) {
+      if (t.startsWith("agent-")) continue;
+      requireResolvable(t, allGranted, `rule "${r.id}"`);
+    }
+  }
+  const allWorkflows = [...spec.workflows ?? [], ...spec.agents.flatMap((a) => a.workflow ? [a.workflow] : [])];
+  for (const w of allWorkflows) {
+    for (const step of w.steps) {
+      if (step.tool !== void 0) requireResolvable(step.tool, allGranted, `workflow "${w.name}" step "${step.id}"`);
+      assertNoCredRefs(step.args, `workflow "${w.name}" step "${step.id}" args`);
+      assertNoCredRefs(step.input, `workflow "${w.name}" step "${step.id}" input`);
+    }
+  }
+  return {
+    slug: spec.slug,
+    ...spec.title ? { title: spec.title } : {},
+    agents,
+    // members carry any granted connector action names in skillNames
+    rules: spec.rules ?? [],
+    // SWARM-scoped only (per-agent rules stay on the AgentDefs)
+    workflows: spec.workflows ?? [],
+    // SWARM-scoped only
+    connectorGrants,
+    requires
+  };
+}
+function mergeBundle(cfg, bundle) {
+  const existing = new Set(cfg.agents.map((a) => a.slug));
+  for (const a of bundle.agents) {
+    if (existing.has(a.slug)) {
+      throw new Error(`mergeBundle(${bundle.slug}): agent "${a.slug}" already exists in the swarm config \u2014 bundle members must not shadow host agents`);
+    }
+  }
+  return {
+    ...cfg,
+    agents: [...cfg.agents, ...bundle.agents],
+    rules: [...cfg.rules ?? [], ...bundle.rules],
+    workflows: [...cfg.workflows ?? [], ...bundle.workflows]
+  };
+}
+function toBundleContent(def) {
+  return {
+    slug: def.slug,
+    ...def.title ? { title: def.title } : {},
+    agents: def.agents.map((a) => {
+      const { version: _version, ...content } = a.head;
+      return content;
+    }),
+    rules: def.rules,
+    workflows: def.workflows,
+    connectorGrants: def.connectorGrants,
+    requires: def.requires
+  };
+}
 var ASK_TOOL_NAME = "ask";
 var askFieldSchema = import_zod4.z.object({
   kind: import_zod4.z.enum(["confirm", "buttons", "select", "multiselect", "number", "text", "textarea"]),
@@ -1395,23 +2884,63 @@ function buildAskMastraTool() {
 function defineSwarm(cfg) {
   const seedable = cfg.storage;
   for (const a of cfg.agents) seedable.seedAgent?.(a.head);
+  const rules = [...cfg.rules ?? [], ...cfg.agents.flatMap((a) => a.rules ?? [])];
+  const workflows = [...cfg.workflows ?? [], ...cfg.agents.flatMap((a) => a.workflow ? [a.workflow] : [])];
+  const namedWorkflows = workflows.filter((w) => w.compliance === "strict" && w.scopeAgent === void 0);
+  const agentWorkflows = {};
+  for (const w of workflows) if (w.compliance === "strict" && w.scopeAgent !== void 0) agentWorkflows[w.scopeAgent] = w;
+  const hasSoft = rules.some((r) => r.level === "advise") || workflows.some((w) => w.compliance === "advisory" && !!w.description);
+  const softPolicy = hasSoft ? (slug) => softPolicyFor(slug, rules, workflows) : void 0;
+  const policy = cfg.toolApproval ?? { mode: "flag" };
+  const enforceTool = rules.filter((r) => r.seam === "tool" && r.level === "enforce");
+  const enforceGen = rules.filter((r) => r.seam === "generation" && r.level === "enforce");
+  const composedHooks = { ...cfg.hooks };
+  if (enforceTool.length) composedHooks.preToolCall = composeToolHooks({ rules: enforceTool, host: cfg.hooks?.preToolCall, policy });
+  if (enforceGen.length) composedHooks.preGeneration = composeGenerationHooks({ rules: enforceGen, host: cfg.hooks?.preGeneration });
   const engine = new SwarmEngine({
+    softPolicy,
+    workflows: namedWorkflows,
+    agentWorkflows,
     storage: cfg.storage,
     model: allowListModelProvider({ allow: cfg.models.allow }),
     modelFactory: cfg.modelFactory,
+    // SP10: thread the optional cheap-model router onto the engine. The allow-list above still validates every
+    // resolved model — incl. a routed tier model. Undefined ⇒ no routing (identical to today).
+    tier: cfg.models.tier,
     cost: cfg.cost,
     // Per-swarm skill registry, built from the agents passed in. No global state.
     resolveSkill: buildSkillResolver(cfg.agents),
+    // PR2: opt-in connector-tools resolver (built by the host via materializeConnectors). Undefined ⇒ no-op.
+    connectorTools: cfg.connectorTools,
     telemetry: resolveTelemetry(cfg.telemetry),
     mastraStore: cfg.mastraStore,
     memory: cfg.memory,
     pageContext: cfg.pageContext,
     scratchpad: cfg.scratchpad,
-    recallLane: cfg.recallLane
+    recallLane: cfg.recallLane,
+    // SP2 + SP5: build the decision-hook dispatcher once per swarm, baking in the non-removable tool-approval
+    // policy. Always present (allow-all hooks + `{ mode: "flag" }` policy when unconfigured, so the engine's
+    // seams stay uniform — no null-checks on the hot path). The dispatcher combines policy + the per-tool flag +
+    // the optional `preToolCall` hook into the effective ToolDecision.
+    hooks: (0, import_hooks3.createHookDispatcher)(composedHooks, cfg.toolApproval),
+    // SP5: also pass the policy standalone so an engine built without a dispatcher (direct construction) still
+    // enforces it; redundant here (the dispatcher already carries it) but keeps EngineOpts self-describing.
+    toolApproval: cfg.toolApproval,
+    // SP15: thread the optional SecretResolver onto the engine, which injects it per-run on the RequestContext.
+    secrets: cfg.secrets,
+    // SP3: best-effort per-event observer (metering debit/settle) — transport-agnostic, fired in run + resume.
+    onEvent: cfg.onEvent,
+    verifyCompletion: cfg.verifyCompletion,
+    // FR-003: per-run lifecycle hooks (seed `ctx.state` at run start, drain at run end).
+    onRunStart: cfg.onRunStart,
+    onRunEnd: cfg.onRunEnd
   });
   return { engine };
 }
 
+// src/index.ts
+var import_hooks4 = require("@nightowlsdev/hooks");
+
 // src/storage/memory.ts
 var InMemoryStorage = class {
   evts = [];
@@ -1428,6 +2957,8 @@ var InMemoryStorage = class {
   heads = /* @__PURE__ */ new Map();
   // key: tenantId:slug -> version
   pads = /* @__PURE__ */ new Map();
+  threadRows = /* @__PURE__ */ new Map();
+  // FR-009
   seedAgent(v, tenantId = "default") {
     this.agentRows.set(`${tenantId}:${v.slug}:${v.version}`, v);
     this.heads.set(`${tenantId}:${v.slug}`, v.version);
@@ -1436,7 +2967,7 @@ var InMemoryStorage = class {
     this.suspends.set(`${tenantId}:${followupId}`, { runId, toolCallId });
   }
   markFollowupAnswered(followupId, tenantId) {
-    this.suspends.delete(`${tenantId}:${followupId}`);
+    return this.suspends.delete(`${tenantId}:${followupId}`);
   }
   /** Test/host helper: read a run row (the RunStore interface is write-mostly). */
   getRun(runId) {
@@ -1511,6 +3042,18 @@ var InMemoryStorage = class {
     },
     getWaitpoint: async (followupId) => this.waitpoints.get(followupId) ?? null
   };
+  // FR-009: idempotent thread-row creation. The dev store has no FK, so `messages.append` never threw `unknown
+  // thread` here — this implements the contract so the engine's run-start ensure works against the in-memory store
+  // too, and a host can read back the recorded thread (getThread) in tests.
+  threads = {
+    ensure: async ({ id, orgId, userId, projectId }) => {
+      if (!this.threadRows.has(id)) this.threadRows.set(id, { id, orgId, userId, projectId });
+    }
+  };
+  /** Test/host helper: read a recorded thread row. */
+  getThread(id) {
+    return this.threadRows.get(id);
+  }
   messages = {
     append: async (m) => {
       this.msgs.push(m);
@@ -1550,21 +3093,119 @@ var InMemoryStorage = class {
   };
 };
 
+// src/run-agent.ts
+function uid() {
+  return globalThis.crypto?.randomUUID?.() ?? `id-${Math.random().toString(36).slice(2)}-${Date.now().toString(36)}`;
+}
+async function drainTrajectory(stream) {
+  const events = [];
+  let output = "";
+  for await (const e of stream) {
+    events.push(e);
+    if (e.type === "swarm.message") {
+      const d = e.data;
+      if (d.role === "assistant") output += d.delta ?? d.text ?? "";
+    }
+  }
+  return { events, output };
+}
+async function runToTrajectory(target, input, ctx) {
+  const engine = "engine" in target ? target.engine : target;
+  const runInput = typeof input === "string" ? { message: input } : input;
+  const full = ephemeralCtx(ctx?.agentSlug ?? "agent", ctx);
+  return drainTrajectory(engine.run(runInput, full));
+}
+function ephemeralCtx(agentSlug, over) {
+  return {
+    tenantId: over?.tenantId ?? "default",
+    userId: over?.userId ?? "local",
+    agentSlug: over?.agentSlug ?? agentSlug,
+    runId: over?.runId ?? uid(),
+    threadId: over?.threadId ?? uid(),
+    ...over?.agentVersion !== void 0 ? { agentVersion: over.agentVersion } : {}
+  };
+}
+function buildSingleAgentSwarm(def, opts) {
+  const t = opts.models?.tier;
+  const tierAllow = t ? [t.tiers.swift, ...t.tiers.genius ? [t.tiers.genius] : []] : [];
+  const allow = opts.models?.allow ?? [def.head.modelId, ...tierAllow];
+  const storage = opts.storage ?? new InMemoryStorage();
+  const cfg = {
+    storage,
+    agents: [def],
+    models: { allow, ...opts.models?.tier ? { tier: opts.models.tier } : {} },
+    modelFactory: opts.modelFactory,
+    cost: { maxSteps: 50, maxCostUsd: 10, ...opts.cost },
+    ...opts.telemetry !== void 0 ? { telemetry: opts.telemetry } : {},
+    ...opts.memory !== void 0 ? { memory: opts.memory } : {},
+    ...opts.hooks !== void 0 ? { hooks: opts.hooks } : {},
+    ...opts.toolApproval !== void 0 ? { toolApproval: opts.toolApproval } : {},
+    ...opts.secrets !== void 0 ? { secrets: opts.secrets } : {},
+    ...opts.onEvent !== void 0 ? { onEvent: opts.onEvent } : {},
+    ...opts.onRunStart !== void 0 ? { onRunStart: opts.onRunStart } : {},
+    ...opts.onRunEnd !== void 0 ? { onRunEnd: opts.onRunEnd } : {},
+    ...opts.pageContext !== void 0 ? { pageContext: opts.pageContext } : {},
+    ...opts.mastraStore !== void 0 ? { mastraStore: opts.mastraStore } : {}
+  };
+  return defineSwarm(cfg);
+}
+async function runAgent(def, input, opts) {
+  const swarm = buildSingleAgentSwarm(def, opts);
+  const runInput = typeof input === "string" ? { message: input } : input;
+  const ctx = ephemeralCtx(def.head.slug, { ...opts.ctx, agentSlug: def.head.slug });
+  return drainTrajectory(swarm.engine.run(runInput, ctx));
+}
+
 // src/auth.ts
 var customAuth = (fn) => ({ authenticate: fn });
 
+// src/rate-limit.ts
+function decideFixedWindow(prev, cfg, nowSec) {
+  const windowValid = prev && nowSec - prev.windowStartSec < cfg.windowSec;
+  const state = windowValid ? { count: prev.count + 1, windowStartSec: prev.windowStartSec } : { count: 1, windowStartSec: nowSec };
+  const resetSec = Math.max(0, state.windowStartSec + cfg.windowSec - nowSec);
+  const allow = state.count <= cfg.max;
+  return { decision: { allow, remaining: Math.max(0, cfg.max - state.count), resetSec }, state };
+}
+function createInMemoryRateLimitStore() {
+  const states = /* @__PURE__ */ new Map();
+  let lastPruneSec = 0;
+  return {
+    async hit(key, cfg, nowSec) {
+      if (nowSec > lastPruneSec) {
+        for (const [k, s] of states) if (nowSec - s.windowStartSec >= cfg.windowSec) states.delete(k);
+        lastPruneSec = nowSec;
+      }
+      const { decision, state } = decideFixedWindow(states.get(key) ?? null, cfg, nowSec);
+      states.set(key, state);
+      return decision;
+    }
+  };
+}
+function rateConfig(max, windowSec, fallbackMax) {
+  const m = Number.isFinite(max) && max > 0 ? Math.floor(max) : fallbackMax;
+  return { windowSec, max: m };
+}
+
 // src/index.ts
 var VERSION = "0.0.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ALLOW,
+  ALLOW_TOOL,
   ASK_TOOL_NAME,
+  AgentMutationForbidden,
   CapturingExporter,
+  ClientToolError,
   CostGovernor,
+  DEFAULT_READ_ONLY_TOOLS,
   DelegateBudgets,
   GUARDRAILS,
+  HookDispatcher,
   InMemoryContainerFloor,
   InMemoryStorage,
   PRICE_TABLE,
+  ReserveDenied,
   RowCache,
   SCRATCHPAD_MAX_ENTRY_CHARS,
   SCRATCHPAD_MAX_KEYS,
@@ -1572,17 +3213,43 @@ var VERSION = "0.0.0";
   SwarmEngine,
   VERSION,
   allowListModelProvider,
+  ask,
+  assertActorMayMutateDefinition,
+  buildSingleAgentSwarm,
   buildSkillResolver,
+  composePolicyPrompt,
   composeSystemPrompt,
   compositeTelemetry,
   containerFloor,
+  createHookDispatcher,
+  createInMemoryRateLimitStore,
+  createRunState,
   customAuth,
   customTelemetry,
+  decideFixedWindow,
   defineAgent,
+  defineBundle,
+  defineClientTool,
+  defineHook,
+  defineRule,
   defineSkill,
   defineSwarm,
   defineTool,
+  defineWorkflow,
+  deny,
+  drainTrajectory,
   ev,
   isEvent,
-  resolveTelemetry
+  isTierSentinel,
+  mergeBundle,
+  priceUsage,
+  rateConfig,
+  resolveTelemetry,
+  resolveTier,
+  runAgent,
+  runToTrajectory,
+  sumBreakdowns,
+  sumTurnUsage,
+  tierModelId,
+  toBundleContent
 });