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

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`, `tools`, and
+`subagents`, 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
@@ -117,9 +153,11 @@ delegate_to_researcher({
 ```
 
 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`.
+the child keeps working. The launch result includes a `bg_...` `task_id` and
+tells the model to wait for a `<system-reminder>` before retrieving output.
+When background work finishes, the session is notified with compact runtime
+input. Hosts that support durable background work should resume the parent session
+through the notification inbox and drain the returned `AgentRun`.
 
 ```ts
 delegate_to_researcher({
@@ -127,6 +165,7 @@ delegate_to_researcher({
   run_in_background: true,
 });
 
+// After the completion reminder arrives:
 background_output({ task_id: "bg_...", block: true });
 background_cancel({ task_id: "bg_..." });
 ```
@@ -134,20 +173,38 @@ background_cancel({ task_id: "bg_..." });
 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.
+run in task-scoped child sessions. In-memory job handles are cleaned up after
+completed output retrieval, while durable hosts keep compact completed output
+available through the execution store for reconstructed agents. Background jobs
+launched during the same parent turn share an internal completion barrier:
+successful jobs notify once when the group settles, while failed jobs notify
+immediately.
 
-## Send and Steer
+## 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.
 
-Both APIs accept the same input shapes: strings, arrays of strings,
+Each accepted call returns one `AgentRun`. Drain that run's `events()` stream to
+observe the turn; each `AgentRun.events()` stream is single-consumer.
+
+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 +245,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,15 +257,14 @@ 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",
 });
 ```
 
@@ -216,17 +276,65 @@ session and child `sessionKey` suffixes back to the same child transcripts:
 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`. A durable host owns
+execution state, scheduling, and its session snapshot store through
+`store.sessions`; `ExecutionHost` does not accept a separate `sessionStore`
+override.
+
+```ts
+import { Agent } from "@minpeter/pss-runtime";
+import {
+  createInMemoryExecutionHost,
+  type ExecutionHost,
+} from "@minpeter/pss-runtime/execution";
+
+const host = createInMemoryExecutionHost();
+
+const agent = new Agent({
+  host,
+  model,
+  namespace: "support-agent",
+});
+
+const durableHost: ExecutionHost = {
+  capabilities: { backgroundSubagents: "durable" },
+  scheduler,
+  store,
+};
+```
+
+## 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({ subagents: [...] })`; host-specific durability and scheduling live
+behind the `host` boundary.
+
+Long-running Node.js can keep an `Agent` and `SessionHandle` alive across turns.
+The default in-memory host advertises in-process background subagent capability,
+so `run_in_background`, `background_output`, and `background_cancel` remain
+available while that process owns the work. `FileSessionStore` persists session
+snapshots only; it does not make background work durable by itself.
+
+Cloudflare Durable Objects and similar edge hosts should reconstruct `Agent`
+objects per turn and persist opaque session state through `store.sessions`.
+When a host does not advertise background subagent capability, the runtime hides
+background tools from the parent model and exposes blocking delegation only.
+This avoids pretending that in-memory background work survived a hibernation,
+isolate restart, or request deadline.
+
+See `examples/cloudflare-edge-subagent` for an edge-hosted turn loop with a
+Worker/Durable Object-shaped host, and `examples/subagent` for a long-running
+local background subagent flow.
 
-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 +343,39 @@ 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 subagents require a host capability that owns task ids,
+attempts, leases, checkpoints, cancellation, scheduling, and completion
+notifications. The Cloudflare edge example includes a Worker/Durable
+Object-shaped host that 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. Parent `delete()` and
+`kill()` mark linked child runs as `cancelled` through the execution store before
+falling back to process-local cleanup, so stale child completions cannot enqueue
+new parent notifications.

package/dist/agent-child-runs.js

@@ -0,0 +1,16 @@
+import { executionHost } from "./execution/host.js";
+import { cancelBackgroundChildRun } from "./subagent-background-child-run.js";
+//#region src/agent-child-runs.ts
+async function cancelDurableChildRuns(host, parentRunId) {
+	const durableHost = executionHost(host);
+	if (!durableHost) return;
+	const childRuns = await durableHost.store.runs.listByParentRunId(parentRunId);
+	await Promise.all(childRuns.map((run) => cancelBackgroundChildRun({
+		executionHost: durableHost,
+		runId: run.runId
+	})));
+}
+//#endregion
+export { cancelDurableChildRuns };
+
+//# sourceMappingURL=agent-child-runs.js.map

package/dist/agent-child-runs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-child-runs.js","names":[],"sources":["../src/agent-child-runs.ts"],"sourcesContent":["import { executionHost } from \"./execution/host\";\nimport type { AgentHost } from \"./execution/types\";\nimport { cancelBackgroundChildRun } from \"./subagent-background-child-run\";\n\nexport async function cancelDurableChildRuns(\n  host: AgentHost,\n  parentRunId: string\n): Promise<void> {\n  const durableHost = executionHost(host);\n  if (!durableHost) {\n    return;\n  }\n\n  const childRuns = await durableHost.store.runs.listByParentRunId(parentRunId);\n  await Promise.all(\n    childRuns.map((run) =>\n      cancelBackgroundChildRun({\n        executionHost: durableHost,\n        runId: run.runId,\n      })\n    )\n  );\n}\n"],"mappings":";;;AAIA,eAAsB,uBACpB,MACA,aACe;CACf,MAAM,cAAc,cAAc,IAAI;CACtC,IAAI,CAAC,aACH;CAGF,MAAM,YAAY,MAAM,YAAY,MAAM,KAAK,kBAAkB,WAAW;CAC5E,MAAM,QAAQ,IACZ,UAAU,KAAK,QACb,yBAAyB;EACvB,eAAe;EACf,OAAO,IAAI;CACb,CAAC,CACH,CACF;AACF"}

