@nightowlsdev/core 0.3.0

package/dist/index.js

@@ -0,0 +1,1534 @@
+// src/types.ts
+var SCRATCHPAD_MAX_ENTRY_CHARS = 4e3;
+var SCRATCHPAD_MAX_KEYS = 64;
+
+// src/events.ts
+function ev(type, base2, data) {
+  return { type, schemaVersion: 1, ...base2, data };
+}
+function isEvent(e, type) {
+  return e.type === type;
+}
+
+// src/define.ts
+import { z as z4 } from "zod";
+import { createTool as createTool4 } from "@mastra/core/tools";
+
+// src/engine.ts
+import { Mastra } from "@mastra/core/mastra";
+import { InMemoryStore } from "@mastra/core/storage";
+import { RequestContext } from "@mastra/core/request-context";
+
+// src/mastra-map.ts
+import { Agent } from "@mastra/core/agent";
+
+// src/prompt.ts
+var GUARDRAILS = [
+  "You are honest and proactive. Never invent facts or tool results.",
+  "Stay strictly focused on the task you were given; do not expand scope.",
+  "If you are blocked or missing information, ASK a follow-up question (to the user or another agent) using the `ask` tool rather than guessing."
+].join(" ");
+function composeSystemPrompt(row) {
+  const persona = [
+    `You are the "${row.slug}" agent.`,
+    `Personality: ${row.personality}.`,
+    row.capabilities.length ? `You are allowed to: ${row.capabilities.join("; ")}.` : "",
+    row.skillNames.length ? `Tools you may invoke: ${row.skillNames.join(", ")}.` : "",
+    row.delegateSlugs.length ? `You may delegate to: ${row.delegateSlugs.join(", ")}.` : ""
+  ].filter(Boolean).join("\n");
+  return [
+    { role: "system", content: GUARDRAILS },
+    { role: "system", content: persona }
+  ];
+}
+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}`);
+    return rows.length ? rows.join("\n") : "(none)";
+  };
+  const content = [
+    "Shared scratchpad for THIS conversation (visible to every agent here). Record important facts PROACTIVELY via `scratchpad_write` under a short KEY; reuse a key to revise that fact. public = shown to the user, meta = internal to agents.",
+    `## Public (also shown to the user)
+${render("public")}`,
+    `## Meta (internal to agents)
+${render("meta")}`
+  ].join("\n\n");
+  return { role: "system", content };
+}
+
+// src/mastra-map.ts
+var MAX_DELEGATION_DEPTH = 4;
+function memoryFor(args, row) {
+  return args.resolveMemory ? args.resolveMemory(row) : args.memory;
+}
+function toolsFor(args, row) {
+  const out = { ...args.builtinTools ?? {} };
+  for (const name of row.skillNames) {
+    const skill = args.resolveSkill(name);
+    const mt = skill && __getMastraTool(skill);
+    if (mt) out[name] = mt;
+  }
+  return out;
+}
+async function withScratchpad(args, base2, rc) {
+  if (!args.loadScratchpad) return base2;
+  const tenantId = rc.get("tenantId") ?? "default";
+  const container = (rc.get("threadId") ?? "").split(":")[0] ?? "";
+  const entries = await args.loadScratchpad(container, tenantId);
+  return [...base2, composeScratchpadPrompt(entries)];
+}
+async function modelFor(args, row, tenantId) {
+  const id = await args.model.resolve(row.modelId, { tenantId });
+  return args.modelFactory(id, row.slug);
+}
+function buildSubAgent(args, row, depth, path) {
+  const nextPath = [...path, row.slug];
+  return new Agent({
+    id: `swarm-sub-${row.slug}`,
+    name: row.slug,
+    // Model-facing tool description for the `agent-<slug>` delegation tool — use the agent's own
+    // 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),
+    model: async ({ requestContext }) => await modelFor(args, row, requestContext.get("tenantId") ?? "default"),
+    tools: toolsFor(args, row),
+    agents: async ({ requestContext }) => await buildSubAgentMap(
+      args,
+      row.delegateSlugs ?? [],
+      depth + 1,
+      nextPath,
+      requestContext.get("tenantId") ?? "default"
+    )
+  });
+}
+async function buildSubAgentMap(args, slugs, depth, path, tenantId) {
+  if (depth > MAX_DELEGATION_DEPTH || slugs.length === 0) return {};
+  const out = {};
+  for (const slug of slugs) {
+    if (path.includes(slug)) continue;
+    const row = await args.loadRow(slug, tenantId);
+    out[slug] = buildSubAgent(args, row, depth, path);
+  }
+  return out;
+}
+function buildMastraAgent(args) {
+  const load = (rc) => args.loadRow(rc.get("agentSlug") ?? "", rc.get("tenantId") ?? "default");
+  return new Agent({
+    id: "swarm-agent",
+    name: "Swarm Agent",
+    // R9: try a DYNAMIC memory fn so the root agent honors a per-agent override too (its row is loaded per
+    // 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),
+    model: async ({ requestContext }) => await modelFor(args, await load(requestContext), requestContext.get("tenantId") ?? "default"),
+    tools: async ({ requestContext }) => ({ ...args.extraTools ?? {}, ...toolsFor(args, await load(requestContext)) }),
+    // Delegation: the orchestrator's delegateSlugs become `agent-<slug>` tools (Mastra-native).
+    agents: async ({ requestContext }) => {
+      const row = await load(requestContext);
+      const tenantId = requestContext.get("tenantId") ?? "default";
+      return await buildSubAgentMap(args, row.delegateSlugs ?? [], 1, [row.slug], tenantId);
+    }
+  });
+}
+
+// src/page-context-tool.ts
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+// src/page-context.ts
+var PAGE_CONTEXT_KEY = "nightowls.pageContext";
+function attachPageContext(rc, value) {
+  rc.set(PAGE_CONTEXT_KEY, value ?? {});
+}
+function readPageContext(rc) {
+  return rc?.get?.(PAGE_CONTEXT_KEY) ?? {};
+}
+
+// src/page-context-tool.ts
+function buildPageContextTool() {
+  return createTool({
+    id: "get_page_context",
+    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: z.object({}),
+    // Mastra 1.38: execute is (inputData, context); requestContext is on the 2nd arg (spike-verified).
+    // Annotated optional to match Mastra's ToolExecutionContext, where requestContext is `RequestContext | undefined`.
+    execute: async (_input, { requestContext }) => ({
+      source: "page (user-supplied, advisory \u2014 not for authorization)",
+      context: readPageContext(requestContext)
+    })
+  });
+}
+
+// src/scratchpad-tool.ts
+import { createTool as createTool2 } from "@mastra/core/tools";
+import { z as z2 } from "zod";
+function buildScratchpadTool(store, caps) {
+  const maxEntryChars = caps?.maxEntryChars ?? SCRATCHPAD_MAX_ENTRY_CHARS;
+  return createTool2({
+    id: "scratchpad_write",
+    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: z2.object({
+      section: z2.enum(["public", "meta"]),
+      key: z2.string().describe("a short stable slug for THIS fact, e.g. 'launch-date' \u2014 reuse it to revise that fact"),
+      content: z2.string()
+    }),
+    execute: async (input, context) => {
+      const { section, key, content } = input;
+      const c = context;
+      const rc = c?.requestContext;
+      const tenantId = rc?.get("tenantId") ?? "default";
+      const threadId = rc?.get("threadId") ?? "";
+      const userId = rc?.get("userId") ?? "unknown";
+      const runSlug = rc?.get("agentSlug") ?? "unknown";
+      const agentId = c?.agent?.agentId ?? "";
+      const isSub = agentId.startsWith("swarm-sub-");
+      const author = isSub ? agentId.slice("swarm-sub-".length) : runSlug;
+      const requestedBy = isSub ? runSlug : "user";
+      const container = threadId.split(":")[0] || threadId;
+      const capped = content.length > maxEntryChars ? content.slice(0, maxEntryChars) + "\u2026[truncated]" : content;
+      await store.write(tenantId, container, section, key, capped, { agentSlug: author, userId, requestedBy, maxKeys: caps?.maxKeys });
+      return { ok: true, section, key };
+    }
+  });
+}
+
+// src/recall-lane-tool.ts
+import { createTool as createTool3 } from "@mastra/core/tools";
+import { z as z3 } from "zod";
+var RECALL_LANE_LIMIT = 20;
+function buildRecallLaneTool(read) {
+  return createTool3({
+    id: "recall_lane",
+    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: z3.object({ agentSlug: z3.string() }),
+    execute: async (input, { requestContext }) => {
+      const { agentSlug } = input;
+      const get = (k) => requestContext?.get(k) ?? "";
+      const threadId = get("threadId");
+      const container = threadId.split(":")[0] || threadId;
+      const runSlug = get("agentSlug");
+      const onBareContainer = !threadId.includes(":");
+      const isRoot = onBareContainer && agentSlug === runSlug;
+      const peerLane = isRoot ? container : `${container}:${agentSlug}`;
+      const ctx = {
+        tenantId: get("tenantId") || "default",
+        userId: get("userId") || "unknown",
+        agentSlug: get("agentSlug") || "unknown",
+        threadId: peerLane,
+        runId: get("runId") || "recall"
+      };
+      const messages = await read(peerLane, ctx);
+      return { agentSlug, messages: messages.map((m) => ({ role: m.role, text: m.text, ts: m.ts })) };
+    }
+  });
+}
+
+// src/memory.ts
+import { Memory } from "@mastra/memory";
+function mergeMemoryOptions(base2, override) {
+  return {
+    ...base2,
+    ...override.lastMessages !== void 0 ? { lastMessages: override.lastMessages } : {},
+    ...override.workingMemory !== void 0 ? { workingMemory: override.workingMemory } : {},
+    ...override.semanticRecall !== void 0 ? { semanticRecall: override.semanticRecall } : {},
+    ...override.observationalMemory !== void 0 ? { observationalMemory: override.observationalMemory } : {}
+  };
+}
+function buildMemoryResolver(memCfg) {
+  const memory = buildMemory(memCfg);
+  const cache = /* @__PURE__ */ new Map();
+  const resolveMemory = (row) => {
+    if (!row.memory) return memory;
+    const key = JSON.stringify(row.memory);
+    let m = cache.get(key);
+    if (!m) {
+      m = buildMemory(mergeMemoryOptions(memCfg, row.memory));
+      cache.set(key, m);
+    }
+    return m;
+  };
+  return { memory, resolveMemory };
+}
+function resourceId(ctx) {
+  const container = ctx.threadId.split(":")[0] || ctx.threadId;
+  return `${ctx.tenantId}:${container}`;
+}
+function buildMemory(cfg) {
+  const wantRecall = cfg.semanticRecall !== void 0 && cfg.semanticRecall !== false;
+  if (wantRecall && (!cfg.vector || !cfg.embedder)) {
+    throw new Error("memory.semanticRecall requires both `vector` and `embedder`");
+  }
+  const wm = cfg.workingMemory;
+  const sr = cfg.semanticRecall;
+  const wmOption = wm ? {
+    enabled: true,
+    ...typeof wm === "object" ? wm : {},
+    scope: "thread"
+    // thread-only: working memory never spans a user's other threads
+  } : void 0;
+  const srOption = wantRecall ? {
+    topK: 5,
+    messageRange: 2,
+    ...typeof sr === "object" ? sr : {},
+    scope: "thread"
+    // thread-only: recall never surfaces messages from other threads
+  } : false;
+  return new Memory({
+    storage: cfg.store,
+    vector: cfg.vector ?? void 0,
+    embedder: cfg.embedder ?? void 0,
+    options: {
+      lastMessages: cfg.lastMessages ?? 20,
+      workingMemory: wmOption,
+      semanticRecall: srOption,
+      // R10: forward Mastra's built-in observational memory (LLM observation/reflection compaction) when opted in.
+      ...cfg.observationalMemory !== void 0 ? { observationalMemory: cfg.observationalMemory } : {}
+    }
+  });
+}
+
+// src/floor.ts
+var InMemoryContainerFloor = class {
+  /** @param maxHoldMs force-release backstop for a hung grant (a run that never releases). */
+  constructor(maxHoldMs = 18e4) {
+    this.maxHoldMs = maxHoldMs;
+  }
+  maxHoldMs;
+  // Slots are intentionally never evicted: a freed slot is a tiny `{held:null, timer:null, waiters:[]}`,
+  // and containers are conversation-keyed (bounded by real usage), so retention is negligible.
+  slots = /* @__PURE__ */ new Map();
+  slot(container) {
+    let s = this.slots.get(container);
+    if (!s) {
+      s = { held: null, timer: null, waiters: [] };
+      this.slots.set(container, s);
+    }
+    return s;
+  }
+  async holder(container) {
+    return this.slots.get(container)?.held ?? null;
+  }
+  async queueDepth(container) {
+    return this.slots.get(container)?.waiters.filter((w) => !w.cancelled).length ?? 0;
+  }
+  async tryAcquire(container, who) {
+    const s = this.slot(container);
+    return s.held ? null : this.grant(container, s, who);
+  }
+  acquire(container, who, signal) {
+    const s = this.slot(container);
+    if (!s.held) return Promise.resolve(this.grant(container, s, who));
+    return new Promise((resolve) => {
+      const waiter = { who, resolve, cancelled: false };
+      s.waiters.push(waiter);
+      if (!signal) return;
+      const onAbort = () => {
+        if (waiter.cancelled) return;
+        waiter.cancelled = true;
+        const i = s.waiters.indexOf(waiter);
+        if (i >= 0) {
+          s.waiters.splice(i, 1);
+          resolve(() => {
+          });
+        } else if (s.held === who) {
+          this.release(container, s, who);
+        }
+      };
+      if (signal.aborted) onAbort();
+      else signal.addEventListener("abort", onAbort, { once: true });
+    });
+  }
+  /** Take the floor for `who`, arm the backstop, and return an idempotent release that hands off FIFO. */
+  grant(container, s, who) {
+    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})`);
+      this.release(container, s, who);
+    }, this.maxHoldMs);
+    if (typeof s.timer.unref === "function") s.timer.unref();
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.release(container, s, who);
+    };
+  }
+  /** Release `who`'s hold (if still current) and grant the next live FIFO waiter, or free the floor. */
+  release(container, s, who) {
+    if (s.held !== who) return;
+    if (s.timer) {
+      clearTimeout(s.timer);
+      s.timer = null;
+    }
+    let next = s.waiters.shift();
+    while (next && next.cancelled) next = s.waiters.shift();
+    if (next) {
+      next.resolve(this.grant(container, s, next.who));
+    } else {
+      s.held = null;
+    }
+  }
+};
+var containerFloor = new InMemoryContainerFloor();
+
+// src/cost.ts
+var PRICE_TABLE = {
+  // built-in, host-overridable (CONTRACTS §10). Values are placeholders pending a real price feed.
+  "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;
+}
+var CostGovernor = class {
+  constructor(opts) {
+    this.opts = opts;
+    this.prices = { ...PRICE_TABLE, ...opts.prices ?? {} };
+  }
+  opts;
+  steps = 0;
+  usd = 0;
+  prices;
+  step() {
+    this.steps++;
+  }
+  /** Price a single usage WITHOUT accumulating it (for per-generation telemetry cost). */
+  priceOf(modelId, u) {
+    return priceUsage(this.prices, modelId, u);
+  }
+  addUsage(modelId, u) {
+    this.usd += this.priceOf(modelId, u);
+  }
+  costUsd() {
+    return this.usd;
+  }
+  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" };
+    return { stop: false };
+  }
+};
+var DelegateBudgets = class {
+  constructor(cfg, rootSlug, prices) {
+    this.cfg = cfg;
+    this.rootSlug = rootSlug;
+    this.prices = { ...PRICE_TABLE, ...prices ?? {} };
+  }
+  cfg;
+  rootSlug;
+  usd = /* @__PURE__ */ new Map();
+  prices;
+  /** 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;
+  }
+  /** 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));
+  }
+  /** The first delegate that has met or exceeded its USD cap, or null. */
+  exceeded() {
+    for (const [slug, spent] of this.usd) {
+      const cap = this.capFor(slug);
+      if (cap != null && spent >= cap) {
+        return { slug, reason: `delegate '${slug}' exceeded its per-delegate USD budget ($${cap})` };
+      }
+    }
+    return null;
+  }
+};
+
+// src/telemetry.ts
+function customTelemetry(fn) {
+  return {
+    export: async (spans) => {
+      await fn(spans);
+    }
+  };
+}
+function compositeTelemetry(exporters) {
+  return {
+    export: async (spans) => {
+      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);
+        }
+      }
+    }
+  };
+}
+function resolveTelemetry(t) {
+  if (!t) return null;
+  return Array.isArray(t) ? compositeTelemetry(t) : t;
+}
+var CapturingExporter = class {
+  spans = [];
+  async export(spans) {
+    this.spans.push(...spans);
+  }
+};
+var SpanCollector = class {
+  constructor(traceId, now, runName, runAttrs = {}) {
+    this.traceId = traceId;
+    this.now = now;
+    this.runSpan = { name: runName, kind: "run", traceId, attributes: runAttrs, startedAt: now() };
+    this.spans.push(this.runSpan);
+  }
+  traceId;
+  now;
+  spans = [];
+  runSpan;
+  gen = null;
+  tools = /* @__PURE__ */ new Map();
+  /** Ensure a generation span is open (lazy — first model activity in this step). */
+  openGeneration(modelId) {
+    if (this.gen) return;
+    this.gen = {
+      name: "generation",
+      kind: "generation",
+      traceId: this.traceId,
+      attributes: { modelId },
+      startedAt: this.now()
+    };
+    this.spans.push(this.gen);
+  }
+  /**
+   * Close the open generation with this step's usage + its own per-call cost (already priced from
+   * the step usage by the engine). `costUsd` is per-generation — never a cumulative running total.
+   */
+  closeGeneration(usage, costUsd) {
+    if (!this.gen) return;
+    this.gen.attributes = {
+      ...this.gen.attributes,
+      inputTokens: usage.inputTokens,
+      outputTokens: usage.outputTokens,
+      costUsd: Math.max(0, costUsd)
+    };
+    this.gen.endedAt = this.now();
+    this.gen = null;
+  }
+  openTool(toolCallId, name) {
+    const s = {
+      name: `tool:${name}`,
+      kind: "tool",
+      traceId: this.traceId,
+      attributes: { toolCallId, name },
+      startedAt: this.now()
+    };
+    this.tools.set(toolCallId, s);
+    this.spans.push(s);
+  }
+  closeTool(toolCallId, ok) {
+    const s = this.tools.get(toolCallId);
+    if (!s) return;
+    s.attributes = { ...s.attributes, ok };
+    s.endedAt = this.now();
+    this.tools.delete(toolCallId);
+  }
+  /**
+   * Seal: close the run span and any dangling open spans, return the batch. A run that suspends
+   * mid-step (e.g. an `ask` tool-call → `tool-call-suspended` with no `step-finish`) leaves the
+   * generation/tool spans open with no usage/result — those are tagged `incomplete:true` so
+   * downstream consumers don't mistake a sealed-but-unfinished span for a completed one.
+   */
+  finish() {
+    const t = this.now();
+    if (this.gen && this.gen.endedAt == null) {
+      this.gen.attributes = { ...this.gen.attributes, incomplete: true };
+      this.gen.endedAt = t;
+    }
+    for (const s of this.tools.values()) {
+      if (s.endedAt == null) {
+        s.attributes = { ...s.attributes, incomplete: true };
+        s.endedAt = t;
+      }
+    }
+    if (this.runSpan.endedAt == null) this.runSpan.endedAt = t;
+    return this.spans;
+  }
+};
+
+// src/cache.ts
+var RowCache = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  map = /* @__PURE__ */ new Map();
+  now() {
+    return this.opts.now ? this.opts.now() : Date.now();
+  }
+  async get(key, load) {
+    const hit = this.map.get(key);
+    if (hit && hit.exp > this.now()) {
+      this.map.delete(key);
+      this.map.set(key, hit);
+      return hit.v;
+    }
+    const v = await load();
+    this.map.set(key, { v, exp: this.now() + this.opts.ttlMs });
+    if (this.map.size > this.opts.max) {
+      const oldest = this.map.keys().next().value;
+      if (oldest !== void 0) this.map.delete(oldest);
+    }
+    return v;
+  }
+  /** Synchronous read of an already-cached, unexpired value (no load, no LRU touch). */
+  peek(key) {
+    const hit = this.map.get(key);
+    return hit && hit.exp > this.now() ? hit.v : void 0;
+  }
+  invalidate(key) {
+    this.map.delete(key);
+  }
+};
+
+// src/engine.ts
+var AGENT_KEY = "swarm";
+var SwarmEngine = class {
+  constructor(opts) {
+    this.opts = opts;
+    if (opts.scratchpad && !opts.storage.scratchpad) {
+      throw new Error("scratchpad: true requires a StorageAdapter with a scratchpad store");
+    }
+    const { memory, resolveMemory } = opts.memory ? buildMemoryResolver(opts.memory) : { memory: void 0, resolveMemory: void 0 };
+    this.memory = memory;
+    this.floor = opts.floor ?? containerFloor;
+    opts.storage.subscribeInvalidations?.((key) => this.rowCache.invalidate(key));
+    const agent = buildMastraAgent({
+      loadRow: (slug, tenantId) => this.loadRow(tenantId, slug),
+      resolveMemory,
+      resolveSkill: (n) => opts.resolveSkill?.(n),
+      model: opts.model,
+      modelFactory: opts.modelFactory,
+      builtinTools: {
+        [ASK_TOOL_NAME]: buildAskMastraTool(),
+        ...opts.scratchpad ? { scratchpad_write: buildScratchpadTool(opts.storage.scratchpad, typeof opts.scratchpad === "object" ? opts.scratchpad : void 0) } : {},
+        ...opts.recallLane ? { recall_lane: buildRecallLaneTool((tid, ctx) => this.history(tid, ctx, { limit: RECALL_LANE_LIMIT })) } : {}
+      },
+      // Opt-in page-context channel: expose `get_page_context` on the user-facing orchestrator
+      // 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,
+      memory
+    });
+    this.mastra = new Mastra({
+      storage: opts.mastraStore ?? new InMemoryStore(),
+      agents: { [AGENT_KEY]: agent }
+    });
+  }
+  opts;
+  mastra;
+  // One cache per engine: the three dynamic agent fns (instructions/model/tools)
+  // each call loadRow within a single request, so without this the row is fetched
+  // 3× per turn. Short TTL keeps published-version changes fresh.
+  rowCache = new RowCache({ max: 256, ttlMs: 3e4 });
+  // The one Mastra Memory this engine streams against (undefined when stateless). Held so
+  // `history` can read a thread's persisted conversation from the SAME memory used for streaming.
+  // Typed `unknown` to keep the engine wall: no engine-vendor type escapes the public surface.
+  memory;
+  floor;
+  /** Cached agent-row load shared by the three dynamic agent fns AND run/resume. */
+  loadRow(tenantId, slug) {
+    return this.rowCache.get(`${tenantId}:${slug}`, async () => {
+      const row = await this.opts.storage.agents.head(tenantId, slug);
+      if (!row) throw new Error(`unknown agent: ${slug}`);
+      return row;
+    });
+  }
+  agent() {
+    return this.mastra.getAgent(AGENT_KEY);
+  }
+  requestContext(ctx) {
+    const rc = new RequestContext();
+    for (const [k, v] of Object.entries(ctx)) {
+      if (v !== void 0) rc.set(k, v);
+    }
+    return rc;
+  }
+  /** Per-call Mastra memory ids + delegation, only when memory is configured (else stream is unchanged). */
+  memoryOpts(ctx) {
+    if (!this.opts.memory) return {};
+    return {
+      memory: { thread: ctx.threadId, resource: resourceId(ctx) },
+      delegation: { includeSubAgentToolResultsInModelContext: true }
+    };
+  }
+  /**
+   * Read a thread's persisted conversation from the engine's Memory and return it as wall-safe
+   * `SwarmMessage[]` (no engine-vendor type in the signature or the result — powers "reload keeps the chat").
+   *
+   * Shapes are spike-proven against the Mastra memory surface (`memory.recall`, NOT `memory.query`): each
+   * recalled row is a MastraDBMessage whose text lives in `content.parts[]` (NOT a flat `m.text`/string
+   * `m.content`). The vendor value is cast THROUGH a local structural type so no vendor type leaks to the
+   * public `.d.ts` (engine wall). Returns `[]` when the engine is stateless (no memory configured).
+   */
+  async history(threadId, ctx, opts) {
+    if (!this.memory) return [];
+    const mem = this.memory;
+    const limit = opts?.limit ?? 200;
+    const recallStart = Date.now();
+    let recalled;
+    try {
+      recalled = await mem.recall({ threadId, resourceId: resourceId(ctx), threadConfig: { lastMessages: limit } });
+    } catch {
+      this.emitRecallSpan(ctx, threadId, recallStart, { limit, messageCount: 0, ok: false });
+      return [];
+    }
+    const mapped = recalled.messages.map((m) => {
+      const role = m.role === "user" ? "user" : "assistant";
+      const raw = (m.content?.parts ?? []).filter((p) => p.type === "text").map((p) => p.text ?? "").join("");
+      const speaker = role === "assistant" ? /^\[([a-z0-9][a-z0-9-]*)\]\s([\s\S]*)$/.exec(raw) : null;
+      const sender = role === "user" ? /^\[user:([^\]]*)\]\s([\s\S]*)$/.exec(raw) : null;
+      return {
+        threadId: m.threadId ?? threadId,
+        role,
+        text: speaker ? speaker[2] : sender ? sender[2] : raw,
+        ts: +new Date(m.createdAt),
+        ...speaker ? { agentSlug: speaker[1] } : {},
+        ...sender ? { userId: sender[1] } : {}
+      };
+    });
+    const result = mapped.length > limit ? mapped.slice(-limit) : mapped;
+    this.emitRecallSpan(ctx, threadId, recallStart, { limit, messageCount: result.length, ok: true });
+    return result;
+  }
+  /**
+   * R4: emit a single `recall` telemetry span for a `history` recall, best-effort. Fire-and-forget — a
+   * throwing/slow exporter must never delay or break a history read, so we don't await it and swallow errors.
+   * traceId is the invoking ctx's runId so a recall inside a run (via `recall_lane`) joins that run's trace.
+   */
+  emitRecallSpan(ctx, threadId, startedAt, attrs) {
+    const telemetry = this.opts.telemetry;
+    if (!telemetry) return;
+    const span = {
+      name: "recall",
+      kind: "recall",
+      traceId: ctx.runId,
+      attributes: { threadId, resourceId: resourceId(ctx), ...attrs },
+      startedAt,
+      endedAt: Date.now()
+    };
+    void Promise.resolve().then(() => telemetry.export([span])).catch(() => {
+    });
+  }
+  /**
+   * Multi-agent shared-thread attribution (the persist boundary). Mastra recall carries NO per-message
+   * author field (spike-proven), so on a thread several agents share, a later agent can't tell who said an
+   * earlier assistant turn. After a run drains, this PREFIXES that run's just-persisted assistant turn(s)
+   * with `"[<slug>] "` — the only place the speaker survives in Mastra memory — so a subsequent agent's
+   * recall sees it inline; `history` decodes + strips it for display. Best-effort: never throws into the
+   * run, and no-op when the engine is stateless. Idempotent (skips an already-prefixed turn) and bounded to
+   * THIS run's responses (only assistant turns AFTER the most-recent user message) so a wide recall window
+   * can never re-stamp an older agent's turn with the wrong slug.
+   */
+  async attributeRun(ctx) {
+    if (!this.memory) return;
+    const mem = this.memory;
+    const rid = resourceId(ctx);
+    try {
+      const { messages } = await mem.recall({ threadId: ctx.threadId, resourceId: rid, threadConfig: { lastMessages: 30 } });
+      let lastUserIdx = -1;
+      for (let i = 0; i < messages.length; i++) if (messages[i].role === "user") lastUserIdx = i;
+      if (lastUserIdx >= 0) {
+        const um = messages[lastUserIdx];
+        const content = um.content ?? {};
+        const parts = Array.isArray(content.parts) ? content.parts : [];
+        const idx = parts.findIndex((p) => p?.type === "text");
+        const cur = idx >= 0 ? String(parts[idx].text ?? "") : "";
+        const existing = /^\[user:([^\]]*)\]/.exec(cur);
+        if (idx >= 0 && (!existing || existing[1] === ctx.userId)) {
+          const stripped = cur.replace(/^(\[user:[^\]]*\]\s*)+/, "");
+          const stampedParts = parts.map((p, i) => i === idx ? { ...p, text: `[user:${ctx.userId}] ${stripped}` } : p);
+          const flatU = stampedParts.filter((p) => p?.type === "text").map((p) => String(p.text ?? "")).join("");
+          await mem.updateMessages({
+            messages: [{ id: um.id, role: "user", threadId: um.threadId ?? ctx.threadId, resourceId: rid, content: { ...content, format: 2, parts: stampedParts, content: flatU } }]
+          });
+        }
+      }
+      const prefix = `[${ctx.agentSlug}] `;
+      for (const m of messages.slice(lastUserIdx + 1)) {
+        if (m.role !== "assistant") continue;
+        const content = m.content ?? {};
+        const parts = Array.isArray(content.parts) ? content.parts : [];
+        const idx = parts.findIndex((p) => p?.type === "text");
+        if (idx < 0) continue;
+        const firstText = String(parts[idx].text ?? "");
+        if (firstText.startsWith("[")) continue;
+        const newParts = parts.map((p, i) => i === idx ? { ...p, text: prefix + firstText } : p);
+        const flat = newParts.filter((p) => p?.type === "text").map((p) => String(p.text ?? "")).join("");
+        await mem.updateMessages({
+          messages: [{ id: m.id, role: "assistant", threadId: m.threadId ?? ctx.threadId, resourceId: rid, content: { ...content, format: 2, parts: newParts, content: flat } }]
+        });
+      }
+    } catch {
+    }
+  }
+  /**
+   * Part B — mirror a delegation into the sub-agent's LANE thread. A delegation runs the sub-agent as a
+   * Mastra `agent-<slug>` tool inside the orchestrator's turn, so its work lands in the orchestrator's
+   * thread, not the sub-agent's lane (`<container>:<slug>`). After the run drains, this recalls THIS run's
+   * assistant turn(s) and, for each `agent-<slug>` tool-invocation part (which carries BOTH the task =
+   * `args.prompt` and the answer = `result.text`), `saveMessages` the pair into the sub-agent's lane thread
+   * — so switching to that agent's lane shows the delegated task + result, durably. Best-effort; Mastra-only
+   * (no nightowls.runs row ⇒ no thread-backing FK). Bounded to this run's turns ⇒ each run mirrors once.
+   */
+  async mirrorDelegations(ctx) {
+    if (!this.memory) return;
+    const mem = this.memory;
+    const rid = resourceId(ctx);
+    try {
+      const { messages } = await mem.recall({ threadId: ctx.threadId, resourceId: rid, threadConfig: { lastMessages: 30 } });
+      let lastUserIdx = -1;
+      for (let i = 0; i < messages.length; i++) if (messages[i].role === "user") lastUserIdx = i;
+      for (const m of messages.slice(lastUserIdx + 1)) {
+        if (m.role !== "assistant") continue;
+        const parts = Array.isArray(m.content?.parts) ? m.content.parts : [];
+        for (const p of parts) {
+          if (p?.type !== "tool-invocation") continue;
+          const ti = p.toolInvocation;
+          if (!ti || ti.state !== "result" || !ti.toolName?.startsWith("agent-")) continue;
+          const subSlug = ti.toolName.slice("agent-".length);
+          const task = (ti.args?.prompt ?? "").trim() || "(no task)";
+          const answer = (ti.result?.text ?? "").trim();
+          if (!answer) continue;
+          const laneTid = `${ctx.threadId}:${subSlug}`;
+          await mem.createThread({ threadId: laneTid, resourceId: rid, metadata: {} });
+          await mem.saveMessages({
+            messages: [
+              { role: "user", threadId: laneTid, resourceId: rid, content: { format: 2, parts: [{ type: "text", text: `\u21AA ${ctx.agentSlug} asked: ${task}` }] } },
+              { role: "assistant", threadId: laneTid, resourceId: rid, content: { format: 2, parts: [{ type: "text", text: answer }] } }
+            ]
+          });
+        }
+      }
+    } catch {
+    }
+  }
+  /**
+   * List the user's conversations from the engine's Memory and return them as wall-safe
+   * `ThreadSummary[]` (no engine-vendor type in the signature or the result — powers a threads-list
+   * sidebar). Returns `[]` when the engine is stateless (no memory configured).
+   *
+   * Shape is spike-proven against the Mastra memory surface (`memory.listThreads`, NOT the
+   * non-existent `getThreadsByResourceId`): resourceId goes under `filter`, the envelope is
+   * `{ threads }`, and each thread row carries `{ id, title?, createdAt, updatedAt }` (see the
+   * threads-spike SPIKE-FINDINGS). The vendor value is cast THROUGH a local structural type so no
+   * vendor type leaks to the public `.d.ts` (engine wall). Already DESC by `updatedAt`, so the
+   * newest-active thread is first; no per-thread recall (avoids N+1) — the engine auto-titles threads.
+   */
+  async listThreads(ctx, opts) {
+    if (!this.memory) return [];
+    const mem = this.memory;
+    const limit = opts?.limit ?? 50;
+    const toSummary = (t) => ({
+      threadId: t.id,
+      title: (t.title ?? "").trim() || new Date(t.createdAt).toLocaleString(),
+      lastActivityAt: +new Date(t.updatedAt)
+    });
+    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(async (container) => {
+          const { threads: threads2 } = await mem.listThreads({ filter: { resourceId: `${ctx.tenantId}:${container}` }, perPage: 8, page: 0 });
+          const bare = threads2.find((t) => t.id === container) ?? threads2.find((t) => !t.id.includes(":"));
+          return bare ? toSummary(bare) : { threadId: container, title: container, lastActivityAt: 0 };
+        })
+      );
+      return out.slice(0, limit);
+    }
+    const { threads } = await mem.listThreads({
+      filter: { resourceId: resourceId(ctx) },
+      orderBy: { field: "updatedAt", direction: "DESC" },
+      perPage: limit * 4,
+      page: 0
+    });
+    return threads.filter((t) => !t.id.includes(":")).map(toSummary).slice(0, limit);
+  }
+  /** The PUBLIC entries of a conversation's scratchpad (empty array when the feature is off or unset). */
+  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 — powers cross-lane background presence (E5). */
+  async activeRuns(container, ctx) {
+    return this.opts.storage.runs.listActive(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. */
+  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: r.delegateSlugs ?? []
+    }));
+  }
+  async *run(input, ctx) {
+    const modelId = (await this.loadRow(ctx.tenantId, ctx.agentSlug)).modelId ?? "unknown";
+    await this.opts.storage.runs.create({
+      runId: ctx.runId,
+      tenantId: ctx.tenantId,
+      userId: ctx.userId,
+      threadId: ctx.threadId,
+      agentSlug: ctx.agentSlug
+    });
+    const modelIdFor = (slug) => this.rowCache.peek(`${ctx.tenantId}:${slug}`)?.modelId ?? modelId;
+    const gov = new CostGovernor(this.opts.cost);
+    const delegateBudgets = this.opts.cost.perDelegate ? new DelegateBudgets(this.opts.cost.perDelegate, ctx.agentSlug) : null;
+    const streamed = /* @__PURE__ */ new Set();
+    const rc = this.requestContext(ctx);
+    if (this.opts.pageContext) attachPageContext(rc, input.context);
+    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);
+      return e;
+    };
+    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", base(ctx, ts++), { state: "blocked", note: held?.label ?? "another agent", position }));
+        releaseFloor = await this.floor.acquire(floorKey, me, floorAbort.signal);
+        if (floorAbort.signal.aborted) return;
+      }
+      yield await emit(ev("swarm.status", base(ctx, ts++), { state: "thinking" }));
+      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;
+        }
+        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;
+        }
+      }
+      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" }));
+    } catch (err) {
+      console.error(`[nightowls] 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 }));
+    } finally {
+      floorAbort.abort();
+      await releaseFloor?.();
+      await exportSpans(this.opts.telemetry, collector);
+    }
+  }
+  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}`);
+    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 gov = new CostGovernor(this.opts.cost);
+    const delegateBudgets = this.opts.cost.perDelegate ? new DelegateBudgets(this.opts.cost.perDelegate, ctx.agentSlug) : null;
+    const streamed = /* @__PURE__ */ new Set();
+    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);
+      return e;
+    };
+    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 };
+    try {
+      if (!releaseFloor) {
+        const held = await this.floor.holder(floorKey);
+        const position = await this.floor.queueDepth(floorKey) + 1;
+        yield await emit(ev("swarm.status", base(rctx, ts++), { state: "blocked", note: held?.label ?? "another agent", position }));
+        releaseFloor = await this.floor.acquire(floorKey, me, floorAbort.signal);
+        if (floorAbort.signal.aborted) return;
+      }
+      yield await emit(
+        ev("swarm.answer", base({ ...ctx, runId: args.runId }, ts++), {
+          followupId: args.followupId,
+          from: "user",
+          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") {
+          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
+            })
+          );
+          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;
+        }
+      }
+      await this.attributeRun(rctx);
+      await this.opts.storage.runs.setStatus(args.runId, "done");
+      yield await emit(ev("swarm.status", base(rctx, ts++), { state: "done" }));
+    } catch (err) {
+      console.error(`[nightowls] 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 }));
+    } finally {
+      floorAbort.abort();
+      await releaseFloor?.();
+      await exportSpans(this.opts.telemetry, collector);
+    }
+  }
+};
+function errMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function base(ctx, ts) {
+  return { runId: ctx.runId, agentSlug: ctx.agentSlug, ts };
+}
+function titleCase(slug) {
+  return slug.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+function safeParse(s) {
+  try {
+    const v = JSON.parse(s);
+    return v && typeof v === "object" ? v : {};
+  } catch {
+    return {};
+  }
+}
+function streamErrorMessage(part) {
+  const err = part.payload?.error;
+  return String(err?.message ?? "stream error");
+}
+function collectSpans(collector, part, modelId, gov) {
+  if (!collector) return;
+  const p = part.payload ?? {};
+  switch (part.type) {
+    case "text-delta":
+      collector.openGeneration(modelId);
+      break;
+    case "tool-call":
+      collector.openGeneration(modelId);
+      collector.openTool(p.toolCallId, p.toolName);
+      break;
+    case "tool-result":
+      collector.closeTool(p.toolCallId, true);
+      break;
+    case "step-finish": {
+      const output = p.output;
+      const usage = output?.usage;
+      const u = { inputTokens: usage?.inputTokens ?? 0, outputTokens: usage?.outputTokens ?? 0 };
+      collector.openGeneration(modelId);
+      collector.closeGeneration(u, gov.priceOf(modelId, u));
+      break;
+    }
+    default:
+      break;
+  }
+}
+async function exportSpans(telemetry, collector) {
+  if (!telemetry || !collector) return;
+  try {
+    await telemetry.export(collector.finish());
+  } catch {
+  }
+}
+var warnedNoRecordSuspend = false;
+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."
+    );
+  }
+  await storage.recordSuspend?.(ctx.runId, ctx.tenantId, followupId, toolCallId);
+}
+function mapChunk(part, ctx, gov, modelIdFor, nextTs, streamed, delegateBudgets) {
+  const p = part.payload ?? {};
+  const modelId = modelIdFor(ctx.agentSlug);
+  switch (part.type) {
+    case "text-delta":
+      return [ev("swarm.message", base(ctx, nextTs()), { role: "assistant", delta: p.text ?? "" })];
+    case "tool-call": {
+      const name = p.toolName;
+      if (name?.startsWith("agent-")) {
+        const to = name.slice("agent-".length);
+        const a = typeof p.args === "string" ? safeParse(p.args) : p.args;
+        const task = a?.prompt ?? "";
+        return [
+          ev("swarm.handoff", base(ctx, nextTs()), { from: ctx.agentSlug, to, task }),
+          ev("swarm.status", base(ctx, nextTs()), { state: "delegating", note: to })
+        ];
+      }
+      return [
+        ev("swarm.tool_call", base(ctx, nextTs()), {
+          toolCallId: p.toolCallId,
+          name,
+          args: p.args,
+          needsApproval: false
+        })
+      ];
+    }
+    case "tool-result": {
+      const name = p.toolName;
+      if (name?.startsWith("agent-")) {
+        const to = name.slice("agent-".length);
+        const tcid = p.toolCallId;
+        const out = [];
+        if (!streamed.has(tcid)) {
+          const text = p.result?.text;
+          if (text) out.push(ev("swarm.message", base({ ...ctx, agentSlug: to }, nextTs()), { role: "assistant", text }));
+        }
+        out.push(ev("swarm.status", base(ctx, nextTs()), { state: "thinking" }));
+        return out;
+      }
+      return [
+        ev("swarm.tool_result", base(ctx, nextTs()), {
+          toolCallId: p.toolCallId,
+          ok: true,
+          result: p.result
+        })
+      ];
+    }
+    case "finish": {
+      const output = p.output;
+      const usage = output?.usage;
+      if (usage) {
+        const u = { inputTokens: usage.inputTokens ?? 0, outputTokens: usage.outputTokens ?? 0 };
+        gov.addUsage(modelId, u);
+        delegateBudgets?.addUsage(ctx.agentSlug, modelId, u);
+      }
+      return [];
+    }
+    case "tool-output": {
+      const name = p.toolName ?? "";
+      if (!name.startsWith("agent-")) return [];
+      const subSlug = name.slice("agent-".length);
+      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);
+    }
+    case "tool-error": {
+      const name = p.toolName ?? "";
+      const err = p.error;
+      const error = typeof err === "string" ? err : err?.message ?? "tool error";
+      const failed = ev("swarm.tool_result", base(ctx, nextTs()), {
+        toolCallId: p.toolCallId,
+        ok: false,
+        error
+      });
+      return name.startsWith("agent-") ? [failed, ev("swarm.status", base(ctx, nextTs()), { state: "thinking" })] : [failed];
+    }
+    default:
+      return [];
+  }
+}
+
+// src/model.ts
+function allowListModelProvider(opts) {
+  const set = new Set(opts.allow);
+  return {
+    resolve: async (modelId) => {
+      if (!set.has(modelId)) throw new Error(`model not allowed: ${modelId}`);
+      return modelId;
+    }
+  };
+}
+
+// src/define.ts
+var MASTRA = /* @__PURE__ */ new WeakMap();
+function defineTool(spec) {
+  const origin = spec.origin ?? "first-party";
+  const needsApproval = spec.needsApproval ?? origin === "mcp";
+  const mastraTool = createTool4({
+    id: spec.name,
+    description: spec.description ?? spec.name,
+    inputSchema: spec.inputSchema,
+    outputSchema: spec.outputSchema,
+    // 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`.
+    execute: async (inputData, context) => {
+      const rc = context?.requestContext;
+      const ctx = {
+        tenantId: rc?.get?.("tenantId") ?? "default",
+        userId: rc?.get?.("userId") ?? "",
+        runId: rc?.get?.("runId") ?? ""
+      };
+      return spec.execute(inputData, ctx);
+    }
+  });
+  const handle = { name: spec.name, needsApproval, origin };
+  MASTRA.set(handle, mastraTool);
+  return handle;
+}
+function defineSkill(tool) {
+  return tool;
+}
+function __getMastraTool(t) {
+  return MASTRA.get(t);
+}
+function defineAgent(spec) {
+  const skills = spec.skills ?? [];
+  return {
+    slug: spec.slug,
+    // 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,
+    head: {
+      slug: spec.slug,
+      version: 1,
+      role: spec.role ?? "specialist",
+      personality: spec.personality,
+      capabilities: spec.capabilities ?? [],
+      skillNames: skills.map((s) => s.name),
+      delegateSlugs: spec.delegates ?? [],
+      modelId: spec.modelId ?? "openai/gpt-5.5",
+      ...spec.memory ? { memory: spec.memory } : {}
+    }
+  };
+}
+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);
+}
+var ASK_TOOL_NAME = "ask";
+var askFieldSchema = z4.object({
+  kind: z4.enum(["confirm", "buttons", "select", "multiselect", "number", "text", "textarea"]),
+  options: z4.array(z4.object({ label: z4.string(), value: z4.string(), description: z4.string().optional() })).optional(),
+  min: z4.number().optional(),
+  max: z4.number().optional(),
+  step: z4.number().optional(),
+  unit: z4.string().optional(),
+  placeholder: z4.string().optional(),
+  rows: z4.number().optional(),
+  confirmLabel: z4.string().optional(),
+  rejectLabel: z4.string().optional(),
+  submitLabel: z4.string().optional(),
+  default: z4.any().optional()
+}).optional();
+function buildAskMastraTool() {
+  return createTool4({
+    id: ASK_TOOL_NAME,
+    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: z4.object({ to: z4.string().default("user"), prompt: z4.string(), field: askFieldSchema }),
+    // Rich answer: boolean (confirm), string (text/select/buttons), number, or string[] (multiselect).
+    outputSchema: z4.object({ answer: z4.any() }),
+    suspendSchema: z4.object({ to: z4.string(), prompt: z4.string(), field: askFieldSchema, asker: z4.string().optional() }),
+    resumeSchema: z4.object({ answer: z4.any() }),
+    execute: async (inputData, context) => {
+      const agentCtx = context?.agent;
+      if (agentCtx?.resumeData) {
+        return { answer: agentCtx.resumeData.answer };
+      }
+      const input = inputData;
+      const rc = context?.requestContext;
+      const runSlug = rc?.get("agentSlug") ?? "";
+      const agentId = agentCtx?.agentId ?? "";
+      const asker = agentId.startsWith("swarm-sub-") ? agentId.slice("swarm-sub-".length) : runSlug;
+      await agentCtx?.suspend({ to: input.to ?? "user", prompt: input.prompt, field: input.field, asker });
+      return { answer: "" };
+    }
+  });
+}
+function defineSwarm(cfg) {
+  const seedable = cfg.storage;
+  for (const a of cfg.agents) seedable.seedAgent?.(a.head);
+  const engine = new SwarmEngine({
+    storage: cfg.storage,
+    model: allowListModelProvider({ allow: cfg.models.allow }),
+    modelFactory: cfg.modelFactory,
+    cost: cfg.cost,
+    // Per-swarm skill registry, built from the agents passed in. No global state.
+    resolveSkill: buildSkillResolver(cfg.agents),
+    telemetry: resolveTelemetry(cfg.telemetry),
+    mastraStore: cfg.mastraStore,
+    memory: cfg.memory,
+    pageContext: cfg.pageContext,
+    scratchpad: cfg.scratchpad,
+    recallLane: cfg.recallLane
+  });
+  return { engine };
+}
+
+// src/storage/memory.ts
+var InMemoryStorage = class {
+  evts = [];
+  seq = 0;
+  runRows = /* @__PURE__ */ new Map();
+  snapshots = /* @__PURE__ */ new Map();
+  suspends = /* @__PURE__ */ new Map();
+  // key: tenantId:followupId
+  waitpoints = /* @__PURE__ */ new Map();
+  // followupId -> token (durable runner only)
+  msgs = [];
+  agentRows = /* @__PURE__ */ new Map();
+  // key: tenantId:slug:version
+  heads = /* @__PURE__ */ new Map();
+  // key: tenantId:slug -> version
+  pads = /* @__PURE__ */ new Map();
+  seedAgent(v, tenantId = "default") {
+    this.agentRows.set(`${tenantId}:${v.slug}:${v.version}`, v);
+    this.heads.set(`${tenantId}:${v.slug}`, v.version);
+  }
+  recordSuspend(runId, tenantId, followupId, toolCallId) {
+    this.suspends.set(`${tenantId}:${followupId}`, { runId, toolCallId });
+  }
+  markFollowupAnswered(followupId, tenantId) {
+    this.suspends.delete(`${tenantId}:${followupId}`);
+  }
+  /** Test/host helper: read a run row (the RunStore interface is write-mostly). */
+  getRun(runId) {
+    return this.runRows.get(runId);
+  }
+  events = {
+    append: async (e) => {
+      const seq = ++this.seq;
+      this.evts.push({ ...e, seq });
+      return seq;
+    },
+    // R11: tenant-scoped via the run's tenant. Lenient when no run row exists (orphan events in tests), strict
+    // otherwise (the supabase store enforces org_id per event row — this dev store cross-refs the run).
+    list: async (tenantId, runId, since) => this.evts.filter((e) => {
+      if (e.runId !== runId || (e.seq ?? 0) <= since) return false;
+      const r = this.runRows.get(runId);
+      return !r || r.tenantId === tenantId;
+    }),
+    subscribe: async function* (runId) {
+      for (const e of this.evts.filter((x) => x.runId === runId)) yield e;
+    }.bind(this)
+  };
+  runs = {
+    create: async (r) => {
+      this.runRows.set(r.runId, { ...r, status: "running" });
+    },
+    setStatus: async (runId, status, patch) => {
+      const cur = this.runRows.get(runId);
+      if (cur) this.runRows.set(runId, { ...cur, ...patch, status });
+    },
+    saveSnapshot: async (runId, snap) => {
+      this.snapshots.set(runId, snap);
+    },
+    loadSnapshot: async (tenantId, runId) => {
+      const r = this.runRows.get(runId);
+      if (r && r.tenantId !== tenantId) return null;
+      return this.snapshots.get(runId) ?? null;
+    },
+    findSuspended: async (tenantId, followupId) => this.suspends.get(`${tenantId}:${followupId}`) ?? null,
+    get: async (runId) => {
+      const row = this.runRows.get(runId);
+      if (!row) return null;
+      return { ...row, status: row.status ?? "running" };
+    },
+    listActive: async (tenantId, container) => {
+      const lanePrefix = `${container}:`;
+      return [...this.runRows.values()].filter((r) => r.tenantId === tenantId && (r.threadId === container || r.threadId.startsWith(lanePrefix)) && (r.status === "running" || r.status === "suspended")).map((r) => ({ runId: r.runId, threadId: r.threadId, agentSlug: r.agentSlug, status: r.status }));
+    },
+    // R14: distinct containers the user has a run in, most-recently-active first. The dev store has no run
+    // timestamps, so insertion order is the recency proxy (last-seen index per container).
+    listUserContainers: async (tenantId, userId, limit = 50) => {
+      const lastSeen = /* @__PURE__ */ new Map();
+      let i = 0;
+      for (const r of this.runRows.values()) {
+        if (r.tenantId !== tenantId || r.userId !== userId) continue;
+        lastSeen.set(r.threadId.split(":")[0] || r.threadId, i++);
+      }
+      return [...lastSeen.entries()].sort((a, b) => b[1] - a[1]).map(([c]) => c).slice(0, limit);
+    },
+    // R14 security: empty container OR the user participates (has a run in it).
+    canAccessContainer: async (tenantId, userId, container) => {
+      let hasRuns = false;
+      for (const r of this.runRows.values()) {
+        if (r.tenantId !== tenantId || (r.threadId.split(":")[0] || r.threadId) !== container) continue;
+        hasRuns = true;
+        if (r.userId === userId) return true;
+      }
+      return !hasRuns;
+    },
+    attachWaitpoint: async (followupId, token) => {
+      this.waitpoints.set(followupId, token);
+    },
+    getWaitpoint: async (followupId) => this.waitpoints.get(followupId) ?? null
+  };
+  messages = {
+    append: async (m) => {
+      this.msgs.push(m);
+    },
+    // R11: accepts tenantId for the contract; the dev store has no thread→tenant map and this path is unused
+    // in production (the runner's history goes through engine.history / Mastra recall), so it's best-effort.
+    history: async (_tenantId, threadId, limit = 50) => this.msgs.filter((m) => m.threadId === threadId).slice(-limit)
+  };
+  scratchpad = {
+    write: async (tenantId, container, section, key, content, by) => {
+      const mapKey = `${tenantId}:${container}:${section}`;
+      const sec = this.pads.get(mapKey) ?? /* @__PURE__ */ new Map();
+      sec.set(key, { author: by.agentSlug, user: by.userId, requestedBy: by.requestedBy, content, ts: Date.now() });
+      this.pads.set(mapKey, sec);
+      const maxKeys = by.maxKeys ?? SCRATCHPAD_MAX_KEYS;
+      if (sec.size > maxKeys) {
+        const oldestFirst = [...sec.entries()].sort((a, b) => a[1].ts - b[1].ts);
+        for (let i = 0; i < oldestFirst.length - maxKeys; i++) sec.delete(oldestFirst[i][0]);
+      }
+    },
+    list: async (tenantId, container) => {
+      const out = [];
+      for (const section of ["public", "meta"]) {
+        const sec = this.pads.get(`${tenantId}:${container}:${section}`);
+        if (sec) for (const [key, e] of sec) out.push({ section, key, author: e.author, requestedBy: e.requestedBy, content: e.content, updatedAt: e.ts });
+      }
+      return out;
+    }
+  };
+  agents = {
+    head: async (tenantId, slug) => {
+      const v = this.heads.get(`${tenantId}:${slug}`);
+      return v ? this.agentRows.get(`${tenantId}:${slug}:${v}`) ?? null : null;
+    },
+    getVersion: async (tenantId, slug, version) => this.agentRows.get(`${tenantId}:${slug}:${version}`) ?? null,
+    listSlugs: async (tenantId) => [...this.heads.keys()].filter((k) => k.startsWith(`${tenantId}:`)).map((k) => k.split(":")[1])
+  };
+};
+
+// src/auth.ts
+var customAuth = (fn) => ({ authenticate: fn });
+
+// src/index.ts
+var VERSION = "0.0.0";
+export {
+  ASK_TOOL_NAME,
+  CapturingExporter,
+  CostGovernor,
+  DelegateBudgets,
+  GUARDRAILS,
+  InMemoryContainerFloor,
+  InMemoryStorage,
+  PRICE_TABLE,
+  RowCache,
+  SCRATCHPAD_MAX_ENTRY_CHARS,
+  SCRATCHPAD_MAX_KEYS,
+  SpanCollector,
+  SwarmEngine,
+  VERSION,
+  allowListModelProvider,
+  buildSkillResolver,
+  composeSystemPrompt,
+  compositeTelemetry,
+  containerFloor,
+  customAuth,
+  customTelemetry,
+  defineAgent,
+  defineSkill,
+  defineSwarm,
+  defineTool,
+  ev,
+  isEvent,
+  resolveTelemetry
+};