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

package/README.md

@@ -13,7 +13,7 @@ Minimal, platform-agnostic agent runtime with keyed sessions, synchronized
 import { Agent } from "@minpeter/pss-runtime";
 import { createYourLanguageModel } from "...";
 
-const agent = await Agent.create({
+const agent = new Agent({
   instructions: "Answer briefly.",
   model: createYourLanguageModel(),
 });
@@ -28,23 +28,7 @@ for await (const event of run.events()) {
 boundaries until the events consumer asks for the next event, so callers must
 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. `AgentRun.events()` is single-consumer by design: keep rendering,
-logging, tracing, and continuation policy in the same app-owned loop when those
-concerns must share synchronized boundary control.
-
-```ts
-const run = await agent.send("Implement the plan.");
-const session = agent.session("default");
-
-for await (const event of run.events()) {
-  renderEvent(event);
-  traceEvent(event);
-
-  if (event.type === "step-end" && shouldContinueWork()) {
-    await session.steer("Continue. The task is not complete yet.");
-  }
-}
-```
+created.
 
 Per-key conversations use `session(key)`:
 
@@ -96,6 +80,63 @@ 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
+
+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.
+
+```ts
+const researcher = new Agent({
+  name: "researcher",
+  description: "Researches facts and returns concise evidence.",
+  model,
+  instructions: "Research facts and return concise evidence.",
+});
+
+const coordinator = new Agent({
+  model,
+  instructions: "Coordinate work and delegate when useful.",
+  subagents: [researcher],
+});
+```
+
+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.
+
+```ts
+delegate_to_researcher({
+  prompt: "Find the current release notes and summarize the evidence.",
+});
+```
+
+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`.
+
+```ts
+delegate_to_researcher({
+  prompt: "Compare the API designs.",
+  run_in_background: true,
+});
+
+background_output({ task_id: "bg_...", block: true });
+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.
+
 ## Send and Steer
 
 Use `session.send(input)` for a new user turn. If a run is already active, the
@@ -138,201 +179,51 @@ for await (const event of run.events()) {
 pending steering path or, when idle, when a new run is scheduled. It does not wait
 for a later model snapshot.
 
-## Overlay
-
-Use `session.overlay(input)` for turn-scoped model context that should affect
-the next model snapshot without becoming canonical session history. It accepts
-the same input shapes as `send()` and `steer()` and has no options in v0.
-
-Overlay context accepted before the first model inference in a turn is composed
-above the current user prompt. This keeps the current prompt near the bottom of
-the model snapshot while still giving the model fresh runtime context first.
-Overlay context accepted after a model inference has already happened is
-append-only: it is added after the messages that already existed for that turn
-and never moves earlier content around.
-
-```ts
-const session = agent.session("room:123:user:456");
-
-await session.overlay("Current wall-clock time: 2026-06-05T19:00:00Z");
-const run = await session.send("What should I do next?");
-
-for await (const event of run.events()) {
-  if (event.type === "step-end" && needsOneMorePass()) {
-    await session.overlay("Additional constraint: answer in two sentences.");
-  }
-}
-```
-
-Active `step-end` overlays intentionally continue the current turn for one more
-model snapshot, like `step-end` steering, but they are not persisted as
-`runtime-input`. Idle overlays do not start a turn; they queue for the next
-`send()` on that session.
-
-Runs emit `overlay-accepted` when overlay input is accepted and
-`overlay-expired` when the turn-scoped frame is discarded at turn end, abort,
-error, or kill. Overlay text is not written to stored history, not encoded in
-session snapshots, and does not survive session reload.
-
-## Plugins, Session Storage, Memory, And Compaction
+## Session storage and portability
 
 The runtime owns full session state encoding and history compaction semantics.
-Persistence, memory, and compaction are configured through in-process plugins:
-
-```ts
-import { Agent } from "@minpeter/pss-runtime";
-import { compaction, memory, sessions } from "@minpeter/pss-runtime/plugins";
+Adapters own persistence only through `SessionStore`:
 
-const agent = await Agent.create({
-  model,
-  plugins: [sessions.file(".pss/sessions"), memory(), compaction()],
-});
-```
-
-If no persistence plugin is provided, sessions are memory-backed by default.
-
-Reusable middleware belongs in plugins. Plugins can observe turn and step
-lifecycle events and call the scoped `steer` function to insert runtime input at
-the active boundary or the scoped `overlay` function to add turn-scoped
-non-persistent context before the turn ends. Plugin `overlay` is available from
-`turn.before`, `step.before`, and `step.after`; `turn.after` runs after the
-turn-scoped overlay frame is closed and rejects overlay calls. App-level control
-should stay with `run.events()` plus `session.steer()` or `session.overlay()`;
-plugin lifecycle is for reusable policy.
+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.
 
-Plugin event names are dotted middleware names: `turn.before`, `step.before`,
-`step.after`, `turn.after`, `tool.call`, and `tool.result`. These are separate
-from public `run.events()` transcript names such as `turn-start`, `step-start`,
-`assistant-text`, `tool-call`, `tool-result`, `step-end`, and `turn-end`.
+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:
+"conflict" }`. On success, the store persists `{ state, version }` and returns the
+new version to the runtime. `delete(key)` removes the persisted session for that
+key.
 
 ```ts
-import { Agent, definePlugin } from "@minpeter/pss-runtime";
-
-const continuePlugin = definePlugin({
-  name: "continue-policy",
-  setup(host) {
-    host.on("step.after", async ({ result, history, overlay, steer, stepIndex }) => {
-      if (result === "completed" && stepIndex === 0 && shouldContinueWork(history)) {
-        await overlay("Continue, but do not persist this policy text.");
-        await steer("Continue. The task is not complete yet.");
-      }
-    });
-  },
-});
+import type { SessionStore } from "@minpeter/pss-runtime";
+import { MemorySessionStore } from "@minpeter/pss-runtime/session-store/memory";
 
-const agent = await Agent.create({
+const agent = new Agent({
   model,
-  plugins: [continuePlugin],
-});
-```
-
-`turn.after` is useful for audit, metrics, or scheduling a separate follow-up
-run after the current turn has committed.
-
-```ts
-const auditPlugin = definePlugin({
-  name: "turn-audit",
-  setup(host) {
-    host.on("turn.after", ({ result, sessionKey }) => {
-      recordTurnResult(sessionKey, result);
-    });
-  },
-});
-```
-
-Tool policy hooks apply to runtime-owned tools in the `Agent.create({ model,
-tools })` path, including tools registered by plugins. Custom `llm` callers own
-their tool execution and do not receive synthetic tool hook events.
-
-`tool.call` runs after AI SDK input parsing and before the original tool
-`execute`. Handlers run in plugin registration order. `allow` continues to the
-next handler, `modify` replaces the input for later handlers and execution,
-`reject-and-continue` skips the original tool and returns a rejection payload to
-the model, `synthesize` skips the original tool and returns a synthetic output,
-and `error` fails the active run.
-
-```ts
-import { definePlugin } from "@minpeter/pss-runtime";
-
-const toolPolicyPlugin = definePlugin({
-  name: "tool-policy",
-  setup(host) {
-    host.on("tool.call", ({ input, tool }) => {
-      if (tool === "delete_file") {
-        return {
-          action: "reject-and-continue",
-          message: "delete_file is disabled in this workspace.",
-        };
-      }
-
-      if (tool === "search" && shouldNarrowSearch(input)) {
-        return { action: "modify", input: narrowSearchInput(input) };
-      }
-
-      return { action: "allow" };
-    });
+  sessions: {
+    namespace: "support-agent",
+    store: new MemorySessionStore(), // default when omitted
   },
 });
 ```
 
-`tool.result` runs after allowed/modified execution, rejected calls, synthesized
-calls, and original tool errors. It can observe or replace the model-facing
-result with `{ status: "done", output }`, `{ status: "error", error, output }`,
-or `{ status: "cancelled", error, output }`. Replacements flow into later
-`tool.result` handlers.
+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:
 
 ```ts
-const resultPolicyPlugin = definePlugin({
-  name: "tool-result-policy",
-  setup(host) {
-    host.on("tool.result", ({ output, status, tool }) => {
-      if (tool === "read_secret" && status === "done") {
-        return {
-          status: "done",
-          output: redactSecretOutput(output),
-        };
-      }
-    });
-  },
-});
-```
-
-Custom stores still own version generation through `SessionStore`. Use
-`sessions.custom(store)` when the runtime should persist through a caller-owned
-store:
+import { FileSessionStore } from "@minpeter/pss-runtime/session-store/file";
 
-```ts
-import type { SessionStore } from "@minpeter/pss-runtime";
-import { sessions } from "@minpeter/pss-runtime/plugins";
-
-declare const store: SessionStore;
-
-const agent = await Agent.create({
+const agent = new Agent({
   model,
-  plugins: [sessions.custom(store)],
+  sessions: {
+    namespace: "support-agent",
+    store: new FileSessionStore(".pss/sessions"),
+  },
 });
 ```
 
-Stored session state is opaque, versioned runtime continuation state:
-
-Do not inspect it as a replay log; exact replay should be modeled separately as
-an `AgentEvent` log if that capability is added later.
-
-`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: "conflict" }`. On
-success, the store persists `{ state, version }` and returns the new version to
-the runtime.
-
-`memory()` adds session-scoped tools named `set_context`, `load_context`, and
-`search_context`. Search is deterministic lexical matching by default; no
-embedding provider is required. Memory is injected into model-facing context
-without mutating top-level instructions.
-
-`compaction()` stores non-destructive overlays with `startIndex` and `endIndex`.
-The full canonical history remains in the session snapshot; summaries are
-applied only to model-facing context.
-
 ## Future adapter boundary: Cloudflare multi-user DX
 
 Cloudflare Durable Objects are a future adapter target, not a runtime dependency.

package/dist/agent-loop.js

@@ -1,10 +1,10 @@
 import { modelMessageToAgentEvents } from "./session/mapping.js";
 //#region src/agent-loop.ts
-async function runAgentLoop({ emit, history, llm, signal = new AbortController().signal, stepLifecycle }) {
+async function runAgentLoop({ emit, history, hooks, llm, signal = new AbortController().signal }) {
 	let stepIndex = 0;
 	while (true) {
 		if (signal.aborted) return "aborted";
-		await stepLifecycle?.beforeStep?.({
+		await hooks?.beforeStep?.({
 			history: history.modelSnapshot(),
 			signal,
 			stepIndex
@@ -15,12 +15,6 @@ async function runAgentLoop({ emit, history, llm, signal = new AbortController()
 			event: { type: "step-start" },
 			signal
 		}) === "aborted") return "aborted";
-		await stepLifecycle?.beforeInference?.({
-			history: history.modelSnapshot(),
-			signal,
-			stepIndex
-		});
-		if (signal.aborted) return "aborted";
 		const output = await readLlmOutput({
 			history,
 			llm,
@@ -34,7 +28,7 @@ async function runAgentLoop({ emit, history, llm, signal = new AbortController()
 			signal
 		});
 		if (result === "aborted") return "aborted";
-		await runAfterStepLifecycle(stepLifecycle, {
+		await runAfterStepHook(hooks, {
 			history: history.modelSnapshot(),
 			result,
 			signal,
@@ -46,7 +40,7 @@ async function runAgentLoop({ emit, history, llm, signal = new AbortController()
 			signal
 		});
 		if (stepEndDecision === "aborted") return "aborted";
-		if (result === "completed" && !stepEndDecision?.runtimeInputAdded && !stepEndDecision?.overlayInputAdded) return "completed";
+		if (result === "completed" && !stepEndDecision?.runtimeInputAdded) return "completed";
 		stepIndex += 1;
 	}
 }
@@ -74,10 +68,10 @@ function createAbortBoundary(signal) {
 		promise
 	};
 }
-async function runAfterStepLifecycle(stepLifecycle, context) {
-	const afterStep = stepLifecycle?.afterStep;
-	if (!afterStep) return;
-	await Promise.allSettled([Promise.resolve().then(() => afterStep(context))]);
+async function runAfterStepHook(hooks, context) {
+	const hook = hooks?.afterStep;
+	if (!hook) return;
+	await Promise.allSettled([Promise.resolve().then(() => hook(context))]);
 }
 async function readLlmOutput({ history, llm, signal }) {
 	try {

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 { Llm, LlmOutput } from \"./llm\";\nimport type { AgentEvent, AgentEventListener } from \"./session/events\";\nimport { modelMessageToAgentEvents } from \"./session/mapping\";\n\ntype MaybePromise<T> = Promise<T> | T;\n\ninterface ModelHistory {\n  appendModelMessage(message: ModelMessage): void;\n  modelSnapshot(): ModelMessage[];\n}\n\ninterface RunAgentLoopOptions {\n  emit: AgentLoopEventListener;\n  history: ModelHistory;\n  llm: Llm;\n  signal?: AbortSignal;\n  stepLifecycle?: AgentStepLifecycle;\n}\n\nexport type AgentLoopResult = \"completed\" | \"aborted\";\nexport type AgentStepResult = \"completed\" | \"continue\";\nexport interface AgentBeforeStepContext {\n  readonly history: readonly ModelMessage[];\n  readonly signal: AbortSignal;\n  readonly stepIndex: number;\n}\nexport interface AgentAfterStepContext extends AgentBeforeStepContext {\n  readonly result: AgentStepResult;\n}\nexport interface AgentStepLifecycle {\n  afterStep?(context: AgentAfterStepContext): MaybePromise<void>;\n  beforeInference?(context: AgentBeforeStepContext): MaybePromise<void>;\n  beforeStep?(context: AgentBeforeStepContext): MaybePromise<void>;\n}\ntype AgentLoopBoundaryEvent = Extract<\n  AgentEvent,\n  { type: \"step-end\" } | { type: \"step-start\" }\n>;\ninterface AgentLoopBoundaryDecision {\n  readonly overlayInputAdded?: boolean;\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  llm,\n  signal = new AbortController().signal,\n  stepLifecycle,\n}: RunAgentLoopOptions): Promise<AgentLoopResult> {\n  let stepIndex = 0;\n\n  while (true) {\n    if (signal.aborted) {\n      return \"aborted\";\n    }\n\n    await stepLifecycle?.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    await stepLifecycle?.beforeInference?.({\n      history: history.modelSnapshot(),\n      signal,\n      stepIndex,\n    });\n\n    if (signal.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 runAfterStepLifecycle(stepLifecycle, {\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 (\n      result === \"completed\" &&\n      !stepEndDecision?.runtimeInputAdded &&\n      !stepEndDecision?.overlayInputAdded\n    ) {\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 runAfterStepLifecycle(\n  stepLifecycle: AgentStepLifecycle | undefined,\n  context: AgentAfterStepContext\n): Promise<void> {\n  const afterStep = stepLifecycle?.afterStep;\n  if (!afterStep) {\n    return;\n  }\n\n  await Promise.allSettled([Promise.resolve().then(() => afterStep(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":";;AAmDA,eAAsB,aAAa,EACjC,MACA,SACA,KACA,SAAS,IAAI,gBAAgB,EAAE,QAC/B,iBACgD;CAChD,IAAI,YAAY;CAEhB,OAAO,MAAM;EACX,IAAI,OAAO,SACT,OAAO;EAGT,MAAM,eAAe,aAAa;GAChC,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,eAAe,kBAAkB;GACrC,SAAS,QAAQ,cAAc;GAC/B;GACA;EACF,CAAC;EAED,IAAI,OAAO,SACT,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,sBAAsB,eAAe;GACzC,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,IACE,WAAW,eACX,CAAC,iBAAiB,qBAClB,CAAC,iBAAiB,mBAElB,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,sBACb,eACA,SACe;CACf,MAAM,YAAY,eAAe;CACjC,IAAI,CAAC,WACH;CAGF,MAAM,QAAQ,WAAW,CAAC,QAAQ,QAAQ,EAAE,WAAW,UAAU,OAAO,CAAC,CAAC,CAAC;AAC7E;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 { 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"}

package/dist/agent-namespace.js

@@ -0,0 +1,17 @@
+//#region src/agent-namespace.ts
+function randomAgentNamespace() {
+	return agentNamespace(crypto.randomUUID());
+}
+function agentNamespace(namespace) {
+	return `agent:${namespacePart(namespace)}`;
+}
+function namespacePart(value) {
+	return encodeURIComponent(value);
+}
+function parentSessionNamespace({ generation, sessionKey, sessionNamespace }) {
+	return `${sessionNamespace}:session:${namespacePart(sessionKey)}:generation:${generation}`;
+}
+//#endregion
+export { agentNamespace, parentSessionNamespace, randomAgentNamespace };
+
+//# sourceMappingURL=agent-namespace.js.map

package/dist/agent-namespace.js.map

@@ -0,0 +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"}

package/dist/agent-validation.js

@@ -0,0 +1,35 @@
+//#region src/agent-validation.ts
+const subagentNamePattern = /^[a-z][a-z0-9_-]{0,51}$/;
+function assertSubagents(options, agentClass, hasCustomLlm) {
+	if (!("subagents" in options) || options.subagents === void 0) return;
+	if (hasCustomLlm) throw new TypeError("Agent: subagents require options.model.");
+	if (!Array.isArray(options.subagents)) throw new TypeError("Agent: subagents must be an array.");
+	assertSubagentTools(options.subagents, agentClass, options.tools ?? {});
+}
+function assertSubagentTools(subagents, agentClass, tools) {
+	const toolNames = new Set(Object.keys(tools));
+	const generatedToolNames = /* @__PURE__ */ new Set();
+	for (const [index, subagent] of subagents.entries()) {
+		const toolName = `delegate_to_${assertSubagentMetadata(subagent, index, agentClass).replaceAll("-", "_")}`;
+		if (toolNames.has(toolName)) throw new TypeError(`Agent: subagent tool ${toolName} collides with an existing tool.`);
+		if (generatedToolNames.has(toolName)) throw new TypeError(`Agent: duplicate subagent tool name ${toolName}.`);
+		generatedToolNames.add(toolName);
+	}
+	for (const reservedToolName of ["background_output", "background_cancel"]) if (toolNames.has(reservedToolName)) throw new TypeError(`Agent: ${reservedToolName} collides with a reserved subagent tool.`);
+}
+function assertSubagentMetadata(subagent, index, agentClass) {
+	if (!(subagent instanceof agentClass)) throw new TypeError(`Agent: subagents[${index}] must be an Agent.`);
+	if (!isValidSubagentName(subagent.name)) throw new TypeError(`Agent: subagents[${index}].name is required or too long.`);
+	if (!isNonEmptyText(subagent.description)) throw new TypeError(`Agent: subagents[${index}].description is required.`);
+	return subagent.name;
+}
+function isNonEmptyText(value) {
+	return typeof value === "string" && value.trim().length > 0;
+}
+function isValidSubagentName(value) {
+	return typeof value === "string" && subagentNamePattern.test(value);
+}
+//#endregion
+export { assertSubagents };
+
+//# sourceMappingURL=agent-validation.js.map

package/dist/agent-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-validation.js","names":[],"sources":["../src/agent-validation.ts"],"sourcesContent":["import type { ToolSet } from \"ai\";\nimport type { Agent, AgentOptions } from \"./agent\";\n\nconst subagentNamePattern = /^[a-z][a-z0-9_-]{0,51}$/;\n\nexport function assertSubagents(\n  options: AgentOptions,\n  agentClass: new (options: AgentOptions) => Agent,\n  hasCustomLlm: boolean\n): void {\n  if (!(\"subagents\" in options) || options.subagents === undefined) {\n    return;\n  }\n\n  if (hasCustomLlm) {\n    throw new TypeError(\"Agent: subagents require options.model.\");\n  }\n\n  if (!Array.isArray(options.subagents)) {\n    throw new TypeError(\"Agent: subagents must be an array.\");\n  }\n\n  assertSubagentTools(options.subagents, agentClass, options.tools ?? {});\n}\n\nfunction assertSubagentTools(\n  subagents: readonly Agent[],\n  agentClass: new (options: AgentOptions) => Agent,\n  tools: ToolSet\n): void {\n  const toolNames = new Set(Object.keys(tools));\n  const generatedToolNames = new Set<string>();\n  for (const [index, subagent] of subagents.entries()) {\n    const name = assertSubagentMetadata(subagent, index, agentClass);\n    const toolName = `delegate_to_${name.replaceAll(\"-\", \"_\")}`;\n    if (toolNames.has(toolName)) {\n      throw new TypeError(\n        `Agent: subagent tool ${toolName} collides with an existing tool.`\n      );\n    }\n\n    if (generatedToolNames.has(toolName)) {\n      throw new TypeError(`Agent: duplicate subagent tool name ${toolName}.`);\n    }\n\n    generatedToolNames.add(toolName);\n  }\n\n  for (const reservedToolName of [\"background_output\", \"background_cancel\"]) {\n    if (toolNames.has(reservedToolName)) {\n      throw new TypeError(\n        `Agent: ${reservedToolName} collides with a reserved subagent tool.`\n      );\n    }\n  }\n}\n\nfunction assertSubagentMetadata(\n  subagent: Agent,\n  index: number,\n  agentClass: new (options: AgentOptions) => Agent\n): string {\n  if (!(subagent instanceof agentClass)) {\n    throw new TypeError(`Agent: subagents[${index}] must be an Agent.`);\n  }\n\n  if (!isValidSubagentName(subagent.name)) {\n    throw new TypeError(\n      `Agent: subagents[${index}].name is required or too long.`\n    );\n  }\n\n  if (!isNonEmptyText(subagent.description)) {\n    throw new TypeError(`Agent: subagents[${index}].description is required.`);\n  }\n\n  return subagent.name;\n}\n\nfunction isNonEmptyText(value: string | undefined): value is string {\n  return typeof value === \"string\" && value.trim().length > 0;\n}\n\nfunction isValidSubagentName(value: string | undefined): value is string {\n  return typeof value === \"string\" && subagentNamePattern.test(value);\n}\n"],"mappings":";AAGA,MAAM,sBAAsB;AAE5B,SAAgB,gBACd,SACA,YACA,cACM;CACN,IAAI,EAAE,eAAe,YAAY,QAAQ,cAAc,KAAA,GACrD;CAGF,IAAI,cACF,MAAM,IAAI,UAAU,yCAAyC;CAG/D,IAAI,CAAC,MAAM,QAAQ,QAAQ,SAAS,GAClC,MAAM,IAAI,UAAU,oCAAoC;CAG1D,oBAAoB,QAAQ,WAAW,YAAY,QAAQ,SAAS,CAAC,CAAC;AACxE;AAEA,SAAS,oBACP,WACA,YACA,OACM;CACN,MAAM,YAAY,IAAI,IAAI,OAAO,KAAK,KAAK,CAAC;CAC5C,MAAM,qCAAqB,IAAI,IAAY;CAC3C,KAAK,MAAM,CAAC,OAAO,aAAa,UAAU,QAAQ,GAAG;EAEnD,MAAM,WAAW,eADJ,uBAAuB,UAAU,OAAO,UAClB,EAAE,WAAW,KAAK,GAAG;EACxD,IAAI,UAAU,IAAI,QAAQ,GACxB,MAAM,IAAI,UACR,wBAAwB,SAAS,iCACnC;EAGF,IAAI,mBAAmB,IAAI,QAAQ,GACjC,MAAM,IAAI,UAAU,uCAAuC,SAAS,EAAE;EAGxE,mBAAmB,IAAI,QAAQ;CACjC;CAEA,KAAK,MAAM,oBAAoB,CAAC,qBAAqB,mBAAmB,GACtE,IAAI,UAAU,IAAI,gBAAgB,GAChC,MAAM,IAAI,UACR,UAAU,iBAAiB,yCAC7B;AAGN;AAEA,SAAS,uBACP,UACA,OACA,YACQ;CACR,IAAI,EAAE,oBAAoB,aACxB,MAAM,IAAI,UAAU,oBAAoB,MAAM,oBAAoB;CAGpE,IAAI,CAAC,oBAAoB,SAAS,IAAI,GACpC,MAAM,IAAI,UACR,oBAAoB,MAAM,gCAC5B;CAGF,IAAI,CAAC,eAAe,SAAS,WAAW,GACtC,MAAM,IAAI,UAAU,oBAAoB,MAAM,2BAA2B;CAG3E,OAAO,SAAS;AAClB;AAEA,SAAS,eAAe,OAA4C;CAClE,OAAO,OAAO,UAAU,YAAY,MAAM,KAAK,EAAE,SAAS;AAC5D;AAEA,SAAS,oBAAoB,OAA4C;CACvE,OAAO,OAAO,UAAU,YAAY,oBAAoB,KAAK,KAAK;AACpE"}

package/dist/agent.d.ts

@@ -1,44 +1,55 @@
 import { AgentToolChoice, Llm } from "./llm.js";
 import { AgentInput } from "./session/input.js";
+import { AgentHooks } from "./hooks.js";
 import { AgentRun } from "./session/run.js";
-import { AgentPlugin } from "./plugins/types.js";
-import { AgentPluginErrorHandler } from "./session/lifecycle.js";
+import { SessionStore } from "./session/store/types.js";
 import { LanguageModel, ToolSet } from "ai";
 
 //#region src/agent.d.ts
 interface AgentLanguageModelOptions {
+  description?: string;
+  hooks?: AgentHooks;
   instructions?: string;
   llm?: never;
   model: LanguageModel;
-  onPluginError?: AgentPluginErrorHandler;
-  plugins?: readonly AgentPlugin[];
+  name?: string;
+  sessions?: AgentSessionOptions;
+  subagents?: readonly Agent[];
   toolChoice?: AgentToolChoice;
   tools?: ToolSet;
 }
 interface AgentLlmOptions {
+  description?: string;
+  hooks?: AgentHooks;
   instructions?: never;
   llm: Llm;
   model?: never;
-  onPluginError?: AgentPluginErrorHandler;
-  plugins?: readonly AgentPlugin[];
+  name?: string;
+  sessions?: AgentSessionOptions;
+  subagents?: never;
   toolChoice?: never;
   tools?: never;
 }
+interface AgentSessionOptions {
+  namespace?: string;
+  store?: SessionStore;
+}
 interface SessionHandle {
+  delete(): Promise<void>;
   interrupt(): void;
   kill(): void;
-  overlay(input: AgentInput): Promise<AgentRun>;
   send(input: AgentInput): Promise<AgentRun>;
   steer(input: AgentInput): Promise<AgentRun>;
 }
 type AgentOptions = AgentLanguageModelOptions | AgentLlmOptions;
 declare class Agent {
   #private;
-  private constructor();
-  static create(options: AgentOptions): Promise<Agent>;
+  readonly description?: string;
+  readonly name?: string;
+  constructor(options: AgentOptions);
   send(input: AgentInput): Promise<AgentRun>;
   session(key: string): SessionHandle;
 }
 //#endregion
-export { Agent, AgentOptions, SessionHandle };
+export { Agent, AgentOptions, AgentSessionOptions, SessionHandle };
 //# sourceMappingURL=agent.d.ts.map