@minpeter/pss-runtime 0.1.0-next.1 → 0.1.0-next.3

package/README.md

@@ -10,12 +10,31 @@ Minimal, platform-agnostic agent runtime with keyed sessions, synchronized
 ## Core DX
 
 ```ts
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
 import { Agent } from "@minpeter/pss-runtime";
-import { createYourLanguageModel } from "...";
+import { createEnv } from "@t3-oss/env-core";
+import { config as loadEnv } from "dotenv";
+import { z } from "zod";
+
+loadEnv({ path: ".env", quiet: true, override: true });
+const env = createEnv({
+  runtimeEnv: process.env,
+  server: {
+    AI_API_KEY: z.string().trim().min(1),
+    AI_BASE_URL: z.url().trim().default("https://apis.opengateway.ai/v1"),
+    AI_MODEL: z.string().trim().min(1).default("minimax/MiniMax-M2.7"),
+  },
+});
+
+const provider = createOpenAICompatible({
+  name: "custom",
+  apiKey: env.AI_API_KEY,
+  baseURL: env.AI_BASE_URL,
+});
 
 const agent = new Agent({
   instructions: "Answer briefly.",
-  model: createYourLanguageModel(),
+  model: provider(env.AI_MODEL),
 });
 
 const run = await agent.send("Hello");
@@ -30,6 +49,23 @@ consume the events for the run to progress. This is what lets code react to
 `turn-start`, `step-start`, and `step-end` before the next model snapshot is
 created.
 
+`model` is the single public constructor key for model execution. Pass an AI SDK
+`LanguageModel` for the managed runtime path with `instructions` and `tools`, or
+pass a custom `RuntimeLlm` function when you want to own the model
+adapter yourself:
+
+```ts
+import { Agent, type RuntimeLlm } from "@minpeter/pss-runtime";
+
+const runtimeModel: RuntimeLlm = async ({ history }) => [
+  { role: "assistant", content: `Seen ${history.length} messages.` },
+];
+
+const agent = new Agent({
+  model: runtimeModel,
+});
+```
+
 Per-key conversations use `session(key)`:
 
 ```ts
@@ -80,74 +116,180 @@ The public transcript protocol is `AgentEvent`: live runs emit runtime-defined
 events through `run.events()`. Provider/model message history is internal
 continuation state, not a public history API.
 
-## Subagents
+## Delegation
 
-Compose specialist agents by constructing them first and passing them as an
-array. Top-level agents may omit metadata, but agents used as subagents need a
-stable `name` and `description` so the runtime can expose clear model-facing
-delegate tools.
+Delegation is app-owned. Build ordinary tools that call another `Agent`,
+`session.send(...)`, `session.notify(...)`, or host-owned background work, then
+return the compact result shape your product wants the model to see.
 
 ```ts
-const researcher = new Agent({
-  name: "researcher",
-  description: "Researches facts and returns concise evidence.",
+const reader = new Agent({
+  instructions: "Read knowledge-base files and cite paths.",
   model,
-  instructions: "Research facts and return concise evidence.",
+  namespace: "reader",
 });
 
 const coordinator = new Agent({
+  instructions: "Coordinate work and delegate knowledge-base reads.",
   model,
-  instructions: "Coordinate work and delegate when useful.",
-  subagents: [researcher],
+  namespace: "coordinator",
+  tools: {
+    delegate_to_reader: tool({
+      description: "Ask the reader agent to inspect the knowledge base.",
+      execute: async ({ prompt }) => {
+        const run = await reader.session("kb").send(prompt);
+        const text: string[] = [];
+        for await (const event of run.events()) {
+          if (event.type === "assistant-text") {
+            text.push(event.text);
+          }
+        }
+        return { result: text.join("\n") };
+      },
+      inputSchema,
+    }),
+  },
 });
 ```
 
-For each subagent, the parent model receives a generated
-`delegate_to_<name>` tool. The tool accepts `prompt`, optional `description`,
-optional `sessionKey` suffix, and `run_in_background`. A provided `sessionKey`
-is always scoped under the parent session and subagent name; the model cannot
-select an arbitrary child session key. Omitting `run_in_background` defaults to
-blocking behavior and returns compact child text, not the full child event
-stream.
+For background delegation, let your host own task ids, scheduling, output
+storage, and notification resume. The runtime provides generic execution stores,
+notifications, `Agent.resume(...)`, and `run.events()`; it does not generate
+delegation tools or own child-agent lifecycle semantics. See
+the sync and background example packages for app-owned blocking and background
+delegation patterns.
+
+## Plugins
+
+Pass `plugins: [...]` on `Agent` to observe or intercept runtime events. Each
+plugin exposes one handler:
 
 ```ts
-delegate_to_researcher({
-  prompt: "Find the current release notes and summarize the evidence.",
+import type { AgentPlugin } from "@minpeter/pss-runtime";
+import { Agent } from "@minpeter/pss-runtime";
+
+const tracePlugin: AgentPlugin = {
+  name: "trace",
+  on: ({ event }) => {
+    if (event.type === "turn-end") {
+      console.log("turn finished");
+    }
+  },
+};
+
+const agent = new Agent({
+  model,
+  plugins: [tracePlugin],
 });
 ```
 
