@nightowlsdev/core 0.4.0 → 0.5.0

package/dist/index.cjs

@@ -25,6 +25,7 @@ __export(index_exports, {
   ASK_TOOL_NAME: () => ASK_TOOL_NAME,
   AgentMutationForbidden: () => AgentMutationForbidden,
   CapturingExporter: () => CapturingExporter,
+  ClientToolError: () => ClientToolError,
   CostGovernor: () => CostGovernor,
   DEFAULT_READ_ONLY_TOOLS: () => import_hooks4.DEFAULT_READ_ONLY_TOOLS,
   DelegateBudgets: () => DelegateBudgets,
@@ -43,6 +44,7 @@ __export(index_exports, {
   allowListModelProvider: () => allowListModelProvider,
   ask: () => import_hooks4.ask,
   assertActorMayMutateDefinition: () => assertActorMayMutateDefinition,
+  buildSingleAgentSwarm: () => buildSingleAgentSwarm,
   buildSkillResolver: () => buildSkillResolver,
   composePolicyPrompt: () => composePolicyPrompt,
   composeSystemPrompt: () => composeSystemPrompt,
@@ -50,11 +52,13 @@ __export(index_exports, {
   containerFloor: () => containerFloor,
   createHookDispatcher: () => import_hooks4.createHookDispatcher,
   createInMemoryRateLimitStore: () => createInMemoryRateLimitStore,
+  createRunState: () => createRunState,
   customAuth: () => customAuth,
   customTelemetry: () => customTelemetry,
   decideFixedWindow: () => decideFixedWindow,
   defineAgent: () => defineAgent,
   defineBundle: () => defineBundle,
+  defineClientTool: () => defineClientTool,
   defineHook: () => import_hooks4.defineHook,
   defineRule: () => defineRule,
   defineSkill: () => defineSkill,
@@ -62,6 +66,7 @@ __export(index_exports, {
   defineTool: () => defineTool,
   defineWorkflow: () => defineWorkflow,
   deny: () => import_hooks4.deny,
+  drainTrajectory: () => drainTrajectory,
   ev: () => ev,
   isEvent: () => isEvent,
   isTierSentinel: () => isTierSentinel,
@@ -70,6 +75,8 @@ __export(index_exports, {
   rateConfig: () => rateConfig,
   resolveTelemetry: () => resolveTelemetry,
   resolveTier: () => resolveTier,
+  runAgent: () => runAgent,
+  runToTrajectory: () => runToTrajectory,
   sumBreakdowns: () => sumBreakdowns,
   sumTurnUsage: () => sumTurnUsage,
   tierModelId: () => tierModelId,
@@ -188,6 +195,31 @@ function bindSecrets(resolver, ctx) {
   };
 }
 
+// src/run-state.ts
+var RUN_STATE_KEY = "__nightowls_run_state__";
+function snapshotCopy(store) {
+  const plain = Object.fromEntries(store);
+  try {
+    return (globalThis.structuredClone ?? ((v) => JSON.parse(JSON.stringify(v))))(plain);
+  } catch {
+    try {
+      return JSON.parse(JSON.stringify(plain));
+    } catch {
+      return plain;
+    }
+  }
+}
+function createRunState(seed) {
+  const m = new Map(seed ? Object.entries(seed) : void 0);
+  return {
+    get: (key) => m.get(key),
+    set: (key, value) => void m.set(key, value),
+    has: (key) => m.has(key),
+    delete: (key) => m.delete(key),
+    entries: () => snapshotCopy(m)
+  };
+}
+
 // src/step-driver.ts
 function initialWorkflowState(wf) {
   return { workflow: wf.name, cursor: wf.start, outputs: {}, generationIndex: 0 };
@@ -1231,13 +1263,14 @@ var SwarmEngine = class {
   agent() {
     return this.mastra.getAgent(AGENT_KEY);
   }
-  requestContext(ctx) {
+  requestContext(ctx, state) {
     const rc = new import_request_context.RequestContext();
     for (const [k, v] of Object.entries(ctx)) {
       if (v !== void 0) rc.set(k, v);
     }
     rc.set(TOOL_GATE_KEY, this.toolGate);
     if (this.opts.secrets) rc.set(SECRET_RESOLVER_KEY, this.opts.secrets);
+    if (state) rc.set(RUN_STATE_KEY, state);
     return rc;
   }
   /**
@@ -1507,6 +1540,9 @@ var SwarmEngine = class {
     const modelId = this.priceModelId((await this.loadRow(ctx.tenantId, ctx.agentSlug)).modelId ?? "unknown", ctx.tenantId, ctx.agentSlug);
     const workflowDef = input.workflow ? this.opts.workflows?.find((w) => w.name === input.workflow) : this.opts.agentWorkflows?.[ctx.agentSlug];
     if (input.workflow && !workflowDef) throw new Error(`unknown workflow: ${input.workflow}`);
+    if (this.opts.storage.threads) {
+      await this.opts.storage.threads.ensure({ id: ctx.threadId, orgId: ctx.tenantId, userId: ctx.userId });
+    }
     await this.opts.storage.runs.create({
       runId: ctx.runId,
       tenantId: ctx.tenantId,
@@ -1524,8 +1560,17 @@ var SwarmEngine = class {
     const streamed = /* @__PURE__ */ new Set();
     const activity = /* @__PURE__ */ new Map();
     const turnUsage = [];
-    const rc = this.requestContext(ctx);
+    const runState = createRunState();
+    const rc = this.requestContext(ctx, runState);
     if (this.opts.pageContext) attachPageContext(rc, input.context);
+    let outcome = "failed";
+    if (this.opts.onRunStart) {
+      try {
+        await this.opts.onRunStart(ctx, { input, state: runState });
+      } catch (err) {
+        console.error(`[@nightowlsdev/core] onRunStart threw for run ${ctx.runId}:`, err);
+      }
+    }
     const collector = this.opts.telemetry ? new SpanCollector(ctx.runId, () => Date.now(), "run", { agentSlug: ctx.agentSlug }) : null;
     let ts = 0;
     const emit = async (e) => {
@@ -1555,7 +1600,7 @@ var SwarmEngine = class {
       if (workflowDef) {
         const wfMessage = input.message.replace(/^(\[user:[^\]]*\]\s*)+/, "");
         await emit(ev("swarm.message", base(ctx, ts++), { role: "user", text: wfMessage }));
-        yield* this.driveWorkflow(workflowDef, initialWorkflowState(workflowDef), ctx, { message: wfMessage, context: input.context }, {
+        outcome = yield* this.driveWorkflow(workflowDef, initialWorkflowState(workflowDef), ctx, { message: wfMessage, context: input.context }, {
           gov,
           modelIdFor,
           streamed,
@@ -1565,7 +1610,11 @@ var SwarmEngine = class {
           turnUsage,
           nextTs: () => ts++,
           emit,
-          emitTurn
+          emitTurn,
+          segmentIndex: 0,
+          // FR-004: a run segment starts at generation 0
+          state: runState
+          // FR-003: workflow steps' tools see the run's ctx.state
         });
         return;
       }
@@ -1593,23 +1642,14 @@ var SwarmEngine = class {
             const sp = payload.suspendPayload ?? {};
             await recordSuspend(this.opts.storage, ctx, followupId, toolCallId);
             await this.opts.storage.runs.setStatus(ctx.runId, "suspended");
-            await this.opts.storage.runs.saveSnapshot(ctx.runId, { pending: { toolCallId }, genIndex: generationIndex + 1 });
+            await this.opts.storage.runs.saveSnapshot(ctx.runId, { pending: { toolCallId }, genIndex: generationIndex + 1, state: runState.entries() });
             {
               const t = await emitTurn();
               if (t) yield t;
             }
             yield await emit(ev("swarm.status", base(ctx, ts++), { state: "waiting" }));
-            yield await emit(
-              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
-              })
-            );
+            yield await emit(clientActionOrQuestion(ctx, ts++, followupId, toolCallId, sp));
+            outcome = "suspended";
             return;
           }
           if (part?.type === "error") {
@@ -1627,7 +1667,7 @@ var SwarmEngine = class {
             );
             return;
           }
-          for (const e of mapChunk(part, ctx, gov, modelIdFor, () => ts++, streamed, delegateBudgets, activity, gatesApproval, turnUsage)) {
+          for (const e of mapChunk(part, ctx, gov, modelIdFor, () => ts++, streamed, delegateBudgets, activity, gatesApproval, turnUsage, 0)) {
             if (e.type === "swarm.message" || e.type === "swarm.tool_call") {
               lastOutputSlug = e.agentSlug;
               if (this.opts.verifyCompletion) transcript = appendTranscript(transcript, e);
@@ -1644,7 +1684,9 @@ var SwarmEngine = class {
               await this.opts.storage.runs.setStatus(ctx.runId, "suspended");
               await this.opts.storage.runs.saveSnapshot(ctx.runId, {
                 capHit: { message: userMessage, spentUsd: gov.costUsd() },
-                genIndex: generationIndex + 1
+                genIndex: generationIndex + 1,
+                state: runState.entries()
+                // FR-003: persist per-run state across the cap-ask boundary
               });
               {
                 const t = await emitTurn();
@@ -1652,6 +1694,7 @@ var SwarmEngine = class {
               }
               yield await emit(ev("swarm.status", base(ctx, ts++), { state: "waiting" }));
               yield await emit(ev("swarm.question", base(ctx, ts++), capQuestion(ctx, followupId, gov)));
+              outcome = "suspended";
               return;
             }
             await this.opts.storage.runs.setStatus(ctx.runId, "failed");
@@ -1700,6 +1743,7 @@ var SwarmEngine = class {
           if (t) yield t;
         }
         yield await emit(ev("swarm.status", base(ctx, ts++), { state: "done" }));
+        outcome = "done";
       }
     } catch (err) {
       const stage = err instanceof ReserveDenied ? "reserve" : "exception";
@@ -1714,6 +1758,13 @@ var SwarmEngine = class {
       }
       yield await emit(ev("swarm.run_failed", base(ctx, ts++), { stage, message: errMessage(err), retryable: false }));
     } finally {
+      if (this.opts.onRunEnd) {
+        try {
+          await this.opts.onRunEnd(ctx, { state: runState, outcome });
+        } catch (err) {
+          console.error(`[@nightowlsdev/core] onRunEnd threw for run ${ctx.runId}:`, err);
+        }
+      }
       floorAbort.abort();
       await releaseFloor?.();
       await exportSpans(this.opts.telemetry, collector);
@@ -1730,7 +1781,7 @@ var SwarmEngine = class {
     const driver = new StepDriver(wf, {
       nextTs: m.nextTs,
       runAgentStep: (slug, message, genIndex) => this.streamWorkflowAgentStep(slug, message, genIndex, ctx, input, m),
-      runToolStep: (toolName, args) => this.runWorkflowToolStep(toolName, args, ctx),
+      runToolStep: (toolName, args) => this.runWorkflowToolStep(toolName, args, ctx, m.state),
       saveState: (rid, st) => this.opts.storage.runs.saveSnapshot(rid, { workflow: st })
     });
     const it = driver.drive(state, ctx, input);
@@ -1749,7 +1800,7 @@ var SwarmEngine = class {
         const t = await m.emitTurn();
         if (t) yield t;
       }
-      return;
+      return "suspended";
     }
     if (outcome.kind === "failed") {
       await this.opts.storage.runs.setStatus(ctx.runId, "failed");
@@ -1758,7 +1809,7 @@ var SwarmEngine = class {
         if (t) yield t;
       }
       yield await m.emit(ev("swarm.run_failed", base(ctx, m.nextTs()), { stage: outcome.stage, message: outcome.message, retryable: true }));
-      return;
+      return "failed";
     }
     await this.mirrorDelegations(ctx);
     await this.attributeRun(ctx);
@@ -1768,19 +1819,20 @@ var SwarmEngine = class {
       if (t) yield t;
     }
     yield await m.emit(ev("swarm.status", base(ctx, m.nextTs()), { state: "done" }));
+    return "done";
   }
   /** A workflow `agent` step: stream `slug` with `message` (a per-step requestContext so it inherits the agent's
    *  persona/tools/gate/model), reserving + metering through the caller's machinery, returning the final text. */
   async *streamWorkflowAgentStep(slug, message, genIndex, ctx, input, m) {
     await this.guardGeneration({ runId: ctx.runId, tenantId: ctx.tenantId, agentSlug: slug, modelId: m.modelIdFor(slug), generationIndex: genIndex, kind: "run" });
     const sctx = { ...ctx, agentSlug: slug };
-    const stepRc = this.requestContext(sctx);
+    const stepRc = this.requestContext(sctx, m.state);
     if (this.opts.pageContext) attachPageContext(stepRc, input.context);
     const result = await this.agent().stream(message, { runId: ctx.runId, requestContext: stepRc, ...this.memoryOpts(sctx) });
     let text = "";
     for await (const part of result.fullStream) {
       if (part?.type === "step-finish") m.gov.step();
-      for (const e of mapChunk(part, sctx, m.gov, m.modelIdFor, m.nextTs, m.streamed, m.delegateBudgets, m.activity, m.gatesApproval, m.turnUsage)) {
+      for (const e of mapChunk(part, sctx, m.gov, m.modelIdFor, m.nextTs, m.streamed, m.delegateBudgets, m.activity, m.gatesApproval, m.turnUsage, m.segmentIndex)) {
         if (e.type === "swarm.message") text += e.data.delta ?? e.data.text ?? "";
         yield e;
       }
@@ -1788,11 +1840,11 @@ var SwarmEngine = class {
     return { text };
   }
   /** A workflow `tool` step: run the gate-free tool body through `executeToolWithGate` (the engine-owned gate). */
-  async runWorkflowToolStep(toolName, args, ctx) {
+  async runWorkflowToolStep(toolName, args, ctx, state) {
     const skill = this.opts.resolveSkill?.(toolName);
     const exec = skill ? getToolExecutor(skill) : void 0;
     if (!skill || !exec) return { ok: false, error: `unknown tool "${toolName}"` };
-    const toolCtx = { tenantId: ctx.tenantId, userId: ctx.userId, runId: ctx.runId, secrets: bindSecrets(this.opts.secrets, ctx) };
+    const toolCtx = { tenantId: ctx.tenantId, userId: ctx.userId, runId: ctx.runId, secrets: bindSecrets(this.opts.secrets, ctx), state };
     return executeToolWithGate({
       ev: toolPreCallEvent({ runId: ctx.runId, tenantId: ctx.tenantId, agentSlug: ctx.agentSlug, toolName, origin: skill.origin ?? "first-party", needsApproval: this.gatesApproval(toolName), args }),
       gate: this.toolGate,
@@ -1802,6 +1854,7 @@ var SwarmEngine = class {
   async *resume(args, ctx) {
     const snap = await this.opts.storage.runs.loadSnapshot(ctx.tenantId, args.runId);
     if (!snap) throw new Error(`no suspended run: ${args.runId}`);
+    const resumedState = createRunState(snap.state ?? void 0);
     const generationIndex = typeof snap.genIndex === "number" ? snap.genIndex : 1;
     const capHit = snap.capHit;
     await this.opts.storage.markFollowupAnswered?.(args.followupId, ctx.tenantId);
@@ -1835,6 +1888,7 @@ var SwarmEngine = class {
       turnEmitted = true;
       return emit(turnUsageEvent(rctx, ts++, turnUsage, generationIndex));
     };
+    let resumeOutcome = "failed";
     try {
       if (!releaseFloor) {
         const held = await this.floor.holder(floorKey);
@@ -1866,7 +1920,7 @@ var SwarmEngine = class {
           wfState.outputs[wfState.pending.stepId] = args.answer;
           wfState.pending = void 0;
         }
-        yield* this.driveWorkflow(wf, wfState, rctx, { message: "", context: args.context }, {
+        resumeOutcome = yield* this.driveWorkflow(wf, wfState, rctx, { message: "", context: args.context }, {
           gov,
           modelIdFor,
           streamed,
@@ -1876,7 +1930,11 @@ var SwarmEngine = class {
           turnUsage,
           nextTs: () => ts++,
           emit,
-          emitTurn
+          emitTurn,
+          segmentIndex: generationIndex,
+          // FR-004: a resume segment starts at the snapshot's genIndex
+          state: resumedState
+          // FR-003: workflow steps' tools see the restored ctx.state
         });
         return;
       }
@@ -1895,7 +1953,7 @@ var SwarmEngine = class {
         );
         return;
       }
-      const rc = this.requestContext({ ...ctx, runId: args.runId });
+      const rc = this.requestContext({ ...ctx, runId: args.runId }, resumedState);
       if (this.opts.pageContext) attachPageContext(rc, args.context);
       await this.guardGeneration({ runId: args.runId, tenantId: ctx.tenantId, agentSlug: ctx.agentSlug, modelId, generationIndex, kind: "resume" });
       let resumeNudges = 0;
@@ -1927,22 +1985,14 @@ var SwarmEngine = class {
             const sp = payload.suspendPayload ?? {};
             await recordSuspend(this.opts.storage, rctx, followupId, toolCallId);
             await this.opts.storage.runs.setStatus(args.runId, "suspended");
-            await this.opts.storage.runs.saveSnapshot(args.runId, { pending: { toolCallId }, genIndex: generationIndex + 1 });
+            await this.opts.storage.runs.saveSnapshot(args.runId, { pending: { toolCallId }, genIndex: generationIndex + 1, state: resumedState.entries() });
             {
               const t = await emitTurn();
               if (t) yield t;
             }
             yield await emit(ev("swarm.status", base(rctx, ts++), { state: "waiting" }));
-            yield await emit(
-              ev("swarm.question", base(rctx, ts++), {
-                followupId,
-                toolCallId,
-                to: sp.to ?? "user",
-                from: sp.asker || rctx.agentSlug,
-                prompt: sp.prompt ?? "",
-                field: sp.field
-              })
-            );
+            yield await emit(clientActionOrQuestion(rctx, ts++, followupId, toolCallId, sp));
+            resumeOutcome = "suspended";
             return;
           }
           if (part?.type === "error") {
@@ -1961,7 +2011,7 @@ var SwarmEngine = class {
             return;
           }
           collectSpans(collector, part, modelId, gov);
-          for (const e of mapChunk(part, rctx, gov, modelIdFor, () => ts++, streamed, delegateBudgets, activity, gatesApproval, turnUsage)) {
+          for (const e of mapChunk(part, rctx, gov, modelIdFor, () => ts++, streamed, delegateBudgets, activity, gatesApproval, turnUsage, generationIndex)) {
             if (e.type === "swarm.message" || e.type === "swarm.tool_call") {
               lastOutputSlug = e.agentSlug;
               if (this.opts.verifyCompletion) transcript = appendTranscript(transcript, e);
@@ -1977,7 +2027,9 @@ var SwarmEngine = class {
               await this.opts.storage.runs.setStatus(args.runId, "suspended");
               await this.opts.storage.runs.saveSnapshot(args.runId, {
                 capHit: { message: capHit.message, spentUsd: gov.costUsd() },
-                genIndex: generationIndex + 1
+                genIndex: generationIndex + 1,
+                state: resumedState.entries()
+                // FR-003: persist per-run state across the cap-ask boundary
               });
               {
                 const t = await emitTurn();
@@ -1985,6 +2037,7 @@ var SwarmEngine = class {
               }
               yield await emit(ev("swarm.status", base(rctx, ts++), { state: "waiting" }));
               yield await emit(ev("swarm.question", base(rctx, ts++), capQuestion(rctx, followupId, gov)));
+              resumeOutcome = "suspended";
               return;
             }
             await this.opts.storage.runs.setStatus(args.runId, "failed");
@@ -2031,6 +2084,7 @@ var SwarmEngine = class {
           if (t) yield t;
         }
         yield await emit(ev("swarm.status", base(rctx, ts++), { state: "done" }));
+        resumeOutcome = "done";
       }
     } catch (err) {
       const stage = err instanceof ReserveDenied ? "reserve" : "exception";
@@ -2045,6 +2099,13 @@ var SwarmEngine = class {
       }
       yield await emit(ev("swarm.run_failed", base(rctx, ts++), { stage, message: errMessage(err), retryable: false }));
     } finally {
+      if (this.opts.onRunEnd) {
+        try {
+          await this.opts.onRunEnd(ctx, { state: resumedState, outcome: resumeOutcome });
+        } catch (err) {
+          console.error(`[@nightowlsdev/core] onRunEnd threw for resume ${args.runId}:`, err);
+        }
+      }
       floorAbort.abort();
       await releaseFloor?.();
       await exportSpans(this.opts.telemetry, collector);
@@ -2064,6 +2125,26 @@ function errMessage(err) {
 function base(ctx, ts) {
   return { runId: ctx.runId, agentSlug: ctx.agentSlug, ts };
 }
+function clientActionOrQuestion(ctx, ts, followupId, toolCallId, sp) {
+  if (sp.clientAction) {
+    return ev("swarm.client_action", base(ctx, ts), {
+      followupId,
+      toolCallId,
+      tool: sp.clientAction.tool,
+      input: sp.clientAction.input,
+      needsApproval: sp.clientAction.needsApproval ?? false,
+      from: sp.asker || ctx.agentSlug
+    });
+  }
+  return ev("swarm.question", base(ctx, ts), {
+    followupId,
+    toolCallId,
+    to: sp.to ?? "user",
+    from: sp.asker || ctx.agentSlug,
+    prompt: sp.prompt ?? "",
+    field: sp.field
+  });
+}
 var CAP_FOLLOWUP_SUFFIX = "cap";
 function capQuestion(ctx, followupId, gov) {
   const spent = gov.costUsd();
@@ -2159,7 +2240,7 @@ async function recordSuspend(storage, ctx, followupId, toolCallId) {
   }
   await storage.recordSuspend?.(ctx.runId, ctx.tenantId, followupId, toolCallId);
 }
-function mapChunk(part, ctx, gov, modelIdFor, nextTs, streamed, delegateBudgets, activity, gatesApproval, turnUsage) {
+function mapChunk(part, ctx, gov, modelIdFor, nextTs, streamed, delegateBudgets, activity, gatesApproval, turnUsage, segmentIndex) {
   const p = part.payload ?? {};
   const modelId = modelIdFor(ctx.agentSlug);
   const act = (slug) => {
@@ -2229,8 +2310,9 @@ function mapChunk(part, ctx, gov, modelIdFor, nextTs, streamed, delegateBudgets,
         gov.addUsage(modelId, u);
         delegateBudgets?.addUsage(ctx.agentSlug, modelId, u);
         const cost = gov.costOf(modelId, u);
+        const generationId = `${ctx.runId}:${segmentIndex}:${turnUsage.length}`;
         turnUsage.push({ slug: ctx.agentSlug, breakdown: u, cost });
-        return [ev("swarm.usage", base(ctx, nextTs()), { slug: ctx.agentSlug, modelId, breakdown: u, cost })];
+        return [ev("swarm.usage", base(ctx, nextTs()), { slug: ctx.agentSlug, modelId, breakdown: u, cost, generationId })];
       }
       return [];
     }
@@ -2241,7 +2323,7 @@ function mapChunk(part, ctx, gov, modelIdFor, nextTs, streamed, delegateBudgets,
       const inner = p.output;
       if (!inner || typeof inner.type !== "string") return [];
       if (inner.type === "text-delta") streamed.add(p.toolCallId);
-      return mapChunk(inner, { ...ctx, agentSlug: subSlug }, gov, modelIdFor, nextTs, streamed, delegateBudgets, activity, gatesApproval, turnUsage);
+      return mapChunk(inner, { ...ctx, agentSlug: subSlug }, gov, modelIdFor, nextTs, streamed, delegateBudgets, activity, gatesApproval, turnUsage, segmentIndex);
     }
     case "tool-error": {
       const name = p.toolName ?? "";
@@ -2434,7 +2516,11 @@ function defineTool(spec) {
         tenantId,
         userId,
         runId,
-        secrets: bindSecrets(resolver, scopedCtx)
+        secrets: bindSecrets(resolver, scopedCtx),
+        // FR-003: the per-run state handle the engine put on the rc (same object across the run's tool calls +
+        // delegated sub-agents). Absent on a raw test stream built without the engine — then `ctx.state` is
+        // undefined, unchanged from prior behaviour.
+        state: rc?.get?.(RUN_STATE_KEY)
       };
       const run = () => spec.execute(inputData, ctx);
       const agentCtx = context?.agent;
@@ -2476,6 +2562,48 @@ function deriveAsker(agentCtx, rc) {
   if (agentId.startsWith("swarm-sub-")) return agentId.slice("swarm-sub-".length);
   return rc?.get?.("agentSlug") ?? "";
 }
+var CLIENT_ACTION_SUSPEND_SCHEMA = import_zod4.z.object({
+  clientAction: import_zod4.z.object({ tool: import_zod4.z.string(), input: import_zod4.z.any(), needsApproval: import_zod4.z.boolean().optional() }),
+  asker: import_zod4.z.string().optional()
+});
+var CLIENT_ACTION_RESUME_SCHEMA = import_zod4.z.object({ answer: import_zod4.z.any() });
+var ClientToolError = class extends Error {
+  constructor(toolName, reason) {
+    super(reason ? `client tool ${toolName} failed: ${reason}` : `client tool ${toolName} failed`);
+    this.name = "ClientToolError";
+  }
+};
+function defineClientTool(spec) {
+  const needsApproval = spec.needsApproval ?? false;
+  const mastraTool = (0, import_tools4.createTool)({
+    id: spec.name,
+    description: spec.description ?? spec.name,
+    inputSchema: spec.inputSchema,
+    outputSchema: spec.outputSchema,
+    suspendSchema: CLIENT_ACTION_SUSPEND_SCHEMA,
+    resumeSchema: CLIENT_ACTION_RESUME_SCHEMA,
+    execute: async (inputData, context) => {
+      const rc = context?.requestContext;
+      const agentCtx = context?.agent;
+      if (agentCtx?.resumeData !== void 0 && agentCtx.resumeData !== null) {
+        const answer = agentCtx.resumeData.answer;
+        if (answer && typeof answer === "object" && "error" in answer && answer.error) {
+          throw new ClientToolError(spec.name, String(answer.error));
+        }
+        return answer && typeof answer === "object" && "output" in answer ? answer.output : answer;
+      }
+      if (typeof agentCtx?.suspend !== "function") {
+        throw new ClientToolError(spec.name, "client tools require an agent-driven run (no server execute)");
+      }
+      const asker = deriveAsker(agentCtx, rc);
+      await agentCtx.suspend({ clientAction: { tool: spec.name, input: inputData, needsApproval }, asker });
+      throw new ClientToolError(spec.name, "awaiting client action");
+    }
+  });
+  const handle = { name: spec.name, needsApproval, origin: "first-party" };
+  MASTRA.set(handle, mastraTool);
+  return handle;
+}
 function __getMastraTool(t) {
   return MASTRA.get(t);
 }
@@ -2802,7 +2930,10 @@ function defineSwarm(cfg) {
     secrets: cfg.secrets,
     // SP3: best-effort per-event observer (metering debit/settle) — transport-agnostic, fired in run + resume.
     onEvent: cfg.onEvent,
-    verifyCompletion: cfg.verifyCompletion
+    verifyCompletion: cfg.verifyCompletion,
+    // FR-003: per-run lifecycle hooks (seed `ctx.state` at run start, drain at run end).
+    onRunStart: cfg.onRunStart,
+    onRunEnd: cfg.onRunEnd
   });
   return { engine };
 }
@@ -2826,6 +2957,8 @@ var InMemoryStorage = class {
   heads = /* @__PURE__ */ new Map();
   // key: tenantId:slug -> version
   pads = /* @__PURE__ */ new Map();
+  threadRows = /* @__PURE__ */ new Map();
+  // FR-009
   seedAgent(v, tenantId = "default") {
     this.agentRows.set(`${tenantId}:${v.slug}:${v.version}`, v);
     this.heads.set(`${tenantId}:${v.slug}`, v.version);
@@ -2909,6 +3042,18 @@ var InMemoryStorage = class {
     },
     getWaitpoint: async (followupId) => this.waitpoints.get(followupId) ?? null
   };
+  // FR-009: idempotent thread-row creation. The dev store has no FK, so `messages.append` never threw `unknown
+  // thread` here — this implements the contract so the engine's run-start ensure works against the in-memory store
+  // too, and a host can read back the recorded thread (getThread) in tests.
+  threads = {
+    ensure: async ({ id, orgId, userId, projectId }) => {
+      if (!this.threadRows.has(id)) this.threadRows.set(id, { id, orgId, userId, projectId });
+    }
+  };
+  /** Test/host helper: read a recorded thread row. */
+  getThread(id) {
+    return this.threadRows.get(id);
+  }
   messages = {
     append: async (m) => {
       this.msgs.push(m);
@@ -2948,6 +3093,69 @@ var InMemoryStorage = class {
   };
 };
 
+// src/run-agent.ts
+function uid() {
+  return globalThis.crypto?.randomUUID?.() ?? `id-${Math.random().toString(36).slice(2)}-${Date.now().toString(36)}`;
+}
+async function drainTrajectory(stream) {
+  const events = [];
+  let output = "";
+  for await (const e of stream) {
+    events.push(e);
+    if (e.type === "swarm.message") {
+      const d = e.data;
+      if (d.role === "assistant") output += d.delta ?? d.text ?? "";
+    }
+  }
+  return { events, output };
+}
+async function runToTrajectory(target, input, ctx) {
+  const engine = "engine" in target ? target.engine : target;
+  const runInput = typeof input === "string" ? { message: input } : input;
+  const full = ephemeralCtx(ctx?.agentSlug ?? "agent", ctx);
+  return drainTrajectory(engine.run(runInput, full));
+}
+function ephemeralCtx(agentSlug, over) {
+  return {
+    tenantId: over?.tenantId ?? "default",
+    userId: over?.userId ?? "local",
+    agentSlug: over?.agentSlug ?? agentSlug,
+    runId: over?.runId ?? uid(),
+    threadId: over?.threadId ?? uid(),
+    ...over?.agentVersion !== void 0 ? { agentVersion: over.agentVersion } : {}
+  };
+}
+function buildSingleAgentSwarm(def, opts) {
+  const t = opts.models?.tier;
+  const tierAllow = t ? [t.tiers.swift, ...t.tiers.genius ? [t.tiers.genius] : []] : [];
+  const allow = opts.models?.allow ?? [def.head.modelId, ...tierAllow];
+  const storage = opts.storage ?? new InMemoryStorage();
+  const cfg = {
+    storage,
+    agents: [def],
+    models: { allow, ...opts.models?.tier ? { tier: opts.models.tier } : {} },
+    modelFactory: opts.modelFactory,
+    cost: { maxSteps: 50, maxCostUsd: 10, ...opts.cost },
+    ...opts.telemetry !== void 0 ? { telemetry: opts.telemetry } : {},
+    ...opts.memory !== void 0 ? { memory: opts.memory } : {},
+    ...opts.hooks !== void 0 ? { hooks: opts.hooks } : {},
+    ...opts.toolApproval !== void 0 ? { toolApproval: opts.toolApproval } : {},
+    ...opts.secrets !== void 0 ? { secrets: opts.secrets } : {},
+    ...opts.onEvent !== void 0 ? { onEvent: opts.onEvent } : {},
+    ...opts.onRunStart !== void 0 ? { onRunStart: opts.onRunStart } : {},
+    ...opts.onRunEnd !== void 0 ? { onRunEnd: opts.onRunEnd } : {},
+    ...opts.pageContext !== void 0 ? { pageContext: opts.pageContext } : {},
+    ...opts.mastraStore !== void 0 ? { mastraStore: opts.mastraStore } : {}
+  };
+  return defineSwarm(cfg);
+}
+async function runAgent(def, input, opts) {
+  const swarm = buildSingleAgentSwarm(def, opts);
+  const runInput = typeof input === "string" ? { message: input } : input;
+  const ctx = ephemeralCtx(def.head.slug, { ...opts.ctx, agentSlug: def.head.slug });
+  return drainTrajectory(swarm.engine.run(runInput, ctx));
+}
+
 // src/auth.ts
 var customAuth = (fn) => ({ authenticate: fn });
 
@@ -2988,6 +3196,7 @@ var VERSION = "0.0.0";
   ASK_TOOL_NAME,
   AgentMutationForbidden,
   CapturingExporter,
+  ClientToolError,
   CostGovernor,
   DEFAULT_READ_ONLY_TOOLS,
   DelegateBudgets,
@@ -3006,6 +3215,7 @@ var VERSION = "0.0.0";
   allowListModelProvider,
   ask,
   assertActorMayMutateDefinition,
+  buildSingleAgentSwarm,
   buildSkillResolver,
   composePolicyPrompt,
   composeSystemPrompt,
@@ -3013,11 +3223,13 @@ var VERSION = "0.0.0";
   containerFloor,
   createHookDispatcher,
   createInMemoryRateLimitStore,
+  createRunState,
   customAuth,
   customTelemetry,
   decideFixedWindow,
   defineAgent,
   defineBundle,
+  defineClientTool,
   defineHook,
   defineRule,
   defineSkill,
@@ -3025,6 +3237,7 @@ var VERSION = "0.0.0";
   defineTool,
   defineWorkflow,
   deny,
+  drainTrajectory,
   ev,
   isEvent,
   isTierSentinel,
@@ -3033,6 +3246,8 @@ var VERSION = "0.0.0";
   rateConfig,
   resolveTelemetry,
   resolveTier,
+  runAgent,
+  runToTrajectory,
   sumBreakdowns,
   sumTurnUsage,
   tierModelId,