package/dist/agent-host-capabilities.js

@@ -0,0 +1,9 @@
+//#region src/agent-host-capabilities.ts
+function supportsBackgroundSubagents(host, executionHost) {
+	const capability = host.capabilities?.backgroundSubagents;
+	return capability === "in-process" || capability === "durable" && executionHost !== void 0;
+}
+//#endregion
+export { supportsBackgroundSubagents };
+
+//# sourceMappingURL=agent-host-capabilities.js.map

package/dist/agent-host-capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-host-capabilities.js","names":[],"sources":["../src/agent-host-capabilities.ts"],"sourcesContent":["import type { AgentHost, ExecutionHost } from \"./execution/types\";\n\nexport function supportsBackgroundSubagents(\n  host: AgentHost,\n  executionHost: ExecutionHost | undefined\n): boolean {\n  const capability = host.capabilities?.backgroundSubagents;\n  return (\n    capability === \"in-process\" ||\n    (capability === \"durable\" && executionHost !== undefined)\n  );\n}\n"],"mappings":";AAEA,SAAgB,4BACd,MACA,eACS;CACT,MAAM,aAAa,KAAK,cAAc;CACtC,OACE,eAAe,gBACd,eAAe,aAAa,kBAAkB,KAAA;AAEnD"}

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