-When the model sets `run_in_background: true`, the parent run can finish while
-the child keeps working. The launch result includes a `bg_...` `task_id`. A
-compact runtime reminder is queued for the parent when the child finishes, and
-the model can retrieve the result with `background_output`.
+### Observe vs intercept
+
+For most events, `on` is observe-only: return nothing (or `{ action: "continue" }`)
+and the runtime emits the event unchanged.
+
+Three input event types support intercept returns:
+
+- `user-text`
+- `user-message`
+- `runtime-input`
+
+Return one of:
+
+- `{ action: "continue" }` — emit the current event (default when omitted)
+- `{ action: "transform", event }` — emit a replacement input event
+- `{ action: "handled" }` — skip emit; for `session.send`, close the run without
+  starting a turn
+
+Plugins run in registration order. Each `transform` updates the event seen by
+later plugins, so transforms chain sequentially.
+
+### Input `meta.source`
+
+The runtime attaches `meta` on input events at API boundaries. Plugins can route
+on `event.meta?.source`:
+
+| `source` | Boundary |
+|----------|----------|
+| `send` | `session.send()` / `agent.send()` |
+| `steer` | `session.steer()` and drained steering queue |
+| `notify` | `session.notify()` runtime input |
+| `delegate` | parent `delegate_to_*` child `session.send()` |
+
+`meta` appears on `run.events()` for input events but is stripped before session
+history persistence and model mapping. It never reaches the LLM prompt.
+
+### Delegate prompt wrapping
+
+Child agents receive delegated prompts with `meta.source === "delegate"`. Wrap or
+rewrite them with a plugin instead of agent-level prompt shims:
 
 ```ts
-delegate_to_researcher({
-  prompt: "Compare the API designs.",
-  run_in_background: true,
-});
+import type { AgentPlugin, UserText } from "@minpeter/pss-runtime";
+import { Agent } from "@minpeter/pss-runtime";
+
+const pokeTagsPlugin: AgentPlugin = {
+  name: "poke-tags",
+  on: ({ event }) => {
+    if (event.type !== "user-text" || event.meta?.source !== "delegate") {
+      return;
+    }
+
+    const text =
+      typeof event.text === "string" ? event.text : event.text.join("\n");
+
+    return {
+      action: "transform",
+      event: {
+        ...event,
+        text: `<poke>\n${text}\n</poke>`,
+      } satisfies UserText,
+    };
+  },
+};
 
-background_output({ task_id: "bg_...", block: true });
-background_cancel({ task_id: "bg_..." });
+const executionAgent = new Agent({
+  namespace: "execution",
+  plugins: [pokeTagsPlugin],
+  model,
+});
 ```
 
-The parent model context stays compact by default: completion reminders include
-the task id, subagent name, description, and retrieval instruction. Full child
-traces are not injected into the parent transcript by default. Background jobs
-run in task-scoped child sessions, and retrieved completed jobs are forgotten
-after `background_output` returns.
+The parent coordinator stays unchanged; only the nested child agent carries the
+plugin.
+
+### Migration
 
-## Send and Steer
+- **`plugins[].events.on`** — deprecated. Use top-level `plugins[].on`. The legacy
+  handler still receives every event but intercept returns are ignored (observe-only).
+- **`wrapDelegatePrompt`** — removed. Use a child `plugins[].on` handler that checks
+  `meta.source === "delegate"` and returns `transform`, as above.
+
+## Send, Host Resume, and Steer
 
 Use `session.send(input)` for a new user turn. If a run is already active, the
-turn is queued until the active run finishes. Use `session.steer(input)` when the
-input should steer the active run; if no run is active, it starts a normal run.
+turn is queued until the active run finishes. Use `session.steer(input)` when
+the input should steer the active run; if no run is active, it starts a normal
+run.
+
+Durable hosts resume completed background work by writing a notification record
+and calling `agent.resume(notificationRunId)`. The resume call claims the
+notification idempotently through its durable run id and returns one `AgentRun`,
+or `null` when a duplicate queue/alarm delivery already claimed it.
+
+Runtime-originated input is delivered through the host notification inbox and
+internal plugin paths. App code should use `session.send()`, `session.steer()`,
+or `agent.resume(runId)` for host-scheduled durable work.
+
+Each accepted call returns one `AgentRun`. Drain that run's `events()` stream to
+observe the turn; each `AgentRun.events()` stream is single-consumer.
 
-Both APIs accept the same input shapes: strings, arrays of strings,
+Input APIs accept the same input shapes: strings, arrays of strings,
 `{ type: "user-text", text }`, and multipart `{ type: "user-message", content }`
-values. Active steering emits `runtime-input` events. A `runtime-input` is
-runtime/API-originated input mapped internally to the model's user role. It is
-distinct from human-origin `user-text` and `user-message` events.
+values. Active steering and host resume input emit `runtime-input` events. A
+`runtime-input` is runtime/API-originated input mapped internally to the model's
+user role. It is distinct from human-origin `user-text` and `user-message`
+events.
 
 Runtime input windows are tied to synchronized events:
 
@@ -188,6 +330,10 @@ Stored session state is an opaque, versioned runtime snapshot for continuation.
 Do not inspect it as a replay log; exact replay should be modeled separately as
 an `AgentEvent` log if that capability is added later.
 
+`SessionStore` is snapshot-only. It does not own background task ids, run
+leases, checkpoints, notification inbox state, or scheduling. Those live on the
+optional `host` execution contract.
+
 Custom stores own version generation. `load(key)` returns the opaque `state` with
 the store-minted `version`; `commit(key, { state }, { expectedVersion })` receives
 state only and should reject stale versions by returning `{ ok: false, reason:
@@ -196,37 +342,89 @@ new version to the runtime. `delete(key)` removes the persisted session for that
 key.
 
 ```ts
