@nightowlsdev/engine-ai-sdk 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1360 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AI_SDK_ENGINE_CAPABILITIES: () => AI_SDK_ENGINE_CAPABILITIES,
+  AiSdkEngine: () => AiSdkEngine,
+  aiSdkEngine: () => aiSdkEngine,
+  nightOwlsPlugin: () => nightOwlsPlugin
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/engine.ts
+var import_ai2 = require("ai");
+var import_core4 = require("@nightowlsdev/core");
+var import_engine_spi2 = require("@nightowlsdev/core/engine-spi");
+
+// src/capabilities.ts
+var AI_SDK_ENGINE_CAPABILITIES = {
+  contract: 1,
+  id: "ai-sdk",
+  kind: "native",
+  events: {
+    tier: 3,
+    emits: [
+      "swarm.message",
+      "swarm.status",
+      "swarm.run_failed",
+      "swarm.run_cancelled",
+      "swarm.question",
+      "swarm.answer",
+      "swarm.client_action",
+      "swarm.tool_call",
+      "swarm.tool_result",
+      "swarm.usage",
+      "swarm.turn_usage"
+    ]
+  },
+  streaming: { seq: "global", persistsUserMessage: true },
+  hitl: { ask: true, approval: true, clientTools: true, durableResume: false },
+  delegation: false,
+  workflows: false,
+  rules: true,
+  memory: { history: true, semanticRecall: false, workingMemory: false, observational: false },
+  scratchpad: true,
+  cancellation: "mid-stream",
+  governance: { preGeneration: true, preToolCall: "fail-closed", costCaps: true, secrets: true },
+  telemetry: true
+};
+
+// src/emit.ts
+var import_core = require("@nightowlsdev/core");
+function makeEmitter(opts) {
+  let ts = opts.startTs ?? 0;
+  return {
+    ev(type, data) {
+      return (0, import_core.ev)(type, { runId: opts.ctx.runId, agentSlug: opts.ctx.agentSlug, ts: ts++ }, data);
+    },
+    async emit(e) {
+      e.seq = await opts.storage.events.append(e);
+      if (opts.onEvent) {
+        try {
+          await opts.onEvent(e, opts.ctx);
+        } catch (err) {
+          console.error(`[@nightowlsdev/engine-ai-sdk] onEvent threw for ${e.type}`, err);
+        }
+      }
+      return e;
+    }
+  };
+}
+
+// src/tools.ts
+var import_zod = require("zod");
+var import_ai = require("ai");
+var import_core2 = require("@nightowlsdev/core");
+var import_engine_spi = require("@nightowlsdev/core/engine-spi");
+
+// src/errors.ts
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// src/internal/brand.ts
+var GATED_DENIED = /* @__PURE__ */ Symbol("nightowls.gated_denied");
+
+// src/map-chunks.ts
+function isBrandedDenied(x) {
+  return typeof x === "object" && x !== null && x[GATED_DENIED] === true;
+}
+function mapChunks(part, ctx) {
+  switch (part.type) {
+    case "text-delta":
+      return [
+        { kind: "event", type: "swarm.message", agentSlug: ctx.agentSlug, data: { role: "assistant", delta: part.text } }
+      ];
+    case "tool-call":
+      return [
+        {
+          kind: "event",
+          type: "swarm.tool_call",
+          agentSlug: ctx.agentSlug,
+          data: {
+            toolCallId: part.toolCallId,
+            name: part.toolName,
+            args: part.input,
+            needsApproval: ctx.gatesApproval(part.toolName)
+          }
+        }
+      ];
+    case "tool-result": {
+      const { toolCallId } = part;
+      const output = part.output;
+      if (isBrandedDenied(output)) {
+        return [
+          {
+            kind: "event",
+            type: "swarm.tool_result",
+            agentSlug: ctx.agentSlug,
+            data: { toolCallId, ok: false, error: output.reason ?? output.error ?? "blocked" }
+          }
+        ];
+      }
+      return [
+        { kind: "event", type: "swarm.tool_result", agentSlug: ctx.agentSlug, data: { toolCallId, ok: true, result: output } }
+      ];
+    }
+    case "tool-output-denied":
+      return [
+        {
+          kind: "event",
+          type: "swarm.tool_result",
+          agentSlug: ctx.agentSlug,
+          data: {
+            toolCallId: part.toolCallId,
+            ok: false,
+            error: part.reason ?? "rejected by approver"
+          }
+        }
+      ];
+    case "tool-error":
+      return [
+        {
+          kind: "event",
+          type: "swarm.tool_result",
+          agentSlug: ctx.agentSlug,
+          data: { toolCallId: part.toolCallId, ok: false, error: errorMessage(part.error) }
+        }
+      ];
+    case "tool-approval-request":
+      return [
+        {
+          kind: "park",
+          approvalId: part.approvalId,
+          toolCallId: part.toolCall.toolCallId,
+          toolName: part.toolCall.toolName,
+          input: part.toolCall.input
+        }
+      ];
+    case "finish-step":
+      return [{ kind: "step-usage", usage: part.usage }];
+    case "abort":
+      return [{ kind: "cancel", reason: part.reason }];
+    case "error":
+      return [{ kind: "failure", error: part.error }];
+    default:
+      return [];
+  }
+}
+
+// src/internal/container.ts
+function containerOf(threadId) {
+  return threadId.split(":")[0] || threadId;
+}
+
+// src/tools.ts
+var RECALL_LANE_LIMIT = 20;
+function buildServerTool(spec, handle, opts, runCtx, gateMemo) {
+  const toolCtx = {
+    tenantId: runCtx.ctx.tenantId,
+    userId: runCtx.ctx.userId,
+    runId: runCtx.ctx.runId,
+    secrets: (0, import_engine_spi.bindSecrets)(opts.secrets, runCtx.ctx),
+    state: runCtx.state
+  };
+  const runBody = (input) => spec.execute(input, toolCtx);
+  const resolveGate = async (input) => {
+    const ev = (0, import_engine_spi.toolPreCallEvent)({
+      runId: runCtx.ctx.runId,
+      tenantId: runCtx.ctx.tenantId,
+      agentSlug: runCtx.ctx.agentSlug,
+      toolName: spec.name,
+      origin: handle.origin,
+      needsApproval: handle.needsApproval,
+      args: input
+    });
+    let decision;
+    try {
+      decision = await opts.gate(ev);
+    } catch (err) {
+      return { action: "gate-error", error: errorMessage(err) };
+    }
+    if (decision.action === "deny") return { action: "deny", reason: decision.reason };
+    if (decision.action === "ask") return { action: "ask" };
+    return { action: "allow" };
+  };
+  return (0, import_ai.tool)({
+    description: spec.description ?? spec.name,
+    // spec.outputSchema is deliberately NOT forwarded: a branded GATED_DENIED return would fail output
+    // validation (the same reason core's define.ts THROWS ToolBlockedError instead of returning a sentinel).
+    inputSchema: spec.inputSchema,
+    needsApproval: async (input, { toolCallId }) => {
+      if (runCtx.approvedToolCallIds.has(toolCallId)) return false;
+      let memoPromise = gateMemo.get(toolCallId);
+      if (!memoPromise) {
+        memoPromise = resolveGate(input);
+        gateMemo.set(toolCallId, memoPromise);
+      }
+      const memo = await memoPromise;
+      return memo.action === "ask";
+    },
+    execute: async (input, options) => {
+      if (runCtx.approvedToolCallIds.has(options.toolCallId)) {
+        return runBody(input);
+      }
+      const memoPromise = gateMemo.get(options.toolCallId);
+      if (memoPromise) {
+        const memo = await memoPromise;
+        switch (memo.action) {
+          case "allow":
+            return runBody(input);
+          case "deny":
+            return { [GATED_DENIED]: true, reason: memo.reason };
+          case "gate-error":
+            return { [GATED_DENIED]: true, error: memo.error };
+          case "ask":
+            return runBody(input);
+        }
+      }
+      const late = await resolveGate(input);
+      switch (late.action) {
+        case "allow":
+          return runBody(input);
+        case "deny":
+          return { [GATED_DENIED]: true, reason: late.reason };
+        case "gate-error":
+          return { [GATED_DENIED]: true, error: late.error };
+        case "ask":
+          return {
+            [GATED_DENIED]: true,
+            reason: "approval required but the engine cannot suspend mid-execute"
+          };
+      }
+    }
+  });
+}
+var CLIENT_NEEDS_APPROVAL = /* @__PURE__ */ new WeakMap();
+function clientNeedsApprovalOf(t) {
+  return (t && CLIENT_NEEDS_APPROVAL.get(t)) ?? false;
+}
+function buildClientTool(spec) {
+  const t = (0, import_ai.tool)({
+    description: spec.description ?? spec.name,
+    inputSchema: spec.inputSchema
+  });
+  CLIENT_NEEDS_APPROVAL.set(t, spec.needsApproval ?? false);
+  return t;
+}
+async function connectorToolsByName(resolve, ctx) {
+  if (!resolve) return {};
+  const out = {};
+  for (const t of await resolve(ctx)) out[t.name] = t;
+  return out;
+}
+var askFieldSchema = import_zod.z.object({
+  kind: import_zod.z.enum(["confirm", "buttons", "select", "multiselect", "number", "text", "textarea"]),
+  options: import_zod.z.array(import_zod.z.object({ label: import_zod.z.string(), value: import_zod.z.string(), description: import_zod.z.string().optional() })).optional(),
+  min: import_zod.z.number().optional(),
+  max: import_zod.z.number().optional(),
+  step: import_zod.z.number().optional(),
+  unit: import_zod.z.string().optional(),
+  placeholder: import_zod.z.string().optional(),
+  rows: import_zod.z.number().optional(),
+  confirmLabel: import_zod.z.string().optional(),
+  rejectLabel: import_zod.z.string().optional(),
+  submitLabel: import_zod.z.string().optional(),
+  default: import_zod.z.any().optional()
+});
+function buildAskTool() {
+  return (0, import_ai.tool)({
+    description: "Ask a follow-up question to the user (or another agent) when blocked. Prefer a RICH `field` so the user gets a fitting control instead of a text box: {kind:'confirm'} for yes/no; {kind:'buttons'|'select'|'multiselect', options:[{label,value}]} for choices; {kind:'number', min,max,step,unit} for a number; {kind:'text'|'textarea', placeholder} for free text. Omit `field` for a plain text answer. `prompt` may be markdown.",
+    inputSchema: import_zod.z.object({ to: import_zod.z.string().default("user"), prompt: import_zod.z.string(), field: askFieldSchema.optional() })
+  });
+}
+function buildScratchpadWriteTool(store, caps, runCtx) {
+  const maxEntryChars = caps?.maxEntryChars ?? import_core2.SCRATCHPAD_MAX_ENTRY_CHARS;
+  return (0, import_ai.tool)({
+    description: "Record a fact on the shared scratchpad under a short KEY. Re-use the same key to update that fact in place; different keys are independent so you never clobber a peer. Use `public` for facts the user should see, `meta` for internal agent notes. Record proactively as you work.",
+    inputSchema: import_zod.z.object({
+      section: import_zod.z.enum(["public", "meta"]),
+      key: import_zod.z.string().describe("a short stable slug for THIS fact, e.g. 'launch-date' \u2014 reuse it to revise that fact"),
+      content: import_zod.z.string()
+    }),
+    execute: async (input) => {
+      const { section, key, content } = input;
+      const capped = content.length > maxEntryChars ? content.slice(0, maxEntryChars) + "\u2026[truncated]" : content;
+      await store.write(runCtx.ctx.tenantId, containerOf(runCtx.ctx.threadId), section, key, capped, {
+        agentSlug: runCtx.ctx.agentSlug,
+        userId: runCtx.ctx.userId,
+        requestedBy: "user",
+        maxKeys: caps?.maxKeys
+      });
+      return { ok: true, section, key };
+    }
+  });
+}
+function buildRecallLaneTool(runCtx) {
+  return (0, import_ai.tool)({
+    description: "Read the recent transcript of another agent's lane in THIS conversation. Use it when you suspect a peer agent discussed something relevant that isn't on the shared scratchpad. Pass the peer's agent slug; you get back their last messages. Pass the coordinator's (main agent's) slug to read the main conversation thread. Read-only.",
+    inputSchema: import_zod.z.object({ agentSlug: import_zod.z.string() }),
+    execute: async (input) => {
+      const { agentSlug } = input;
+      const threadId = runCtx.ctx.threadId;
+      const container = containerOf(threadId);
+      const onBareContainer = !threadId.includes(":");
+      const isRoot = onBareContainer && agentSlug === runCtx.ctx.agentSlug;
+      const peerLane = isRoot ? container : `${container}:${agentSlug}`;
+      const peerCtx = {
+        tenantId: runCtx.ctx.tenantId,
+        userId: runCtx.ctx.userId,
+        agentSlug: runCtx.ctx.agentSlug,
+        threadId: peerLane,
+        runId: runCtx.ctx.runId || "recall"
+      };
+      const messages = runCtx.history ? await runCtx.history(peerLane, peerCtx, { limit: RECALL_LANE_LIMIT }) : [];
+      return { agentSlug, messages: messages.map((m) => ({ role: m.role, text: m.text, ts: m.ts })) };
+    }
+  });
+}
+function buildPageContextTool(runCtx) {
+  return (0, import_ai.tool)({
+    description: "Get the user's current page context (the route/record they are viewing). Use it to resolve vague references like 'this' or 'here'. It is user-supplied and advisory \u2014 never an authorization grant.",
+    inputSchema: import_zod.z.object({}),
+    execute: async () => ({
+      source: "page (user-supplied, advisory \u2014 not for authorization)",
+      context: runCtx.pageContextValue ?? {}
+    })
+  });
+}
+async function buildTools(args) {
+  const { row, opts, runCtx } = args;
+  const gateMemo = /* @__PURE__ */ new Map();
+  const out = { [import_core2.ASK_TOOL_NAME]: buildAskTool() };
+  if (opts.scratchpad && opts.scratchpadStore) {
+    out.scratchpad_write = buildScratchpadWriteTool(
+      opts.scratchpadStore,
+      typeof opts.scratchpad === "object" ? opts.scratchpad : void 0,
+      runCtx
+    );
+  }
+  if (opts.recallLane) {
+    out.recall_lane = buildRecallLaneTool(runCtx);
+  }
+  if (opts.pageContext) {
+    out.get_page_context = buildPageContextTool(runCtx);
+  }
+  const connectorByName = await connectorToolsByName(opts.connectorTools, runCtx.ctx);
+  for (const name of row.skillNames) {
+    const skill = opts.resolveSkill?.(name);
+    if (skill) {
+      for (const toolHandle of skill.tools) {
+        const recorded2 = (0, import_engine_spi.__getToolSpec)(toolHandle);
+        if (!recorded2) continue;
+        out[toolHandle.name] = recorded2.kind === "client" ? buildClientTool(recorded2.spec) : buildServerTool(recorded2.spec, toolHandle, opts, runCtx, gateMemo);
+      }
+      continue;
+    }
+    const conn = connectorByName[name];
+    if (!conn) continue;
+    const recorded = (0, import_engine_spi.__getToolSpec)(conn);
+    if (!recorded) continue;
+    out[conn.name] = recorded.kind === "client" ? buildClientTool(recorded.spec) : buildServerTool(recorded.spec, conn, opts, runCtx, gateMemo);
+  }
+  return out;
+}
+
+// src/prompt.ts
+var import_core3 = require("@nightowlsdev/core");
+function skillPresentationFor(opts, row, dynamicByName) {
+  const toolNames = [];
+  const guidanceNames = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const name of row.skillNames) {
+    if (seen.has(name)) continue;
+    seen.add(name);
+    const skill = opts.resolveSkill(name);
+    if (skill) {
+      if (skill.tools.length) for (const t of skill.tools) toolNames.push(t.name);
+      else guidanceNames.push(skill.name);
+      continue;
+    }
+    if (dynamicByName[name]) guidanceNames.push(name);
+    else toolNames.push(name);
+  }
+  return { toolNames: [...new Set(toolNames)], guidanceNames };
+}
+function grantedSkillsFor(opts, row, dynamicByName) {
+  const seen = /* @__PURE__ */ new Set();
+  const skills = [];
+  for (const name of row.skillNames) {
+    const s = opts.resolveSkill(name) ?? dynamicByName[name];
+    if (s && !seen.has(s.name)) {
+      seen.add(s.name);
+      skills.push(s);
+    }
+  }
+  return skills;
+}
+async function buildSystemMessages(args) {
+  const { row, opts, ctx, dynamicSkillsResolved, systemContextText } = args;
+  const presentation = skillPresentationFor(opts, row, dynamicSkillsResolved);
+  let messages = (0, import_core3.composeSystemPrompt)(row, presentation);
+  messages = [...messages, ...(0, import_core3.composePolicyPrompt)(opts.softPolicy?.(row.slug) ?? [])];
+  messages = [...messages, ...(0, import_core3.composeSkillInstructions)(grantedSkillsFor(opts, row, dynamicSkillsResolved))];
+  if (opts.scratchpad && opts.loadScratchpad) {
+    const container = ctx.threadId.split(":")[0] ?? "";
+    const entries = await opts.loadScratchpad(container, ctx.tenantId);
+    messages = [...messages, (0, import_core3.composeScratchpadPrompt)(entries)];
+  }
+  if (systemContextText) {
+    messages = [...messages, (0, import_core3.composeAdvisoryContext)(systemContextText)];
+  }
+  return messages;
+}
+
+// src/usage.ts
+function extractUsage(u) {
+  const breakdown = {
+    inputTokens: u.inputTokens ?? 0,
+    outputTokens: u.outputTokens ?? 0
+  };
+  const cacheReadTokens = u.inputTokenDetails?.cacheReadTokens;
+  if (cacheReadTokens != null) breakdown.cacheReadTokens = cacheReadTokens;
+  const cacheWriteTokens = u.inputTokenDetails?.cacheWriteTokens;
+  if (cacheWriteTokens != null) breakdown.cacheWriteTokens = cacheWriteTokens;
+  const reasoningTokens = u.outputTokenDetails?.reasoningTokens;
+  if (reasoningTokens != null) breakdown.reasoningTokens = reasoningTokens;
+  return breakdown;
+}
+
+// src/engine.ts
+function titleCase(slug) {
+  return slug.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+var LEGACY_ASSISTANT_PREFIX_RE = /^\[([a-z0-9][a-z0-9-]*)\]\s([\s\S]*)$/;
+var LEGACY_USER_PREFIX_RE = /^\[user:([^\]]*)\]\s([\s\S]*)$/;
+function messagesFromEvents(threadId, events) {
+  const out = [];
+  let cur = null;
+  const flush = () => {
+    if (!cur) return;
+    const { role, ts, agentSlug } = cur;
+    let text = cur.parts.join("");
+    let userId;
+    if (role === "assistant") {
+      const m = LEGACY_ASSISTANT_PREFIX_RE.exec(text);
+      if (m) text = m[2];
+    } else {
+      const m = LEGACY_USER_PREFIX_RE.exec(text);
+      if (m) {
+        userId = m[1];
+        text = m[2];
+      }
+    }
+    out.push({
+      threadId,
+      role,
+      text,
+      ts,
+      ...role === "assistant" && agentSlug ? { agentSlug } : {},
+      ...userId ? { userId } : {}
+    });
+    cur = null;
+  };
+  for (const e of events) {
+    if (e.type === "swarm.message") {
+      const role = e.data.role;
+      const raw = e.data.delta ?? e.data.text ?? "";
+      if (cur && cur.role === role) {
+        cur.parts.push(raw);
+      } else {
+        flush();
+        cur = { role, parts: [raw], ts: e.ts, agentSlug: role === "assistant" ? e.agentSlug : void 0 };
+      }
+    } else {
+      flush();
+    }
+  }
+  flush();
+  return out;
+}
+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.` : "[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 isValidAiSdkSnapshot(snap) {
+  if (!snap || typeof snap !== "object") return false;
+  const s = snap;
+  if (s.v !== 1) return false;
+  if (s.kind !== "ask" && s.kind !== "approval" && s.kind !== "client") return false;
+  if (typeof s.toolCallId !== "string") return false;
+  if (!Array.isArray(s.messages)) return false;
+  if (s.kind === "approval" && typeof s.approvalId !== "string") return false;
+  return true;
+}
+var VERIFY_TRANSCRIPT_CAP = 6e3;
+var HISTORY_PROMPT_CAP = 20;
+function appendTranscript(t, add) {
+  return add ? (t + add).slice(-VERIFY_TRANSCRIPT_CAP) : t;
+}
+function isAbortLike(err) {
+  return err instanceof Error && err.name === "AbortError";
+}
+var warnedNoRecordSuspend = false;
+async function recordSuspendSafe(storage, ctx, followupId, toolCallId) {
+  if (!storage.recordSuspend && !warnedNoRecordSuspend) {
+    warnedNoRecordSuspend = true;
+    console.warn(
+      "[@nightowlsdev/engine-ai-sdk] 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);
+}
+async function* finishDoneSeg(io) {
+  await io.runsStore.setStatus(io.ctx.runId, "done");
+  const t = await io.emitTurnUsage(io.segmentIndex);
+  if (t) yield t;
+  yield await io.emit(io.ev("swarm.status", { state: "done" }));
+}
+async function* finishFailedSeg(io, stage, message, retryable = false) {
+  try {
+    await io.runsStore.setStatus(io.ctx.runId, "failed");
+  } catch {
+  }
+  const t = await io.emitTurnUsage(io.segmentIndex);
+  if (t) yield t;
+  yield await io.emit(io.ev("swarm.run_failed", { stage, message, retryable }));
+}
+async function* finishCancelledSeg(io) {
+  await io.runsStore.setStatus(io.ctx.runId, "failed");
+  const t = await io.emitTurnUsage(io.segmentIndex);
+  if (t) yield t;
+  yield await io.emit(io.ev("swarm.run_cancelled", { reason: "aborted" }));
+}
+var AiSdkEngine = class {
+  constructor(opts, extra) {
+    this.opts = opts;
+    this.hooks = opts.hooks ?? new import_core4.HookDispatcher({}, opts.toolApproval ?? { mode: "flag" });
+    this.floor = opts.floor ?? import_core4.containerFloor;
+    this.telemetry = (0, import_core4.resolveTelemetry)(opts.telemetry ?? void 0);
+    this.capabilities = extra.durable ? { ...AI_SDK_ENGINE_CAPABILITIES, hitl: { ...AI_SDK_ENGINE_CAPABILITIES.hitl, durableResume: true } } : AI_SDK_ENGINE_CAPABILITIES;
+  }
+  opts;
+  capabilities;
+  hooks;
+  floor;
+  telemetry;
+  /**
+   * SP2 — the preGeneration DECISION seam, awaited immediately before every model launch. Verbatim mirror of
+   * the reference engine's private `guardGeneration` (`packages/core/src/engine.ts:543-553`): the dispatcher is
+   * fail-closed (a throwing hook ⇒ deny), so this only ever sees a clean allow/deny; a deny THROWS
+   * `ReserveDenied` (re-exported from core, not redefined here) so the caller's model launch never happens and
+   * the run/resume catch-all maps it to a terminal `run_failed` stage `"reserve"` (never the generic
+   * `"exception"`).
+   */
+  async guardGeneration(ev) {
+    const decision = await this.hooks.preGeneration(ev);
+    if (decision.action === "deny") throw new import_core4.ReserveDenied(decision.reason);
+  }
+  /**
+   * SP5 truth-fix — resolve whether a tool WILL require approval, for the `swarm.tool_call` event's advisory
+   * `needsApproval` field. Verbatim mirror of the reference engine's private `gatesApproval`
+   * (`packages/core/src/engine.ts:528-534`): the tool's resolved `needsApproval` (its own flag, defaulting by
+   * origin) run through the dispatcher's SYNC `policyDecision` (`ask` ⇒ true). The async `preToolCall` hook can
+   * still escalate a specific call at execute time (that's what actually drives the tool's native pause — see
+   * `tools.ts`'s `buildServerTool`); this is only the truthful baseline the event carries.
+   */
+  gatesApproval(toolName) {
+    const tool2 = this.opts.resolveSkill?.(toolName)?.tools.find((t) => t.name === toolName);
+    const origin = tool2?.origin ?? "first-party";
+    const needsApproval = tool2?.needsApproval ?? origin === "mcp";
+    const decision = this.hooks.policyDecision({ runId: "", agentSlug: "", toolName, origin, needsApproval });
+    return decision.action === "ask";
+  }
+  /**
+   * T9 (T8-review fix) — best-effort recall of the thread's request text for the completion verifier's
+   * `request` param on RESUME (the engine doesn't hold the original prompt there — `resume()` only carries the
+   * suspended tool's answer). Mirrors the reference engine's `recallRequest`, but deliberately the LAST user
+   * turn (not the first): a resume continues whichever prompt MOST RECENTLY triggered this run, not the
+   * thread's opening message. Fail-safe: gated behind `verifyCompletion` (a no-verifier config never pays for
+   * the read) and never throws — any failure yields `""`, matching the reference's own fallback.
+   */
+  async recallRequest(ctx) {
+    if (!this.opts.verifyCompletion) return "";
+    try {
+      const msgs = await this.history(ctx.threadId, ctx, { limit: 50 });
+      for (let i = msgs.length - 1; i >= 0; i--) {
+        if (msgs[i].role === "user") return msgs[i].text;
+      }
+      return "";
+    } catch {
+      return "";
+    }
+  }
+  /** Run the completion supervisor (`EngineOpts.verifyCompletion`), FAIL-OPEN: no verifier, or a throwing one,
+   *  yields `{ complete: true }` so a missing/broken judge never traps a run in a verify loop. Mirrors the
+   *  reference engine's private `safeVerify`. */
+  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/engine-ai-sdk] verifyCompletion threw for run ${ctx.runId} \u2014 treating as complete:`, err);
+      return { complete: true };
+    }
+  }
+  /** FR-024 — resolve the host's per-run advisory system-context block. FAIL-SAFE: a throwing/rejecting resolver
+   *  is swallowed (logged) and yields no block, so a broken context source never breaks the run. Mirrors the
+   *  reference engine's private `safeSystemContext`. */
+  async safeSystemContext(ctx, input) {
+    if (!this.opts.systemContext) return void 0;
+    try {
+      const s = await this.opts.systemContext(ctx, input);
+      return s && s.trim() ? s : void 0;
+    } catch (err) {
+      console.error(`[@nightowlsdev/engine-ai-sdk] systemContext threw for run ${ctx.runId} \u2014 skipping the block:`, err);
+      return void 0;
+    }
+  }
+  /** FR-027 — resolve the host's opt-in per-request instruction-only (dynamic/imported) skills, by name.
+   *  FAIL-SAFE: a throwing/rejecting resolver yields no dynamic skills (never breaks the run). No memoization —
+   *  v1 has no delegation, so there is only ever ONE resolution per segment (no sub-agent to share it with);
+   *  re-resolved fresh on every `resume()` segment too (never carried over the suspend boundary). */
+  async safeDynamicSkills(ctx) {
+    if (!this.opts.dynamicSkills) return {};
+    try {
+      const skills = await this.opts.dynamicSkills(ctx);
+      const out = {};
+      for (const s of skills) out[s.name] = s;
+      return out;
+    } catch (err) {
+      console.error(`[@nightowlsdev/engine-ai-sdk] dynamicSkills threw for run ${ctx.runId} \u2014 skipping:`, err);
+      return {};
+    }
+  }
+  /**
+   * Resolve the CONCRETE model instance for one generation launch: tier routing (a sentinel `modelId` routes to
+   * the configured tier; a concrete pin passes verbatim), THEN the allow-list `opts.model.resolve` (a deny
+   * throws — this is the security-critical re-validation the plan calls out: EVERY resolved id, tier-routed or
+   * not, goes through the allow-list, never just the stored one), THEN `opts.modelFactory`. Mirrors the
+   * reference engine's private `modelFor` (`packages/core/src/mastra-map.ts:284-292`). Called once for the
+   * `streamText` call's outer `model` field AND again from `prepareStep` for EVERY step (including the first) —
+   * so a revoked/rotated allow-list entry is caught mid-run, not just at the top of the segment.
+   */
+  async resolveModel(row, ctx) {
+    const effective = (0, import_core4.tierModelId)(row.modelId ?? "unknown", this.opts.tier, {
+      tenantId: ctx.tenantId,
+      agentSlug: ctx.agentSlug,
+      pinnedModelId: row.modelId ?? "unknown"
+    });
+    const resolvedId = await this.opts.model.resolve(effective, { tenantId: ctx.tenantId });
+    return this.opts.modelFactory(resolvedId, ctx.agentSlug);
+  }
+  /** Build this segment's `ToolAssemblyOpts` — identical wiring for `run()` and `resume()` (both rebuild tools
+   *  fresh from the CURRENT agent row; only `runCtx` differs). */
+  toolAssemblyOpts() {
+    return {
+      resolveSkill: this.opts.resolveSkill,
+      connectorTools: this.opts.connectorTools,
+      secrets: this.opts.secrets,
+      scratchpad: this.opts.scratchpad,
+      scratchpadStore: this.opts.storage.scratchpad,
+      recallLane: this.opts.recallLane,
+      pageContext: this.opts.pageContext,
+      gate: (event) => this.hooks.preToolCall(event)
+    };
+  }
+  /**
+   * The shared governed `streamText` drive — Task 6's loop, generalized so both `run()` (segmentIndex 0) and
+   * `resume()` (segmentIndex = the snapshot's genIndex) call the SAME implementation: per-step metering + cost
+   * caps, mid-stream cancellation, suspend-parking (ask / native tool approvals / client actions), and
+   * completion-supervisor nudging. Returns the segment's terminal outcome as the generator's return value (the
+   * caller captures it via `const outcome = yield* this.drive(...)`); every terminal event (`done`/`run_failed`/
+   * `run_cancelled`/the park's `waiting`+`question`/`client_action`) is yielded from INSIDE this loop — the
+   * caller only needs the returned outcome for its own `onRunEnd` reporting.
+   */
+  async *drive(d) {
+    const { ctx, ev, emit, emitTurnUsage, segmentIndex, row, modelId, tools, systemMessages, gov, collector, signal, turnUsage, runState, requestText } = d;
+    let messages = d.initialMessages;
+    let continueNudges = 0;
+    const maxContinueNudges = Math.max(0, Math.floor(this.opts.maxContinueNudges ?? 2));
+    let transcript = "";
+    let incompleteMissing = null;
+    try {
+      for (; ; ) {
+        if (signal?.aborted) {
+          yield* finishCancelledSeg(d);
+          return "cancelled";
+        }
+        const initialModel = await this.resolveModel(row, ctx);
+        const remainingSteps = Math.max(1, this.opts.cost.maxSteps - turnUsage.length);
+        const result = (0, import_ai2.streamText)({
+          model: initialModel,
+          system: systemMessages,
+          messages,
+          tools,
+          stopWhen: (0, import_ai2.stepCountIs)(remainingSteps),
+          prepareStep: async () => ({ model: await this.resolveModel(row, ctx) }),
+          maxRetries: 0,
+          // E11 — no engine-level retries; the durable backend owns retries.
+          ...signal ? { abortSignal: signal } : {}
+        });
+        const pendingToolCalls = /* @__PURE__ */ new Map();
+        let parkedApproval = null;
+        for await (const part of result.fullStream) {
+          if (signal?.aborted) {
+            yield* finishCancelledSeg(d);
+            return "cancelled";
+          }
+          for (const mapped of mapChunks(part, { agentSlug: ctx.agentSlug, gatesApproval: (name) => this.gatesApproval(name) })) {
+            if (mapped.kind === "event") {
+              switch (mapped.type) {
+                case "swarm.message":
+                  collector?.openGeneration(modelId);
+                  if (this.opts.verifyCompletion) transcript = appendTranscript(transcript, mapped.data.delta ?? "");
+                  break;
+                case "swarm.tool_call":
+                  collector?.openGeneration(modelId);
+                  collector?.openTool(mapped.data.toolCallId, mapped.data.name);
+                  pendingToolCalls.set(mapped.data.toolCallId, { name: mapped.data.name, input: mapped.data.args });
+                  if (this.opts.verifyCompletion) {
+                    transcript = appendTranscript(transcript, `
+\xAB${ctx.agentSlug} \u2192 ${mapped.data.name}\xBB
+`);
+                  }
+                  break;
+                case "swarm.tool_result":
+                  collector?.closeTool(mapped.data.toolCallId, mapped.data.ok);
+                  pendingToolCalls.delete(mapped.data.toolCallId);
+                  break;
+              }
+              yield await emit(ev(mapped.type, mapped.data));
+              continue;
+            }
+            switch (mapped.kind) {
+              case "park":
+                parkedApproval = {
+                  approvalId: mapped.approvalId,
+                  toolCallId: mapped.toolCallId,
+                  toolName: mapped.toolName,
+                  input: mapped.input
+                };
+                break;
+              case "step-usage": {
+                gov.step();
+                const u = extractUsage(mapped.usage);
+                collector?.openGeneration(modelId);
+                collector?.closeGeneration(u, gov.priceOf(modelId, u));
+                gov.addUsage(modelId, u);
+                const cost = gov.costOf(modelId, u);
+                const generationId = `${ctx.runId}:${segmentIndex}:${turnUsage.length}`;
+                turnUsage.push({ slug: ctx.agentSlug, breakdown: u, cost });
+                yield await emit(ev("swarm.usage", { slug: ctx.agentSlug, modelId, breakdown: u, cost, generationId }));
+                break;
+              }
+              case "cancel":
+                yield* finishCancelledSeg(d);
+                return "cancelled";
+              case "failure":
+                yield* finishFailedSeg(d, "model", errorMessage(mapped.error), false);
+                return "failed";
+            }
+          }
+          const stop = gov.shouldStop();
+          if (stop.stop) {
+            yield* finishFailedSeg(d, "cost", stop.reason ?? "cost cap reached", false);
+            return "failed";
+          }
+        }
+        if (signal?.aborted) {
+          yield* finishCancelledSeg(d);
+          return "cancelled";
+        }
+        if (parkedApproval || pendingToolCalls.size > 0) {
+          let parkKind;
+          let toolCallId;
+          let toolName;
+          let toolInput;
+          let approvalId;
+          if (parkedApproval) {
+            ({ approvalId, toolCallId, toolName, input: toolInput } = parkedApproval);
+            parkKind = "approval";
+          } else {
+            const [id, info] = [...pendingToolCalls.entries()][0];
+            toolCallId = id;
+            toolName = info.name;
+            toolInput = info.input;
+            parkKind = toolName === import_core4.ASK_TOOL_NAME ? "ask" : "client";
+          }
+          const responseMessages = (await result.response).messages;
+          const snapshotMessages = [...messages, ...responseMessages];
+          const followupId = `${ctx.runId}:${toolCallId}`;
+          const genIndex = segmentIndex + 1;
+          const snapshot = {
+            v: 1,
+            kind: parkKind,
+            messages: snapshotMessages,
+            genIndex,
+            toolCallId,
+            toolName,
+            state: runState.entries(),
+            ...approvalId ? { approvalId } : {}
+          };
+          await recordSuspendSafe(this.opts.storage, ctx, followupId, toolCallId);
+          await d.runsStore.setStatus(ctx.runId, "suspended");
+          await d.runsStore.saveSnapshot(ctx.runId, snapshot);
+          if (signal?.aborted) {
+            yield* finishCancelledSeg(d);
+            return "cancelled";
+          }
+          const t = await emitTurnUsage(segmentIndex);
+          if (t) yield t;
+          yield await emit(ev("swarm.status", { state: "waiting" }));
+          if (parkKind === "client") {
+            const needsApproval = clientNeedsApprovalOf(tools[toolName]);
+            yield await emit(
+              ev("swarm.client_action", {
+                followupId,
+                toolCallId,
+                tool: toolName,
+                input: toolInput,
+                needsApproval,
+                from: ctx.agentSlug
+              })
+            );
+          } else if (parkKind === "approval") {
+            yield await emit(
+              ev("swarm.question", {
+                followupId,
+                toolCallId,
+                to: "user",
+                from: ctx.agentSlug,
+                prompt: `Approve running \`${toolName}\`? args: ${JSON.stringify(toolInput)}`,
+                field: { kind: "confirm", confirmLabel: "Approve", rejectLabel: "Reject" }
+              })
+            );
+          } else {
+            const askInput = toolInput ?? {};
+            yield await emit(
+              ev("swarm.question", {
+                followupId,
+                toolCallId,
+                to: askInput.to ?? "user",
+                from: ctx.agentSlug,
+                prompt: askInput.prompt ?? "",
+                field: askInput.field
+              })
+            );
+          }
+          return "suspended";
+        }
+        if (this.opts.verifyCompletion) {
+          const verdict = await this.safeVerify(requestText, transcript, ctx);
+          if (!verdict.complete && continueNudges < maxContinueNudges) {
+            continueNudges++;
+            messages = [...messages, ...(await result.response).messages, { role: "user", content: verifyNudge(verdict.missing) }];
+            continue;
+          }
+          incompleteMissing = verdict.complete ? null : verdict.missing ?? "The task was not completed.";
+        }
+        break;
+      }
+    } catch (err) {
+      if (signal?.aborted || isAbortLike(err)) {
+        yield* finishCancelledSeg(d);
+        return "cancelled";
+      }
+      yield* finishFailedSeg(d, "model", errorMessage(err), false);
+      return "failed";
+    }
+    if (incompleteMissing != null) {
+      yield* finishFailedSeg(d, "incomplete", incompleteMissing, true);
+      return "failed";
+    }
+    yield* finishDoneSeg(d);
+    return "done";
+  }
+  async *run(input, ctx, signal) {
+    const row = await this.opts.storage.agents.head(ctx.tenantId, ctx.agentSlug);
+    if (!row) throw new Error(`unknown agent: ${ctx.agentSlug}`);
+    const modelId = (0, import_core4.tierModelId)(row.modelId ?? "unknown", this.opts.tier, {
+      tenantId: ctx.tenantId,
+      agentSlug: ctx.agentSlug,
+      pinnedModelId: row.modelId ?? "unknown"
+    });
+    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,
+      userId: ctx.userId,
+      threadId: ctx.threadId,
+      agentSlug: ctx.agentSlug
+    });
+    const runsStore = this.opts.storage.runs;
+    const { ev, emit } = makeEmitter({ storage: this.opts.storage, onEvent: this.opts.onEvent, ctx });
+    const turnUsage = [];
+    let turnEmitted = false;
+    const emitTurnUsage = async (segmentIndex) => {
+      if (turnEmitted) return null;
+      turnEmitted = true;
+      const total = (0, import_core4.sumTurnUsage)(turnUsage);
+      return emit(
+        ev("swarm.turn_usage", {
+          breakdown: total.breakdown,
+          cost: total.cost,
+          bySlug: total.bySlug,
+          generations: turnUsage.length,
+          segmentIndex
+        })
+      );
+    };
+    const collector = this.telemetry ? new import_core4.SpanCollector(ctx.runId, () => Date.now(), "run", { agentSlug: ctx.agentSlug }) : null;
+    const runState = (0, import_core4.createRunState)();
+    let outcome = "failed";
+    if (this.opts.onRunStart) {
+      try {
+        await this.opts.onRunStart(ctx, { input, state: runState });
+      } catch (err) {
+        console.error(`[@nightowlsdev/engine-ai-sdk] onRunStart threw for run ${ctx.runId}:`, err);
+      }
+    }
+    const io = { ctx, runsStore, ev, emit, emitTurnUsage, segmentIndex: 0 };
+    const floorKey = ctx.threadId;
+    const me = { label: titleCase(ctx.agentSlug), runId: ctx.runId };
+    const floorAbort = new AbortController();
+    let releaseFloor = await this.floor.tryAcquire(floorKey, me);
+    try {
+      if (!releaseFloor) {
+        const held = await this.floor.holder(floorKey);
+        const position = await this.floor.queueDepth(floorKey) + 1;
+        yield await emit(ev("swarm.status", { state: "blocked", note: held?.label ?? "another agent", position }));
+        releaseFloor = await this.floor.acquire(floorKey, me, floorAbort.signal);
+        if (floorAbort.signal.aborted) return;
+      }
+      if (signal?.aborted) {
+        yield* finishCancelledSeg(io);
+        outcome = "cancelled";
+        return;
+      }
+      yield await emit(ev("swarm.status", { state: "thinking" }));
+      try {
+        await this.guardGeneration({
+          runId: ctx.runId,
+          tenantId: ctx.tenantId,
+          agentSlug: ctx.agentSlug,
+          modelId,
+          generationIndex: 0,
+          kind: "run"
+        });
+      } catch (err) {
+        const stage = err instanceof import_core4.ReserveDenied ? "reserve" : "exception";
+        yield* finishFailedSeg(io, stage, errorMessage(err), false);
+        outcome = "failed";
+        return;
+      }
+      const priorHistory = await this.history(ctx.threadId, ctx);
+      const userMessage = input.message.replace(/^(\[user:[^\]]*\]\s*)+/, "");
+      await emit(ev("swarm.message", { role: "user", text: userMessage }));
+      const approvedToolCallIds = /* @__PURE__ */ new Set();
+      const runToolCtx = {
+        ctx,
+        state: runState,
+        approvedToolCallIds,
+        pageContextValue: input.context,
+        // T9: the real events-derived `history()` — `recall_lane` now returns a real peer-lane transcript.
+        history: (threadId, histCtx, historyOpts) => this.history(threadId, histCtx, historyOpts)
+      };
+      const tools = await buildTools({ row, opts: this.toolAssemblyOpts(), runCtx: runToolCtx });
+      const dynamicSkillsResolved = await this.safeDynamicSkills(ctx);
+      const systemMessages = await buildSystemMessages({
+        row,
+        opts: {
+          resolveSkill: this.opts.resolveSkill ?? (() => void 0),
+          softPolicy: this.opts.softPolicy,
+          scratchpad: !!this.opts.scratchpad,
+          loadScratchpad: this.opts.storage.scratchpad ? (container, tenantId) => this.opts.storage.scratchpad.list(tenantId, container) : void 0
+        },
+        ctx: { tenantId: ctx.tenantId, threadId: ctx.threadId },
+        dynamicSkillsResolved,
+        systemContextText: await this.safeSystemContext(ctx, input)
+      });
+      const gov = new import_core4.CostGovernor(this.opts.cost);
+      const historyMessages = priorHistory.slice(-HISTORY_PROMPT_CAP).map((m) => m.role === "user" ? { role: "user", content: m.text } : { role: "assistant", content: m.text });
+      const messages = [...historyMessages, { role: "user", content: userMessage }];
+      const result = yield* this.drive({
+        ...io,
+        row,
+        modelId,
+        tools,
+        systemMessages,
+        initialMessages: messages,
+        gov,
+        collector,
+        signal,
+        turnUsage,
+        runState,
+        requestText: userMessage
+      });
+      outcome = result;
+    } finally {
+      if (this.opts.onRunEnd) {
+        try {
+          await this.opts.onRunEnd(ctx, { state: runState, outcome });
+        } catch (err) {
+          console.error(`[@nightowlsdev/engine-ai-sdk] onRunEnd threw for run ${ctx.runId}:`, err);
+        }
+      }
+      floorAbort.abort();
+      await releaseFloor?.();
+      if (this.telemetry && collector) {
+        const spans = collector.finish();
+        try {
+          await this.telemetry.export(spans);
+        } catch {
+        }
+      }
+    }
+  }
+  /**
+   * Resume a parked run: `markFollowupAnswered` EARLY (CAS, replay-safe) → `loadSnapshot` → reload the agent
+   * row fresh (same as `run()`) → re-acquire the floor → emit `swarm.answer` → preGeneration re-fire (kind
+   * 'resume', at the snapshot's genIndex) → per-kind append the answer to the snapshot's messages → re-enter
+   * the SHARED `drive()` with rebuilt tools (`approvedToolCallIds` pre-populated on an approval-approve, BEFORE
+   * `buildTools`/`streamText` — Task 4's blocker-fix contract) + restored messages. A re-park persists
+   * `genIndex = (this segment's own segmentIndex) + 1` — the same bookkeeping `drive()` already does for
+   * `run()`'s park, generalized.
+   *
+   * ⚠ `onRunStart` deliberately does NOT fire here — this is a CONTINUATION of the run `onRunStart` already
+   * announced (in `run()`), not a new one. Mirrors the reference (Mastra) engine exactly: `packages/core/src/
+   * engine.ts`'s own `resume()` never calls `this.opts.onRunStart` either (only `run()` does — see that file's
+   * `onRunStart` doc comment: "fires on `run()` only"). A host that seeds per-run state in `onRunStart` gets it
+   * back via `snap.state` → `resumedState` below, so nothing is lost across the suspend/resume boundary.
+   */
+  async *resume(args, ctx, signal) {
+    const rctx = { ...ctx, runId: args.runId };
+    const runsStore = this.opts.storage.runs;
+    const { ev, emit } = makeEmitter({ storage: this.opts.storage, onEvent: this.opts.onEvent, ctx: rctx, startTs: 1e3 });
+    const snap = await runsStore.loadSnapshot(rctx.tenantId, args.runId);
+    if (!snap) {
+      yield await emit(ev("swarm.run_failed", { stage: "resume", message: `no suspended run: ${args.runId}`, retryable: false }));
+      return;
+    }
+    if (!isValidAiSdkSnapshot(snap)) {
+      yield await emit(
+        ev("swarm.run_failed", { stage: "resume", message: "incompatible or corrupt snapshot", retryable: false })
+      );
+      return;
+    }
+    const resumedState = (0, import_core4.createRunState)(snap.state ?? void 0);
+    const generationIndex = typeof snap.genIndex === "number" ? snap.genIndex : 1;
+    const answered = await this.opts.storage.markFollowupAnswered?.(args.followupId, rctx.tenantId);
+    if (this.opts.storage.markFollowupAnswered && answered === false) {
+      yield await emit(
+        ev("swarm.run_failed", { stage: "resume", message: `followup already answered: ${args.followupId}`, retryable: false })
+      );
+      return;
+    }
+    await runsStore.setStatus(args.runId, "running");
+    const row = await this.opts.storage.agents.head(rctx.tenantId, rctx.agentSlug);
+    if (!row) {
+      try {
+        await runsStore.setStatus(args.runId, "failed");
+      } catch {
+      }
+      yield await emit(ev("swarm.run_failed", { stage: "resume", message: `unknown agent: ${rctx.agentSlug}`, retryable: false }));
+      return;
+    }
+    const modelId = (0, import_core4.tierModelId)(row.modelId ?? "unknown", this.opts.tier, {
+      tenantId: rctx.tenantId,
+      agentSlug: rctx.agentSlug,
+      pinnedModelId: row.modelId ?? "unknown"
+    });
+    const turnUsage = [];
+    let turnEmitted = false;
+    const emitTurnUsage = async (segmentIndex) => {
+      if (turnEmitted) return null;
+      turnEmitted = true;
+      const total = (0, import_core4.sumTurnUsage)(turnUsage);
+      return emit(
+        ev("swarm.turn_usage", {
+          breakdown: total.breakdown,
+          cost: total.cost,
+          bySlug: total.bySlug,
+          generations: turnUsage.length,
+          segmentIndex
+        })
+      );
+    };
+    const collector = this.telemetry ? new import_core4.SpanCollector(args.runId, () => Date.now(), "resume", { agentSlug: rctx.agentSlug }) : null;
+    let outcome = "failed";
+    const io = { ctx: rctx, runsStore, ev, emit, emitTurnUsage, segmentIndex: generationIndex };
+    const floorKey = rctx.threadId;
+    const me = { label: titleCase(rctx.agentSlug), runId: args.runId };
+    const floorAbort = new AbortController();
+    let releaseFloor = await this.floor.tryAcquire(floorKey, me);
+    try {
+      if (!releaseFloor) {
+        const held = await this.floor.holder(floorKey);
+        const position = await this.floor.queueDepth(floorKey) + 1;
+        yield await emit(ev("swarm.status", { state: "blocked", note: held?.label ?? "another agent", position }));
+        releaseFloor = await this.floor.acquire(floorKey, me, floorAbort.signal);
+        if (floorAbort.signal.aborted) return;
+      }
+      if (signal?.aborted) {
+        yield* finishCancelledSeg(io);
+        outcome = "cancelled";
+        return;
+      }
+      yield await emit(ev("swarm.answer", { followupId: args.followupId, from: "user", answer: args.answer }));
+      try {
+        await this.guardGeneration({ runId: args.runId, tenantId: rctx.tenantId, agentSlug: rctx.agentSlug, modelId, generationIndex, kind: "resume" });
+      } catch (err) {
+        const stage = err instanceof import_core4.ReserveDenied ? "reserve" : "exception";
+        yield* finishFailedSeg(io, stage, errorMessage(err), false);
+        outcome = "failed";
+        return;
+      }
+      yield await emit(ev("swarm.status", { state: "thinking" }));
+      const approvedToolCallIds = /* @__PURE__ */ new Set();
+      let messages = [...snap.messages];
+      if (snap.kind === "ask") {
+        const toolResult = {
+          type: "tool-result",
+          toolCallId: snap.toolCallId,
+          toolName: snap.toolName,
+          output: { type: "json", value: { answer: args.answer } }
+        };
+        const toolMessage = { role: "tool", content: [toolResult] };
+        messages = [...messages, toolMessage];
+      } else if (snap.kind === "approval") {
+        const approved = (0, import_engine_spi2.isApproved)(args.answer);
+        if (approved) approvedToolCallIds.add(snap.toolCallId);
+        const approvalResponse = { type: "tool-approval-response", approvalId: snap.approvalId ?? "", approved };
+        const toolMessage = { role: "tool", content: [approvalResponse] };
+        messages = [...messages, toolMessage];
+      } else {
+        const clientAnswer = args.answer;
+        const isError = !!(clientAnswer && typeof clientAnswer === "object" && "error" in clientAnswer && clientAnswer.error);
+        const outputValue = !isError && clientAnswer && typeof clientAnswer === "object" && "output" in clientAnswer ? clientAnswer.output : clientAnswer;
+        const output = isError ? { type: "error-text", value: String(clientAnswer.error) } : { type: "json", value: outputValue };
+        const toolResult = { type: "tool-result", toolCallId: snap.toolCallId, toolName: snap.toolName, output };
+        const toolMessage = { role: "tool", content: [toolResult] };
+        messages = [...messages, toolMessage];
+      }
+      const runToolCtx = {
+        ctx: rctx,
+        state: resumedState,
+        approvedToolCallIds,
+        pageContextValue: args.context,
+        // R6: re-attach the host's (possibly refreshed) page context on resume.
+        // T9: wired to the real events-derived `history()` (same binding as run()).
+        history: (threadId, histCtx, historyOpts) => this.history(threadId, histCtx, historyOpts)
+      };
+      const tools = await buildTools({ row, opts: this.toolAssemblyOpts(), runCtx: runToolCtx });
+      const dynamicSkillsResolved = await this.safeDynamicSkills(rctx);
+      const systemMessages = await buildSystemMessages({
+        row,
+        opts: {
+          resolveSkill: this.opts.resolveSkill ?? (() => void 0),
+          softPolicy: this.opts.softPolicy,
+          scratchpad: !!this.opts.scratchpad,
+          loadScratchpad: this.opts.storage.scratchpad ? (container, tenantId) => this.opts.storage.scratchpad.list(tenantId, container) : void 0
+        },
+        ctx: { tenantId: rctx.tenantId, threadId: rctx.threadId },
+        dynamicSkillsResolved,
+        // FR-024 gotcha: systemContext is NEVER re-resolved on resume (only run() sets it) — mirrors the
+        // reference engine's own resume rc, which never attaches SYSTEM_CONTEXT_KEY.
+        systemContextText: void 0
+      });
+      const gov = new import_core4.CostGovernor(this.opts.cost);
+      const requestText = await this.recallRequest(rctx);
+      const result = yield* this.drive({
+        ...io,
+        row,
+        modelId,
+        tools,
+        systemMessages,
+        initialMessages: messages,
+        gov,
+        collector,
+        signal,
+        turnUsage,
+        runState: resumedState,
+        requestText
+      });
+      outcome = result;
+    } finally {
+      if (this.opts.onRunEnd) {
+        try {
+          await this.opts.onRunEnd(rctx, { state: resumedState, outcome });
+        } catch (err) {
+          console.error(`[@nightowlsdev/engine-ai-sdk] onRunEnd threw for resume ${args.runId}:`, err);
+        }
+      }
+      floorAbort.abort();
+      await releaseFloor?.();
+      if (this.telemetry && collector) {
+        const spans = collector.finish();
+        try {
+          await this.telemetry.export(spans);
+        } catch {
+        }
+      }
+    }
+  }
+  /**
+   * T9 — events-derived thread history (no Mastra memory in this engine: the events log IS the store).
+   * `container(threadId)` resolves the root container; `events.listForContainer` (optional on `StorageAdapter`
+   * — absent ⇒ `[]`, matching the reference's "no memory ⇒ []" degradation) returns the FULL container log
+   * (root + any lane sub-threads), each event tagged with its OWN run's `threadId`. Filtered LANE-EXACT to the
+   * REQUESTED `threadId` (so a root read never leaks a lane's side-chat and vice versa), then folded into
+   * `SwarmMessage[]` by `messagesFromEvents` (structural attribution; decode-only legacy prefix stripping — see
+   * its doc comment). Hard-capped to the most recent `limit` (default 200, mirrors the reference).
+   */
+  async history(threadId, ctx, opts) {
+    const limit = opts?.limit ?? 200;
+    const container = containerOf(threadId);
+    const events = await this.opts.storage.events.listForContainer?.(ctx.tenantId, container) ?? [];
+    const laneEvents = events.filter((e) => e.threadId === threadId);
+    const mapped = messagesFromEvents(threadId, laneEvents);
+    return mapped.length > limit ? mapped.slice(-limit) : mapped;
+  }
+  /** T9 helper — one container's `ThreadSummary`: title = its first (oldest) user message's text, falling back
+   *  to the bare container id (an empty/title-less container, matching the reference's "no Mastra row" fallback
+   *  shape: `{ threadId: container, title: container, lastActivityAt: 0 }`). `lastActivityAt` = the max `seq`
+   *  seen on the container's BARE (non-lane) events (T9-review fix): `seq` is the storage-assigned, GLOBALLY
+   *  monotonic append counter, so a newer run's events always rank above an older run's — whereas `ts` is a
+   *  per-segment ordinal (restarts at 0/1000 every segment, see `emit.ts`) and is meaningless across runs. Same
+   *  seq-over-ts preference the react timeline established (react/timeline.ts). NOT a wall-clock epoch (no
+   *  adapter in the `StorageAdapter` contract exposes one for runs/events) — a recency-ORDERING proxy only.
+   */
+  async threadSummaryFor(container, ctx) {
+    const events = await this.opts.storage.events.listForContainer?.(ctx.tenantId, container) ?? [];
+    const bare = events.filter((e) => e.threadId === container);
+    if (bare.length === 0) return { threadId: container, title: container, lastActivityAt: 0 };
+    const firstUser = bare.find(
+      (e) => e.type === "swarm.message" && e.data.role === "user"
+    );
+    const title = (firstUser?.data.text ?? "").trim() || container;
+    const lastActivityAt = Math.max(...bare.map((e) => e.seq ?? 0));
+    return { threadId: container, title, lastActivityAt };
+  }
+  /**
+   * T9 — R14 participation-based thread listing (mirrors the reference `listThreads`, minus the Mastra memory
+   * dependency): `runs.listUserContainers` (optional) gives the containers this user has a run in,
+   * newest-active first; each is summarized via `threadSummaryFor` (concurrently, order preserved).
+   * FALLBACK (an adapter without `listUserContainers`): the reference degrades to the CURRENT container under
+   * multi-user (no cross-container Mastra listing to fall back on here either) — a single-entry list for
+   * `ctx.threadId`'s own container.
+   */
+  async listThreads(ctx, opts) {
+    const limit = opts?.limit ?? 50;
+    const lister = this.opts.storage.runs.listUserContainers;
+    if (lister) {
+      const containers = await lister.call(this.opts.storage.runs, ctx.tenantId, ctx.userId, limit);
+      const out = await Promise.all(containers.map((c) => this.threadSummaryFor(c, ctx)));
+      return out.slice(0, limit);
+    }
+    const container = containerOf(ctx.threadId);
+    return [await this.threadSummaryFor(container, ctx)];
+  }
+  /** The PUBLIC entries of a conversation's scratchpad (empty array when the feature is off or unset).
+   *  Mirrors the reference engine's `scratchpadPublic` verbatim (storage-backed, engine-neutral). */
+  async scratchpadPublic(container, ctx) {
+    const all = await this.opts.storage.scratchpad?.list(ctx.tenantId, container) ?? [];
+    return all.filter((e) => e.section === "public");
+  }
+  /** In-flight runs (running|suspended) for a container + its lanes. Mirrors the reference engine's
+   *  `activeRuns` verbatim (storage-backed, engine-neutral). */
+  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) — unlike
+   *  `history()`, NOT lane-filtered: this is the rich raw timeline (tool calls + status, not just messages).
+   *  Mirrors the reference engine's `threadEvents` verbatim (storage-backed, engine-neutral). Returns `[]` when
+   *  the store has no `events.listForContainer`. */
+  async threadEvents(threadId, ctx) {
+    const container = containerOf(threadId);
+    return await this.opts.storage.events.listForContainer?.(ctx.tenantId, container) ?? [];
+  }
+  /**
+   * T9 (REQUIRED on `Engine`) — the tenant's agent roster as wall-safe `AgentSummary[]`: `agents.listSlugs` →
+   * `head` per slug (dropping any slug whose head resolves to `null`, a race with a mid-listing deletion).
+   * `delegateSlugs` is ALWAYS `[]` — a deliberate divergence from the reference engine (which surfaces the
+   * stored `AgentVersion.delegateSlugs`): this engine's `capabilities.delegation` is `false` (v1, single-agent),
+   * so there is no addressable delegate graph to report regardless of what a row happens to store.
+   */
+  async listAgents(ctx) {
+    const slugs = await this.opts.storage.agents.listSlugs(ctx.tenantId);
+    const rows = await Promise.all(slugs.map((s) => this.opts.storage.agents.head(ctx.tenantId, s)));
+    return rows.filter((r) => !!r).map((r) => ({ slug: r.slug, name: titleCase(r.slug), role: r.role, delegateSlugs: [] }));
+  }
+};
+
+// src/index.ts
+function aiSdkEngine({ durable = false } = {}) {
+  return (opts) => new AiSdkEngine(opts, { durable });
+}
+var nightOwlsPlugin = {
+  name: "engine-ai-sdk",
+  version: "0.0.0",
+  kind: "engine",
+  pkg: "@nightowlsdev/engine-ai-sdk",
+  description: "The AI-SDK-native engine as a named engine package (single-agent v1, governed ai@6 streamText loop).",
+  env: [],
+  config: {
+    import: `import { aiSdkEngine } from "@nightowlsdev/engine-ai-sdk";`,
+    snippet: `engine = aiSdkEngine();`,
+    marker: "engine"
+  },
+  // Print-only (idempotent) — runs on init/install + `owl init engine-ai-sdk`. NEVER connects anywhere.
+  init: (ctx) => ctx.log("engine-ai-sdk wired \u2014 defineSwarm({ engine: aiSdkEngine() })."),
+  commands: []
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AI_SDK_ENGINE_CAPABILITIES,
+  AiSdkEngine,
+  aiSdkEngine,
+  nightOwlsPlugin
+});