@@ -0,0 +1,12 @@
+import { executionHost } from "./execution/host.js";
+import { MemorySessionStore } from "./session/store/memory.js";
+//#region src/agent-host-session-store.ts
+function sessionStoreForHost(host) {
+	if ("sessionStore" in host && host.sessionStore) return host.sessionStore;
+	const hostExecution = executionHost(host);
+	return hostExecution ? hostExecution.store.sessions : 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 { executionHost } 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  if (\"sessionStore\" in host && host.sessionStore) {\n    return host.sessionStore;\n  }\n\n  const hostExecution = executionHost(host);\n  return hostExecution\n    ? hostExecution.store.sessions\n    : new MemorySessionStore();\n}\n"],"mappings":";;;AAKA,SAAgB,oBAAoB,MAA+B;CACjE,IAAI,kBAAkB,QAAQ,KAAK,cACjC,OAAO,KAAK;CAGd,MAAM,gBAAgB,cAAc,IAAI;CACxC,OAAO,gBACH,cAAc,MAAM,WACpB,IAAI,mBAAmB;AAC7B"}

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,75 @@ 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) {
+	if (event.type === "subagent-job-update") return false;
+	return !(event.type === "subagent-job-end" && event.task_id);
+}
 //#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  if (event.type === \"subagent-job-update\") {\n    return false;\n  }\n\n  return !(event.type === \"subagent-job-end\" && event.task_id);\n}\n"],"mappings":"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"}

package/dist/agent-namespace.js