-import type { SessionStore } from "@minpeter/pss-runtime";
 import { MemorySessionStore } from "@minpeter/pss-runtime/session-store/memory";
 
 const agent = new Agent({
-  model,
-  sessions: {
-    namespace: "support-agent",
-    store: new MemorySessionStore(), // default when omitted
+  host: {
+    sessionStore: new MemorySessionStore(), // default when omitted
   },
+  model,
+  namespace: "support-agent",
 });
 ```
 
-For durable sessions, use the exported file POC. Set a stable `namespace` when
-subagents also use durable stores, so reconstructed agents map the same parent
-session and child `sessionKey` suffixes back to the same child transcripts:
+For durable sessions, use the exported file POC. Set a stable `namespace` so
+reconstructed agents map the same app-owned session keys back to the same
+transcripts:
 
 ```ts
 import { FileSessionStore } from "@minpeter/pss-runtime/session-store/file";
 
 const agent = new Agent({
-  model,
-  sessions: {
-    namespace: "support-agent",
-    store: new FileSessionStore(".pss/sessions"),
+  host: {
+    sessionStore: new FileSessionStore(".pss/sessions"),
   },
+  model,
+  namespace: "support-agent",
 });
 ```
 
-## Future adapter boundary: Cloudflare multi-user DX
+Hosts that need durable runs pass `host:` into `Agent`. The execution subpath
+keeps the durable surface split by responsibility, so hosts can implement only
+the capabilities they need: `SessionHost`, `RunHost`, `CheckpointHost`,
+`EventHost`, `NotificationHost`, `BackgroundSchedulerHost`, and
+`ExecutionTransactionHost`. `ExecutionHost` remains the aggregate contract for
+in-process or full-store hosts, while `DurableBackgroundHost` and
+`DurableNotificationResumeHost` describe the smaller durable surfaces required
+for background scheduling and notification resume.
+
+```ts
+import { Agent } from "@minpeter/pss-runtime";
+import {
+  createInMemoryExecutionHost,
+  type DurableBackgroundHost,
+  type ExecutionHost,
+} from "@minpeter/pss-runtime/execution";
+
+const host = createInMemoryExecutionHost();
+
+const agent = new Agent({
+  host,
+  model,
+  namespace: "support-agent",
+});
+
+const durableHost: DurableBackgroundHost = {
+  capabilities: {},
+  backgroundScheduler,
+  checkpointStore,
+  eventStore,
+  notificationInbox,
+  runStore,
+  sessionStore,
+  transaction,
+};
+```
+
+## Supported Deployment Shapes
+
+The runtime supports both long-running Node.js processes and edge hosts that
+reconstruct runtime objects between turns. The same public DX stays centered on
+`new Agent({ model, tools, host })`; host-specific durability and scheduling live
+behind the `host` boundary.
+
+Long-running Node.js can keep an `Agent` and `SessionHandle` alive across turns.
+`FileSessionStore` persists session snapshots only; app-owned background work
+needs its own durable task/output storage if it must survive process restarts.
+
+Cloudflare Durable Objects and similar edge hosts should reconstruct `Agent`
+objects per turn and persist opaque session state through a durable
+`sessionStore`.
+Use `@minpeter/pss-runtime/cloudflare` for the packaged Cloudflare Durable
+Object adapter. See the sync example package for blocking app-owned delegation
+and the background example package for durable background delegation in a local
+interactive CLI.
 
-Cloudflare Durable Objects are a future adapter target, not a runtime dependency.
 The same core API supports room/user/session routing through stable session keys.
 
 Recommended key patterns:
@@ -235,6 +433,37 @@ Recommended key patterns:
 - Per-user memory inside room: `room:<roomId>:user:<userId>`
 - Ticketed workspace flows: `tenant:<tenantId>:ticket:<ticketId>`
 
-In a Durable Object, map the `SessionStore` contract to `ctx.storage` so DO storage is
-durable across hibernation/restores, while in-memory state remains request-local.
-Do not store canonical agent session state in memory attachments.
+In a Durable Object, map the execution store contract to `ctx.storage` so DO
+storage is durable across hibernation/restores, while in-memory state remains
+request-local. Do not store canonical agent session or run state in memory
+attachments.
+
+Durable background workflows require host-owned task ids, attempts, leases,
+checkpoints, cancellation, scheduling, session snapshots, and completion
+notifications. The Cloudflare adapter persists scheduled runs and session
+prompts, sets alarms, and resumes work through `Agent.resume(...)`.
+
+## Checkpoints and Cancellation
+
+Resume is safe only at committed boundaries. Durable hosts can checkpoint before
+and after model steps, around notifications, before child run creation, when a
+child link is committed, and when a run suspends. If a process is killed inside a
+provider call or unsafe tool execution, resume rolls back to the last committed
+checkpoint and may re-enter the operation.
+
+When `Agent` receives an `ExecutionHost`, high-level model turns create a
+`user-turn` run record and thread tool execution context into managed model
+calls. Tools are checkpointed before and after execution and receive stable
+`attempt`, `idempotencyKey`, `retryPolicy`, `signal`, and public `toolCallId`
+values. The `@minpeter/pss-runtime/execution` entrypoint also exposes the same
+low-level tool execution checkpoint types for custom resume runners built
+directly on `createLlm`.
+
+These checkpoints are rollback boundaries, not a complete host adapter by
+themselves. Edge hosts still need durable scheduling, leases, resume workers,
+and notification resume handling; externally visible side-effect tools still need
+idempotent execution or a manual recovery flow.
+
+Cancellation is persisted before aborting active work. `delete()` and `dispose()`
+stop the current session's in-process work; durable hosts remain responsible for
+any app-owned background run cancellation, cleanup, and notification policy.

package/dist/agent-host-session-store.js

@@ -0,0 +1,10 @@
+import { sessionHost } from "./execution/host.js";
+import { MemorySessionStore } from "./session/store/memory.js";
+//#region src/agent-host-session-store.ts
+function sessionStoreForHost(host) {
+	return sessionHost(host).sessionStore ?? new MemorySessionStore();
+}
+//#endregion
+export { sessionStoreForHost };
+
+//# sourceMappingURL=agent-host-session-store.js.map

package/dist/agent-host-session-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-host-session-store.js","names":[],"sources":["../src/agent-host-session-store.ts"],"sourcesContent":["import { sessionHost } from \"./execution/host\";\nimport type { AgentHost } from \"./execution/types\";\nimport { MemorySessionStore } from \"./session/store/memory\";\nimport type { SessionStore } from \"./session/store/types\";\n\nexport function sessionStoreForHost(host: AgentHost): SessionStore {\n  return sessionHost(host).sessionStore ?? new MemorySessionStore();\n}\n"],"mappings":";;;AAKA,SAAgB,oBAAoB,MAA+B;CACjE,OAAO,YAAY,IAAI,EAAE,gBAAgB,IAAI,mBAAmB;AAClE"}

package/dist/agent-loop.js

@@ -1,39 +1,29 @@
 import { modelMessageToAgentEvents } from "./session/mapping.js";
 //#region src/agent-loop.ts
-async function runAgentLoop({ emit, history, hooks, llm, signal = new AbortController().signal }) {
-	let stepIndex = 0;
+async function runAgentLoop({ captureObserverEvents = captureNoObserverEvents, emit, history, llm, signal = new AbortController().signal, toolExecution }) {
 	while (true) {
-		if (signal.aborted) return "aborted";
-		await hooks?.beforeStep?.({
-			history: history.modelSnapshot(),
-			signal,
-			stepIndex
-		});
 		if (signal.aborted) return "aborted";
 		if (await emitBoundary({
 			emit,
 			event: { type: "step-start" },
 			signal
 		}) === "aborted") return "aborted";
-		const output = await readLlmOutput({
+		const capturedOutput = await captureObserverEvents(() => readLlmOutput({
 			history,
 			llm,
-			signal
-		});
+			signal,
+			toolExecution
+		}));
+		const output = capturedOutput.value;
 		if (output === "aborted") return "aborted";
-		const result = appendStepOutput({
+		const result = await appendCapturedStepOutput({
+			capturedOutput,
 			emit,
 			history,
 			output,
 			signal
 		});
 		if (result === "aborted") return "aborted";
-		await runAfterStepHook(hooks, {
-			history: history.modelSnapshot(),
-			result,
-			signal,
-			stepIndex
-		});
 		const stepEndDecision = await emitBoundary({
 			emit,
 			event: { type: "step-end" },
@@ -41,7 +31,6 @@ async function runAgentLoop({ emit, history, hooks, llm, signal = new AbortContr
 		});
 		if (stepEndDecision === "aborted") return "aborted";
 		if (result === "completed" && !stepEndDecision?.runtimeInputAdded) return "completed";
-		stepIndex += 1;
 	}
 }
 async function emitBoundary({ emit, event, signal }) {
@@ -68,34 +57,74 @@ function createAbortBoundary(signal) {
 		promise
 	};
 }
-async function runAfterStepHook(hooks, context) {
-	const hook = hooks?.afterStep;
-	if (!hook) return;
-	await Promise.allSettled([Promise.resolve().then(() => hook(context))]);
+async function captureNoObserverEvents(callback) {
+	return {
+		events: [],
+		release: releaseNoObserverEvents,
+		value: await callback()
+	};
 }
-async function readLlmOutput({ history, llm, signal }) {
+function releaseNoObserverEvents() {}
+async function readLlmOutput({ history, llm, signal, toolExecution }) {
 	try {
 		return await llm({
 			history: history.modelSnapshot(),
-			signal
+			signal,
+			toolExecution
 		});
 	} catch (error) {
 		if (signal.aborted) return "aborted";
 		throw error;
 	}
 }
-function appendStepOutput({ emit, history, output, signal }) {
+async function appendCapturedStepOutput({ capturedOutput, emit, history, output, signal }) {
+	try {
+		return await appendStepOutput({
+			emit,
+			history,
+			observerEvents: capturedOutput.events,
+			output,
+			signal
+		});
+	} finally {
+		capturedOutput.release();
+	}
+}
+async function appendStepOutput({ emit, history, observerEvents, output, signal }) {
 	if (signal.aborted) return "aborted";
 	let shouldContinue = false;
+	const pendingObserverEvents = observerEvents;
+	const flushObserverEvents = async (shouldFlush = () => true) => {
+		for (let index = 0; index < pendingObserverEvents.length;) {
+			const event = pendingObserverEvents[index];
+			if (!(event && shouldFlush(event))) {
+				index += 1;
+				continue;
+			}
+			pendingObserverEvents.splice(index, 1);
+			await emit(event);
+		}
+	};
 	for (const message of output) {
 		if (signal.aborted) return "aborted";
 		history.appendModelMessage(message);
 		const events = modelMessageToAgentEvents(message);
-		for (const event of events) emit(event);
-		if (events.some((event) => event.type === "tool-call")) shouldContinue = true;
+		const hasToolResult = events.some((event) => event.type === "tool-result");
+		for (const event of events) {
+			await emit(event);
+			if (event.type === "tool-call") {
+				shouldContinue = true;
+				await flushObserverEvents(isLaunchOrBlockingObserverEvent);
+			}
+		}
+		if (hasToolResult) await flushObserverEvents();
 	}
+	await flushObserverEvents();
 	return shouldContinue ? "continue" : "completed";
 }
+function isLaunchOrBlockingObserverEvent(_event) {
+	return true;
+}
 //#endregion
 export { runAgentLoop };
 

package/dist/agent-loop.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-loop.js","names":[],"sources":["../src/agent-loop.ts"],"sourcesContent":["import type { ModelMessage } from \"ai\";\nimport type { AgentHooks, AgentStepResult } from \"./hooks\";\nimport type { Llm, LlmOutput } from \"./llm\";\nimport type { AgentEvent, AgentEventListener } from \"./session/events\";\nimport { modelMessageToAgentEvents } from \"./session/mapping\";\n\ninterface ModelHistory {\n  appendModelMessage(message: ModelMessage): void;\n  modelSnapshot(): ModelMessage[];\n}\n\ninterface RunAgentLoopOptions {\n  emit: AgentLoopEventListener;\n  history: ModelHistory;\n  hooks?: AgentHooks;\n  llm: Llm;\n  signal?: AbortSignal;\n}\n\nexport type AgentLoopResult = \"completed\" | \"aborted\";\ntype AgentLoopBoundaryEvent = Extract<\n  AgentEvent,\n  { type: \"step-end\" } | { type: \"step-start\" }\n>;\ninterface AgentLoopBoundaryDecision {\n  readonly runtimeInputAdded?: boolean;\n}\ntype AgentLoopEventListener = (\n  event: AgentEvent\n) =>\n  | AgentLoopBoundaryDecision\n  | Promise<AgentLoopBoundaryDecision | undefined>\n  | undefined;\ntype StepOutputResult = AgentStepResult | \"aborted\";\n\nexport async function runAgentLoop({\n  emit,\n  history,\n  hooks,\n  llm,\n  signal = new AbortController().signal,\n}: RunAgentLoopOptions): Promise<AgentLoopResult> {\n  let stepIndex = 0;\n\n  while (true) {\n    if (signal.aborted) {\n      return \"aborted\";\n    }\n\n    await hooks?.beforeStep?.({\n      history: history.modelSnapshot(),\n      signal,\n      stepIndex,\n    });\n\n    if (signal.aborted) {\n      return \"aborted\";\n    }\n\n    const stepStartDecision = await emitBoundary({\n      emit,\n      event: { type: \"step-start\" },\n      signal,\n    });\n\n    if (stepStartDecision === \"aborted\") {\n      return \"aborted\";\n    }\n\n    const output = await readLlmOutput({ history, llm, signal });\n\n    if (output === \"aborted\") {\n      return \"aborted\";\n    }\n\n    const result = appendStepOutput({ emit, history, output, signal });\n\n    if (result === \"aborted\") {\n      return \"aborted\";\n    }\n\n    await runAfterStepHook(hooks, {\n      history: history.modelSnapshot(),\n      result,\n      signal,\n      stepIndex,\n    });\n\n    const stepEndDecision = await emitBoundary({\n      emit,\n      event: { type: \"step-end\" },\n      signal,\n    });\n\n    if (stepEndDecision === \"aborted\") {\n      return \"aborted\";\n    }\n\n    // Runtime input after step-end intentionally forces another inference step,\n    // even after final-looking assistant text. Unconditional insertion on every\n    // step-end can create an unbounded loop.\n    if (result === \"completed\" && !stepEndDecision?.runtimeInputAdded) {\n      return \"completed\";\n    }\n\n    stepIndex += 1;\n  }\n}\n\nasync function emitBoundary({\n  emit,\n  event,\n  signal,\n}: Pick<RunAgentLoopOptions, \"emit\"> & {\n  event: AgentLoopBoundaryEvent;\n  signal: AbortSignal;\n}): Promise<AgentLoopBoundaryDecision | \"aborted\" | undefined> {\n  if (signal.aborted) {\n    return \"aborted\";\n  }\n\n  const abort = createAbortBoundary(signal);\n  try {\n    return await Promise.race([Promise.resolve(emit(event)), abort.promise]);\n  } catch (error) {\n    if (signal.aborted) {\n      return \"aborted\";\n    }\n\n    throw error;\n  } finally {\n    abort.dispose();\n  }\n}\n\nfunction createAbortBoundary(signal: AbortSignal): {\n  dispose: () => void;\n  promise: Promise<\"aborted\">;\n} {\n  let dispose: () => void = () => undefined;\n\n  const promise = new Promise<\"aborted\">((resolve) => {\n    const onAbort = () => resolve(\"aborted\");\n    dispose = () => signal.removeEventListener(\"abort\", onAbort);\n    signal.addEventListener(\"abort\", onAbort, { once: true });\n  });\n\n  return { dispose, promise };\n}\n\nasync function runAfterStepHook(\n  hooks: AgentHooks | undefined,\n  context: Parameters<NonNullable<AgentHooks[\"afterStep\"]>>[0]\n): Promise<void> {\n  const hook = hooks?.afterStep;\n  if (!hook) {\n    return;\n  }\n\n  await Promise.allSettled([Promise.resolve().then(() => hook(context))]);\n}\n\nasync function readLlmOutput({\n  history,\n  llm,\n  signal,\n}: Pick<RunAgentLoopOptions, \"history\" | \"llm\"> & {\n  signal: AbortSignal;\n}): Promise<LlmOutput | \"aborted\"> {\n  try {\n    return await llm({ history: history.modelSnapshot(), signal });\n  } catch (error) {\n    if (signal.aborted) {\n      return \"aborted\";\n    }\n\n    throw error;\n  }\n}\n\nfunction appendStepOutput({\n  emit,\n  history,\n  output,\n  signal,\n}: { emit: AgentEventListener; history: ModelHistory } & {\n  output: LlmOutput;\n  signal: AbortSignal;\n}): StepOutputResult {\n  if (signal.aborted) {\n    return \"aborted\";\n  }\n\n  let shouldContinue = false;\n\n  for (const message of output) {\n    if (signal.aborted) {\n      return \"aborted\";\n    }\n\n    history.appendModelMessage(message);\n    const events = modelMessageToAgentEvents(message);\n\n    for (const event of events) {\n      emit(event);\n    }\n\n    if (events.some((event) => event.type === \"tool-call\")) {\n      shouldContinue = true;\n    }\n  }\n\n  return shouldContinue ? \"continue\" : \"completed\";\n}\n"],"mappings":";;AAmCA,eAAsB,aAAa,EACjC,MACA,SACA,OACA,KACA,SAAS,IAAI,gBAAgB,EAAE,UACiB;CAChD,IAAI,YAAY;CAEhB,OAAO,MAAM;EACX,IAAI,OAAO,SACT,OAAO;EAGT,MAAM,OAAO,aAAa;GACxB,SAAS,QAAQ,cAAc;GAC/B;GACA;EACF,CAAC;EAED,IAAI,OAAO,SACT,OAAO;EAST,IAAI,MAN4B,aAAa;GAC3C;GACA,OAAO,EAAE,MAAM,aAAa;GAC5B;EACF,CAAC,MAEyB,WACxB,OAAO;EAGT,MAAM,SAAS,MAAM,cAAc;GAAE;GAAS;GAAK;EAAO,CAAC;EAE3D,IAAI,WAAW,WACb,OAAO;EAGT,MAAM,SAAS,iBAAiB;GAAE;GAAM;GAAS;GAAQ;EAAO,CAAC;EAEjE,IAAI,WAAW,WACb,OAAO;EAGT,MAAM,iBAAiB,OAAO;GAC5B,SAAS,QAAQ,cAAc;GAC/B;GACA;GACA;EACF,CAAC;EAED,MAAM,kBAAkB,MAAM,aAAa;GACzC;GACA,OAAO,EAAE,MAAM,WAAW;GAC1B;EACF,CAAC;EAED,IAAI,oBAAoB,WACtB,OAAO;EAMT,IAAI,WAAW,eAAe,CAAC,iBAAiB,mBAC9C,OAAO;EAGT,aAAa;CACf;AACF;AAEA,eAAe,aAAa,EAC1B,MACA,OACA,UAI6D;CAC7D,IAAI,OAAO,SACT,OAAO;CAGT,MAAM,QAAQ,oBAAoB,MAAM;CACxC,IAAI;EACF,OAAO,MAAM,QAAQ,KAAK,CAAC,QAAQ,QAAQ,KAAK,KAAK,CAAC,GAAG,MAAM,OAAO,CAAC;CACzE,SAAS,OAAO;EACd,IAAI,OAAO,SACT,OAAO;EAGT,MAAM;CACR,UAAU;EACR,MAAM,QAAQ;CAChB;AACF;AAEA,SAAS,oBAAoB,QAG3B;CACA,IAAI,gBAA4B,KAAA;CAEhC,MAAM,UAAU,IAAI,SAAoB,YAAY;EAClD,MAAM,gBAAgB,QAAQ,SAAS;EACvC,gBAAgB,OAAO,oBAAoB,SAAS,OAAO;EAC3D,OAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;CAC1D,CAAC;CAED,OAAO;EAAE;EAAS;CAAQ;AAC5B;AAEA,eAAe,iBACb,OACA,SACe;CACf,MAAM,OAAO,OAAO;CACpB,IAAI,CAAC,MACH;CAGF,MAAM,QAAQ,WAAW,CAAC,QAAQ,QAAQ,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC;AACxE;AAEA,eAAe,cAAc,EAC3B,SACA,KACA,UAGiC;CACjC,IAAI;EACF,OAAO,MAAM,IAAI;GAAE,SAAS,QAAQ,cAAc;GAAG;EAAO,CAAC;CAC/D,SAAS,OAAO;EACd,IAAI,OAAO,SACT,OAAO;EAGT,MAAM;CACR;AACF;AAEA,SAAS,iBAAiB,EACxB,MACA,SACA,QACA,UAImB;CACnB,IAAI,OAAO,SACT,OAAO;CAGT,IAAI,iBAAiB;CAErB,KAAK,MAAM,WAAW,QAAQ;EAC5B,IAAI,OAAO,SACT,OAAO;EAGT,QAAQ,mBAAmB,OAAO;EAClC,MAAM,SAAS,0BAA0B,OAAO;EAEhD,KAAK,MAAM,SAAS,QAClB,KAAK,KAAK;EAGZ,IAAI,OAAO,MAAM,UAAU,MAAM,SAAS,WAAW,GACnD,iBAAiB;CAErB;CAEA,OAAO,iBAAiB,aAAa;AACvC"}
+{"version":3,"file":"agent-loop.js","names":[],"sources":["../src/agent-loop.ts"],"sourcesContent":["import type { ModelMessage } from \"ai\";\nimport type { RuntimeLlm, RuntimeLlmOutput } from \"./llm\";\nimport type { RuntimeToolExecutionContext } from \"./llm-tool-execution\";\nimport type { AgentEvent } from \"./session/events\";\nimport { modelMessageToAgentEvents } from \"./session/mapping\";\n\ninterface ModelHistory {\n  appendModelMessage(message: ModelMessage): void;\n  modelSnapshot(): ModelMessage[];\n}\n\ninterface RunAgentLoopOptions {\n  captureObserverEvents?: ObserverEventCapture;\n  emit: AgentLoopEventListener;\n  history: ModelHistory;\n  llm: RuntimeLlm;\n  signal?: AbortSignal;\n  toolExecution?: RuntimeToolExecutionContext;\n}\n\ntype AgentLoopResult = \"completed\" | \"aborted\";\ntype AgentLoopBoundaryEvent = Extract<\n  AgentEvent,\n  { type: \"step-end\" } | { type: \"step-start\" }\n>;\ninterface AgentLoopBoundaryDecision {\n  readonly runtimeInputAdded?: boolean;\n}\ntype AgentLoopEventListener = (\n  event: AgentEvent\n) =>\n  | AgentLoopBoundaryDecision\n  | Promise<AgentLoopBoundaryDecision | undefined>\n  | undefined;\ntype StepOutputResult = \"aborted\" | \"completed\" | \"continue\";\ninterface ObserverEventCaptureResult<T> {\n  readonly events: AgentEvent[];\n  readonly release: () => void;\n  readonly value: T;\n}\ntype ObserverEventCapture = <T>(\n  callback: () => Promise<T>\n) => Promise<ObserverEventCaptureResult<T>>;\n\nexport async function runAgentLoop({\n  captureObserverEvents = captureNoObserverEvents,\n  emit,\n  history,\n  llm,\n  signal = new AbortController().signal,\n  toolExecution,\n}: RunAgentLoopOptions): Promise<AgentLoopResult> {\n  while (true) {\n    if (signal.aborted) {\n      return \"aborted\";\n    }\n\n    const stepStartDecision = await emitBoundary({\n      emit,\n      event: { type: \"step-start\" },\n      signal,\n    });\n\n    if (stepStartDecision === \"aborted\") {\n      return \"aborted\";\n    }\n\n    const capturedOutput = await captureObserverEvents(() =>\n      readLlmOutput({ history, llm, signal, toolExecution })\n    );\n    const output = capturedOutput.value;\n\n    if (output === \"aborted\") {\n      return \"aborted\";\n    }\n\n    const result = await appendCapturedStepOutput({\n      capturedOutput,\n      emit,\n      history,\n      output,\n      signal,\n    });\n\n    if (result === \"aborted\") {\n      return \"aborted\";\n    }\n\n    const stepEndDecision = await emitBoundary({\n      emit,\n      event: { type: \"step-end\" },\n      signal,\n    });\n\n    if (stepEndDecision === \"aborted\") {\n      return \"aborted\";\n    }\n\n    // Runtime input after step-end intentionally forces another inference step,\n    // even after final-looking assistant text. Unconditional insertion on every\n    // step-end can create an unbounded loop.\n    if (result === \"completed\" && !stepEndDecision?.runtimeInputAdded) {\n      return \"completed\";\n    }\n  }\n}\n\nasync function emitBoundary({\n  emit,\n  event,\n  signal,\n}: Pick<RunAgentLoopOptions, \"emit\"> & {\n  event: AgentLoopBoundaryEvent;\n  signal: AbortSignal;\n}): Promise<AgentLoopBoundaryDecision | \"aborted\" | undefined> {\n  if (signal.aborted) {\n    return \"aborted\";\n  }\n\n  const abort = createAbortBoundary(signal);\n  try {\n    return await Promise.race([Promise.resolve(emit(event)), abort.promise]);\n  } catch (error) {\n    if (signal.aborted) {\n      return \"aborted\";\n    }\n\n    throw error;\n  } finally {\n    abort.dispose();\n  }\n}\n\nfunction createAbortBoundary(signal: AbortSignal): {\n  dispose: () => void;\n  promise: Promise<\"aborted\">;\n} {\n  let dispose: () => void = () => undefined;\n\n  const promise = new Promise<\"aborted\">((resolve) => {\n    const onAbort = () => resolve(\"aborted\");\n    dispose = () => signal.removeEventListener(\"abort\", onAbort);\n    signal.addEventListener(\"abort\", onAbort, { once: true });\n  });\n\n  return { dispose, promise };\n}\n\nasync function captureNoObserverEvents<T>(callback: () => Promise<T>): Promise<{\n  readonly events: AgentEvent[];\n  readonly release: () => void;\n  readonly value: T;\n}> {\n  return {\n    events: [],\n    release: releaseNoObserverEvents,\n    value: await callback(),\n  };\n}\n\nfunction releaseNoObserverEvents(): void {\n  return;\n}\n\nasync function readLlmOutput({\n  history,\n  llm,\n  signal,\n  toolExecution,\n}: Pick<RunAgentLoopOptions, \"history\" | \"llm\"> & {\n  signal: AbortSignal;\n  toolExecution?: RuntimeToolExecutionContext;\n}): Promise<RuntimeLlmOutput | \"aborted\"> {\n  try {\n    return await llm({\n      history: history.modelSnapshot(),\n      signal,\n      toolExecution,\n    });\n  } catch (error) {\n    if (signal.aborted) {\n      return \"aborted\";\n    }\n\n    throw error;\n  }\n}\n\nasync function appendCapturedStepOutput({\n  capturedOutput,\n  emit,\n  history,\n  output,\n  signal,\n}: Pick<RunAgentLoopOptions, \"emit\"> & { history: ModelHistory } & {\n  capturedOutput: ObserverEventCaptureResult<RuntimeLlmOutput | \"aborted\">;\n  output: RuntimeLlmOutput;\n  signal: AbortSignal;\n}): Promise<StepOutputResult> {\n  try {\n    return await appendStepOutput({\n      emit,\n      history,\n      observerEvents: capturedOutput.events,\n      output,\n      signal,\n    });\n  } finally {\n    capturedOutput.release();\n  }\n}\n\nasync function appendStepOutput({\n  emit,\n  history,\n  observerEvents,\n  output,\n  signal,\n}: Pick<RunAgentLoopOptions, \"emit\"> & { history: ModelHistory } & {\n  observerEvents: AgentEvent[];\n  output: RuntimeLlmOutput;\n  signal: AbortSignal;\n}): Promise<StepOutputResult> {\n  if (signal.aborted) {\n    return \"aborted\";\n  }\n\n  let shouldContinue = false;\n  const pendingObserverEvents = observerEvents;\n  const flushObserverEvents = async (\n    shouldFlush: (event: AgentEvent) => boolean = () => true\n  ) => {\n    for (let index = 0; index < pendingObserverEvents.length; ) {\n      const event = pendingObserverEvents[index];\n      if (!(event && shouldFlush(event))) {\n        index += 1;\n        continue;\n      }\n      pendingObserverEvents.splice(index, 1);\n      await emit(event);\n    }\n  };\n\n  for (const message of output) {\n    if (signal.aborted) {\n      return \"aborted\";\n    }\n\n    history.appendModelMessage(message);\n    const events = modelMessageToAgentEvents(message);\n    const hasToolResult = events.some((event) => event.type === \"tool-result\");\n\n    for (const event of events) {\n      await emit(event);\n      if (event.type === \"tool-call\") {\n        shouldContinue = true;\n        await flushObserverEvents(isLaunchOrBlockingObserverEvent);\n      }\n    }\n\n    if (hasToolResult) {\n      await flushObserverEvents();\n    }\n  }\n\n  await flushObserverEvents();\n\n  return shouldContinue ? \"continue\" : \"completed\";\n}\n\nfunction isLaunchOrBlockingObserverEvent(_event: AgentEvent): boolean {\n  return true;\n}\n"],"mappings":";;AA4CA,eAAsB,aAAa,EACjC,wBAAwB,yBACxB,MACA,SACA,KACA,SAAS,IAAI,gBAAgB,EAAE,QAC/B,iBACgD;CAChD,OAAO,MAAM;EACX,IAAI,OAAO,SACT,OAAO;EAST,IAAI,MAN4B,aAAa;GAC3C;GACA,OAAO,EAAE,MAAM,aAAa;GAC5B;EACF,CAAC,MAEyB,WACxB,OAAO;EAGT,MAAM,iBAAiB,MAAM,4BAC3B,cAAc;GAAE;GAAS;GAAK;GAAQ;EAAc,CAAC,CACvD;EACA,MAAM,SAAS,eAAe;EAE9B,IAAI,WAAW,WACb,OAAO;EAGT,MAAM,SAAS,MAAM,yBAAyB;GAC5C;GACA;GACA;GACA;GACA;EACF,CAAC;EAED,IAAI,WAAW,WACb,OAAO;EAGT,MAAM,kBAAkB,MAAM,aAAa;GACzC;GACA,OAAO,EAAE,MAAM,WAAW;GAC1B;EACF,CAAC;EAED,IAAI,oBAAoB,WACtB,OAAO;EAMT,IAAI,WAAW,eAAe,CAAC,iBAAiB,mBAC9C,OAAO;CAEX;AACF;AAEA,eAAe,aAAa,EAC1B,MACA,OACA,UAI6D;CAC7D,IAAI,OAAO,SACT,OAAO;CAGT,MAAM,QAAQ,oBAAoB,MAAM;CACxC,IAAI;EACF,OAAO,MAAM,QAAQ,KAAK,CAAC,QAAQ,QAAQ,KAAK,KAAK,CAAC,GAAG,MAAM,OAAO,CAAC;CACzE,SAAS,OAAO;EACd,IAAI,OAAO,SACT,OAAO;EAGT,MAAM;CACR,UAAU;EACR,MAAM,QAAQ;CAChB;AACF;AAEA,SAAS,oBAAoB,QAG3B;CACA,IAAI,gBAA4B,KAAA;CAEhC,MAAM,UAAU,IAAI,SAAoB,YAAY;EAClD,MAAM,gBAAgB,QAAQ,SAAS;EACvC,gBAAgB,OAAO,oBAAoB,SAAS,OAAO;EAC3D,OAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;CAC1D,CAAC;CAED,OAAO;EAAE;EAAS;CAAQ;AAC5B;AAEA,eAAe,wBAA2B,UAIvC;CACD,OAAO;EACL,QAAQ,CAAC;EACT,SAAS;EACT,OAAO,MAAM,SAAS;CACxB;AACF;AAEA,SAAS,0BAAgC,CAEzC;AAEA,eAAe,cAAc,EAC3B,SACA,KACA,QACA,iBAIwC;CACxC,IAAI;EACF,OAAO,MAAM,IAAI;GACf,SAAS,QAAQ,cAAc;GAC/B;GACA;EACF,CAAC;CACH,SAAS,OAAO;EACd,IAAI,OAAO,SACT,OAAO;EAGT,MAAM;CACR;AACF;AAEA,eAAe,yBAAyB,EACtC,gBACA,MACA,SACA,QACA,UAK4B;CAC5B,IAAI;EACF,OAAO,MAAM,iBAAiB;GAC5B;GACA;GACA,gBAAgB,eAAe;GAC/B;GACA;EACF,CAAC;CACH,UAAU;EACR,eAAe,QAAQ;CACzB;AACF;AAEA,eAAe,iBAAiB,EAC9B,MACA,SACA,gBACA,QACA,UAK4B;CAC5B,IAAI,OAAO,SACT,OAAO;CAGT,IAAI,iBAAiB;CACrB,MAAM,wBAAwB;CAC9B,MAAM,sBAAsB,OAC1B,oBAAoD,SACjD;EACH,KAAK,IAAI,QAAQ,GAAG,QAAQ,sBAAsB,SAAU;GAC1D,MAAM,QAAQ,sBAAsB;GACpC,IAAI,EAAE,SAAS,YAAY,KAAK,IAAI;IAClC,SAAS;IACT;GACF;GACA,sBAAsB,OAAO,OAAO,CAAC;GACrC,MAAM,KAAK,KAAK;EAClB;CACF;CAEA,KAAK,MAAM,WAAW,QAAQ;EAC5B,IAAI,OAAO,SACT,OAAO;EAGT,QAAQ,mBAAmB,OAAO;EAClC,MAAM,SAAS,0BAA0B,OAAO;EAChD,MAAM,gBAAgB,OAAO,MAAM,UAAU,MAAM,SAAS,aAAa;EAEzE,KAAK,MAAM,SAAS,QAAQ;GAC1B,MAAM,KAAK,KAAK;GAChB,IAAI,MAAM,SAAS,aAAa;IAC9B,iBAAiB;IACjB,MAAM,oBAAoB,+BAA+B;GAC3D;EACF;EAEA,IAAI,eACF,MAAM,oBAAoB;CAE9B;CAEA,MAAM,oBAAoB;CAE1B,OAAO,iBAAiB,aAAa;AACvC;AAEA,SAAS,gCAAgC,QAA6B;CACpE,OAAO;AACT"}

package/dist/agent-namespace.js

@@ -8,10 +8,13 @@ function agentNamespace(namespace) {
 function namespacePart(value) {
 	return encodeURIComponent(value);
 }
-function parentSessionNamespace({ generation, sessionKey, sessionNamespace }) {
-	return `${sessionNamespace}:session:${namespacePart(sessionKey)}:generation:${generation}`;
+function ownsAgentNamespace(ownerNamespace, sessionNamespace) {
+	return ownerNamespace === sessionNamespace || ownerNamespace?.startsWith(`${sessionNamespace}:session:`) === true;
+}
+function stableAgentNamespace({ namespace }) {
+	return namespace ? agentNamespace(namespace) : randomAgentNamespace();
 }
 //#endregion
-export { agentNamespace, parentSessionNamespace, randomAgentNamespace };
+export { ownsAgentNamespace, stableAgentNamespace };
 
 //# sourceMappingURL=agent-namespace.js.map