@@ -11,7 +11,14 @@ function namespacePart(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({ name, namespace }) {
+	const stableNamespace = namespace ?? name;
+	return stableNamespace ? agentNamespace(stableNamespace) : randomAgentNamespace();
+}
 //#endregion
-export { agentNamespace, parentSessionNamespace, randomAgentNamespace };
+export { ownsAgentNamespace, parentSessionNamespace, stableAgentNamespace };
 
 //# sourceMappingURL=agent-namespace.js.map

package/dist/agent-namespace.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-namespace.js","names":[],"sources":["../src/agent-namespace.ts"],"sourcesContent":["export function randomAgentNamespace(): string {\n  return agentNamespace(crypto.randomUUID());\n}\n\nexport function agentNamespace(namespace: string): string {\n  return `agent:${namespacePart(namespace)}`;\n}\n\nexport function namespacePart(value: string): string {\n  return encodeURIComponent(value);\n}\n\nexport function parentSessionNamespace({\n  generation,\n  sessionKey,\n  sessionNamespace,\n}: {\n  readonly generation: number;\n  readonly sessionKey: string;\n  readonly sessionNamespace: string;\n}): string {\n  return `${sessionNamespace}:session:${namespacePart(\n    sessionKey\n  )}:generation:${generation}`;\n}\n"],"mappings":";AAAA,SAAgB,uBAA+B;CAC7C,OAAO,eAAe,OAAO,WAAW,CAAC;AAC3C;AAEA,SAAgB,eAAe,WAA2B;CACxD,OAAO,SAAS,cAAc,SAAS;AACzC;AAEA,SAAgB,cAAc,OAAuB;CACnD,OAAO,mBAAmB,KAAK;AACjC;AAEA,SAAgB,uBAAuB,EACrC,YACA,YACA,oBAKS;CACT,OAAO,GAAG,iBAAiB,WAAW,cACpC,UACF,EAAE,cAAc;AAClB"}
+{"version":3,"file":"agent-namespace.js","names":[],"sources":["../src/agent-namespace.ts"],"sourcesContent":["export function randomAgentNamespace(): string {\n  return agentNamespace(crypto.randomUUID());\n}\n\nexport function agentNamespace(namespace: string): string {\n  return `agent:${namespacePart(namespace)}`;\n}\n\nexport function namespacePart(value: string): string {\n  return encodeURIComponent(value);\n}\n\nexport function parentSessionNamespace({\n  generation,\n  sessionKey,\n  sessionNamespace,\n}: {\n  readonly generation: number;\n  readonly sessionKey: string;\n  readonly sessionNamespace: string;\n}): string {\n  return `${sessionNamespace}:session:${namespacePart(\n    sessionKey\n  )}:generation:${generation}`;\n}\n\nexport function ownsAgentNamespace(\n  ownerNamespace: string | undefined,\n  sessionNamespace: string\n): boolean {\n  return (\n    ownerNamespace === sessionNamespace ||\n    ownerNamespace?.startsWith(`${sessionNamespace}:session:`) === true\n  );\n}\n\nexport function stableAgentNamespace({\n  name,\n  namespace,\n}: {\n  readonly name?: string;\n  readonly namespace?: string;\n}): string {\n  const stableNamespace = namespace ?? name;\n  return stableNamespace\n    ? agentNamespace(stableNamespace)\n    : randomAgentNamespace();\n}\n"],"mappings":";AAAA,SAAgB,uBAA+B;CAC7C,OAAO,eAAe,OAAO,WAAW,CAAC;AAC3C;AAEA,SAAgB,eAAe,WAA2B;CACxD,OAAO,SAAS,cAAc,SAAS;AACzC;AAEA,SAAgB,cAAc,OAAuB;CACnD,OAAO,mBAAmB,KAAK;AACjC;AAEA,SAAgB,uBAAuB,EACrC,YACA,YACA,oBAKS;CACT,OAAO,GAAG,iBAAiB,WAAW,cACpC,UACF,EAAE,cAAc;AAClB;AAEA,SAAgB,mBACd,gBACA,kBACS;CACT,OACE,mBAAmB,oBACnB,gBAAgB,WAAW,GAAG,iBAAiB,UAAU,MAAM;AAEnE;AAEA,SAAgB,qBAAqB,EACnC,MACA,aAIS;CACT,MAAM,kBAAkB,aAAa;CACrC,OAAO,kBACH,eAAe,eAAe,IAC9B,qBAAqB;AAC3B"}

package/dist/agent-options.d.ts

@@ -0,0 +1,35 @@
+import { AgentToolChoice, RuntimeLlm } from "./llm.js";
+import { AgentHost } from "./execution/types.js";
+import { AgentPlugin } from "./plugins.js";
+import { Agent } from "./agent.js";
+import { LanguageModel, ToolSet } from "ai";
+
+//#region src/agent-options.d.ts
+interface AgentLanguageModelOptions {
+  readonly description?: string;
+  readonly host?: AgentHost;
+  readonly instructions?: string;
+  readonly model: LanguageModel;
+  readonly name?: string;
+  readonly namespace?: string;
+  readonly plugins?: readonly AgentPlugin[];
+  readonly subagents?: readonly Agent[];
+  readonly toolChoice?: AgentToolChoice;
+  readonly tools?: ToolSet;
+}
+interface AgentRuntimeModelOptions {
+  readonly description?: string;
+  readonly host?: AgentHost;
+  readonly instructions?: never;
+  readonly model: RuntimeLlm;
+  readonly name?: string;
+  readonly namespace?: string;
+  readonly plugins?: readonly AgentPlugin[];
+  readonly subagents?: never;
+  readonly toolChoice?: never;
+  readonly tools?: never;
+}
+type AgentOptions = AgentLanguageModelOptions | AgentRuntimeModelOptions;
+//#endregion
+export { AgentOptions };
+//# sourceMappingURL=agent-options.d.ts.map

package/dist/agent-options.js

@@ -0,0 +1,16 @@
+//#region src/agent-options.ts
+function assertAgentOptions(options) {
+	if (options === null || typeof options !== "object") throw new TypeError("Agent options are required. Provide { model }.");
+	if ("sessions" in options) throw new TypeError("Agent: unsupported options.sessions. Use host: { sessionStore } and namespace instead.");
+	if ("runtime" in options) throw new TypeError("Agent: unsupported options.runtime. Use host.");
+	if ("llm" in options) throw new TypeError("Agent: unsupported options.llm. Use model for both AI SDK models and custom RuntimeLlm functions.");
+	if (!("model" in options && options.model != null)) throw new TypeError("Agent: missing options.model.");
+	if (typeof options.model !== "function" && (typeof options.model !== "object" || options.model === null)) throw new TypeError("Agent: invalid options.model.");
+}
+function hasRuntimeModel(options) {
+	return typeof options.model === "function";
+}
+//#endregion
+export { assertAgentOptions, hasRuntimeModel };
+
+//# sourceMappingURL=agent-options.js.map

package/dist/agent-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-options.js","names":[],"sources":["../src/agent-options.ts"],"sourcesContent":["import type { LanguageModel, ToolSet } from \"ai\";\nimport type { Agent } from \"./agent\";\nimport type { AgentHost } from \"./execution/types\";\nimport type { AgentToolChoice, RuntimeLlm } from \"./llm\";\nimport type { AgentPlugin } from \"./plugins\";\n\ninterface AgentLanguageModelOptions {\n  readonly description?: string;\n  readonly host?: AgentHost;\n  readonly instructions?: string;\n  readonly model: LanguageModel;\n  readonly name?: string;\n  readonly namespace?: string;\n  readonly plugins?: readonly AgentPlugin[];\n  readonly subagents?: readonly Agent[];\n  readonly toolChoice?: AgentToolChoice;\n  readonly tools?: ToolSet;\n}\n\ninterface AgentRuntimeModelOptions {\n  readonly description?: string;\n  readonly host?: AgentHost;\n  readonly instructions?: never;\n  readonly model: RuntimeLlm;\n  readonly name?: string;\n  readonly namespace?: string;\n  readonly plugins?: readonly AgentPlugin[];\n  readonly subagents?: never;\n  readonly toolChoice?: never;\n  readonly tools?: never;\n}\n\nexport type AgentModelOptions = Pick<\n  AgentLanguageModelOptions,\n  \"instructions\" | \"model\" | \"toolChoice\"\n>;\nexport type AgentOptions = AgentLanguageModelOptions | AgentRuntimeModelOptions;\n\nexport function assertAgentOptions(\n  options: unknown\n): asserts options is AgentOptions {\n  if (options === null || typeof options !== \"object\") {\n    throw new TypeError(\"Agent options are required. Provide { model }.\");\n  }\n\n  if (\"sessions\" in options) {\n    throw new TypeError(\n      \"Agent: unsupported options.sessions. Use host: { sessionStore } and namespace instead.\"\n    );\n  }\n\n  if (\"runtime\" in options) {\n    throw new TypeError(\"Agent: unsupported options.runtime. Use host.\");\n  }\n\n  if (\"llm\" in options) {\n    throw new TypeError(\n      \"Agent: unsupported options.llm. Use model for both AI SDK models and custom RuntimeLlm functions.\"\n    );\n  }\n\n  const hasModel = \"model\" in options && options.model != null;\n\n  if (!hasModel) {\n    throw new TypeError(\"Agent: missing options.model.\");\n  }\n\n  if (\n    typeof options.model !== \"function\" &&\n    (typeof options.model !== \"object\" || options.model === null)\n  ) {\n    throw new TypeError(\"Agent: invalid options.model.\");\n  }\n}\n\nexport function hasRuntimeModel(\n  options: AgentOptions\n): options is AgentRuntimeModelOptions {\n  return typeof options.model === \"function\";\n}\n"],"mappings":";AAsCA,SAAgB,mBACd,SACiC;CACjC,IAAI,YAAY,QAAQ,OAAO,YAAY,UACzC,MAAM,IAAI,UAAU,gDAAgD;CAGtE,IAAI,cAAc,SAChB,MAAM,IAAI,UACR,wFACF;CAGF,IAAI,aAAa,SACf,MAAM,IAAI,UAAU,+CAA+C;CAGrE,IAAI,SAAS,SACX,MAAM,IAAI,UACR,mGACF;CAKF,IAAI,EAFa,WAAW,WAAW,QAAQ,SAAS,OAGtD,MAAM,IAAI,UAAU,+BAA+B;CAGrD,IACE,OAAO,QAAQ,UAAU,eACxB,OAAO,QAAQ,UAAU,YAAY,QAAQ,UAAU,OAExD,MAAM,IAAI,UAAU,+BAA+B;AAEvD;AAEA,SAAgB,gBACd,SACqC;CACrC,OAAO,OAAO,QAAQ,UAAU;AAClC"}