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

package/README.md

@@ -28,7 +28,23 @@ 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.
+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.");
+  }
+}
+```
 
 Per-key conversations use `session(key)`:
 
@@ -122,46 +138,201 @@ 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.
 
-## Session storage and portability
+## 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
 
 The runtime owns full session state encoding and history compaction semantics.
-Adapters own persistence only through `SessionStore`:
+Persistence, memory, and compaction are configured through in-process plugins:
 
-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.
+```ts
+import { Agent } from "@minpeter/pss-runtime";
+import { compaction, memory, sessions } from "@minpeter/pss-runtime/plugins";
+
+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.
 
-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.
+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.
+
+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`.
 
 ```ts
-import type { SessionStore } from "@minpeter/pss-runtime";
-import { MemorySessionStore } from "@minpeter/pss-runtime/session-store/memory";
+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.");
+      }
+    });
+  },
+});
 
 const agent = await Agent.create({
   model,
-  sessions: {
-    store: new MemorySessionStore(), // default when omitted
+  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" };
+    });
   },
 });
 ```
 
-For durable sessions, use the exported file POC:
+`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.
 
 ```ts
-import { FileSessionStore } from "@minpeter/pss-runtime/session-store/file";
+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:
+
+```ts
+import type { SessionStore } from "@minpeter/pss-runtime";
+import { sessions } from "@minpeter/pss-runtime/plugins";
+
+declare const store: SessionStore;
 
 const agent = await Agent.create({
   model,
-  sessions: {
-    store: new FileSessionStore(".pss/sessions"),
-  },
+  plugins: [sessions.custom(store)],
 });
 ```
 
+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.d.ts

@@ -0,0 +1 @@
+import { ModelMessage } from "ai";

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, hooks, llm, signal = new AbortController().signal }) {
+async function runAgentLoop({ emit, history, llm, signal = new AbortController().signal, stepLifecycle }) {
 	let stepIndex = 0;
 	while (true) {
 		if (signal.aborted) return "aborted";
-		await hooks?.beforeStep?.({
+		await stepLifecycle?.beforeStep?.({
 			history: history.modelSnapshot(),
 			signal,
 			stepIndex
@@ -15,6 +15,12 @@ async function runAgentLoop({ emit, history, hooks, llm, signal = new AbortContr
 			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,
@@ -28,7 +34,7 @@ async function runAgentLoop({ emit, history, hooks, llm, signal = new AbortContr
 			signal
 		});
 		if (result === "aborted") return "aborted";
-		await runAfterStepHook(hooks, {
+		await runAfterStepLifecycle(stepLifecycle, {
 			history: history.modelSnapshot(),
 			result,
 			signal,
@@ -40,7 +46,7 @@ async function runAgentLoop({ emit, history, hooks, llm, signal = new AbortContr
 			signal
 		});
 		if (stepEndDecision === "aborted") return "aborted";
-		if (result === "completed" && !stepEndDecision?.runtimeInputAdded) return "completed";
+		if (result === "completed" && !stepEndDecision?.runtimeInputAdded && !stepEndDecision?.overlayInputAdded) return "completed";
 		stepIndex += 1;
 	}
 }
@@ -68,10 +74,10 @@ 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 runAfterStepLifecycle(stepLifecycle, context) {
+	const afterStep = stepLifecycle?.afterStep;
+	if (!afterStep) return;
+	await Promise.allSettled([Promise.resolve().then(() => afterStep(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 { 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 { 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"}

package/dist/agent.d.ts

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

package/dist/agent.js

@@ -1,25 +1,42 @@
 import { createLlm } from "./llm.js";
+import { resolveAgentPlugins } from "./plugins/runner.js";
 import { AgentSession } from "./session/session.js";
 import { MemorySessionStore } from "./session/store/memory.js";
 //#region src/agent.ts
 var Agent = class Agent {
-	#hooks;
+	#internalLlm;
 	#llm;
+	#onPluginError;
+	#plugins;
 	#sessions = /* @__PURE__ */ new Map();
 	#store;
-	constructor(options) {
+	constructor(options, resolvedPlugins) {
 		assertAgentOptions(options);
-		this.#store = options.sessions?.store ?? new MemorySessionStore();
-		this.#hooks = options.hooks;
-		this.#llm = hasCustomLlm(options) ? options.llm : createLlm({
-			instructions: options.instructions,
-			model: options.model,
-			toolChoice: options.toolChoice,
-			tools: options.tools
-		});
+		this.#plugins = resolvedPlugins;
+		this.#onPluginError = options.onPluginError;
+		this.#store = resolvedPlugins.sessionStore?.store ?? new MemorySessionStore();
+		if (hasCustomLlm(options)) {
+			this.#internalLlm = options.llm;
+			this.#llm = options.llm;
+		} else {
+			this.#internalLlm = createLlm({
+				instructions: options.instructions,
+				model: options.model
+			});
+			this.#llm = createLlm({
+				instructions: options.instructions,
+				model: options.model,
+				toolChoice: options.toolChoice,
+				tools: resolvedPlugins.tools
+			});
+		}
 	}
-	static create(options) {
-		return Promise.resolve().then(() => new Agent(options));
+	static async create(options) {
+		assertAgentOptions(options);
+		return new Agent(options, await resolveAgentPlugins({
+			callerTools: hasCustomLlm(options) ? void 0 : options.tools,
+			plugins: options.plugins
+		}));
 	}
 	send(input) {
 		return this.session("default").send(input);
@@ -30,13 +47,14 @@ var Agent = class Agent {
 		const session = new AgentSession(this.#llm, {
 			key,
 			store: this.#store
-		}, this.#hooks);
+		}, this.#plugins, this.#internalLlm, this.#onPluginError);
 		const handle = {
 			interrupt: () => session.interrupt(),
 			kill: () => {
 				session.kill();
 				this.#sessions.delete(key);
 			},
+			overlay: (input) => session.overlay(input),
 			send: (input) => session.send(input),
 			steer: (input) => session.steer(input)
 		};
@@ -46,10 +64,13 @@ var Agent = class Agent {
 };
 function assertAgentOptions(options) {
 	if (options === null || typeof options !== "object") throw new TypeError("Agent options are required. Provide either { model } or { llm }.");
+	if ("sessions" in options) throw new TypeError("Agent.create: options.sessions was removed. Use plugins: [sessions.custom(store)].");
+	if ("hooks" in options) throw new TypeError("Agent.create: options.hooks was removed. Use run.events() with session.steer() for app control or plugin lifecycle handlers for middleware.");
 	const hasLlm = hasCustomLlm(options);
 	const hasModel = "model" in options && options.model !== void 0 && options.model !== null;
 	if (hasLlm && hasModel) throw new TypeError("Agent.create: provide either options.llm or options.model, not both.");
 	if ("llm" in options && options.llm !== void 0 && !hasLlm) throw new TypeError("Agent.create: invalid options.llm.");
+	if ("onPluginError" in options && options.onPluginError !== void 0 && typeof options.onPluginError !== "function") throw new TypeError("Agent.create: invalid options.onPluginError.");
 	if (!(hasLlm || hasModel)) throw new TypeError("Agent.create: missing options.model.");
 }
 function hasCustomLlm(options) {

package/dist/agent.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent.js","names":["#hooks","#llm","#sessions","#store"],"sources":["../src/agent.ts"],"sourcesContent":["import type { LanguageModel, ToolSet } from \"ai\";\nimport type { AgentHooks } from \"./hooks\";\nimport { type AgentToolChoice, createLlm, type Llm } from \"./llm\";\nimport type { AgentRun } from \"./session/run\";\nimport { type AgentInput, AgentSession } from \"./session/session\";\nimport { MemorySessionStore } from \"./session/store/memory\";\nimport type { SessionStore } from \"./session/store/types\";\n\ninterface AgentLanguageModelOptions {\n  hooks?: AgentHooks;\n  instructions?: string;\n  llm?: never;\n  model: LanguageModel;\n  sessions?: AgentSessionOptions;\n  toolChoice?: AgentToolChoice;\n  tools?: ToolSet;\n}\n\ninterface AgentLlmOptions {\n  hooks?: AgentHooks;\n  instructions?: never;\n  llm: Llm;\n  model?: never;\n  sessions?: AgentSessionOptions;\n  toolChoice?: never;\n  tools?: never;\n}\n\nexport interface AgentSessionOptions {\n  store?: SessionStore;\n}\n\nexport interface SessionHandle {\n  interrupt(): void;\n  kill(): void;\n  send(input: AgentInput): Promise<AgentRun>;\n  steer(input: AgentInput): Promise<AgentRun>;\n}\n\nexport type AgentOptions = AgentLanguageModelOptions | AgentLlmOptions;\n\nexport class Agent {\n  readonly #hooks?: AgentHooks;\n  readonly #llm: Llm;\n  readonly #sessions = new Map<string, SessionHandle>();\n  readonly #store: SessionStore;\n\n  private constructor(options: AgentOptions) {\n    assertAgentOptions(options);\n\n    this.#store = options.sessions?.store ?? new MemorySessionStore();\n    this.#hooks = options.hooks;\n    this.#llm = hasCustomLlm(options)\n      ? options.llm\n      : createLlm({\n          instructions: options.instructions,\n          model: options.model,\n          toolChoice: options.toolChoice,\n          tools: options.tools,\n        });\n  }\n\n  static create(options: AgentOptions): Promise<Agent> {\n    return Promise.resolve().then(() => new Agent(options));\n  }\n\n  send(input: AgentInput): Promise<AgentRun> {\n    return this.session(\"default\").send(input);\n  }\n\n  session(key: string): SessionHandle {\n    const existing = this.#sessions.get(key);\n    if (existing) {\n      return existing;\n    }\n\n    const session = new AgentSession(\n      this.#llm,\n      { key, store: this.#store },\n      this.#hooks\n    );\n    const handle: SessionHandle = {\n      interrupt: () => session.interrupt(),\n      kill: () => {\n        session.kill();\n        this.#sessions.delete(key);\n      },\n      send: (input) => session.send(input),\n      steer: (input) => session.steer(input),\n    };\n    this.#sessions.set(key, handle);\n    return handle;\n  }\n}\n\nfunction assertAgentOptions(options: unknown): asserts options is AgentOptions {\n  if (options === null || typeof options !== \"object\") {\n    throw new TypeError(\n      \"Agent options are required. Provide either { model } or { llm }.\"\n    );\n  }\n\n  const hasLlm = hasCustomLlm(options);\n  const hasModel =\n    \"model\" in options && options.model !== undefined && options.model !== null;\n\n  if (hasLlm && hasModel) {\n    throw new TypeError(\n      \"Agent.create: provide either options.llm or options.model, not both.\"\n    );\n  }\n\n  if (\"llm\" in options && options.llm !== undefined && !hasLlm) {\n    throw new TypeError(\"Agent.create: invalid options.llm.\");\n  }\n\n  if (!(hasLlm || hasModel)) {\n    throw new TypeError(\"Agent.create: missing options.model.\");\n  }\n}\n\nfunction hasCustomLlm(options: object): options is AgentLlmOptions {\n  return \"llm\" in options && typeof options.llm === \"function\";\n}\n"],"mappings":";;;;AAyCA,IAAa,QAAb,MAAa,MAAM;CACjB;CACA;CACA,4BAAqB,IAAI,IAA2B;CACpD;CAEA,YAAoB,SAAuB;EACzC,mBAAmB,OAAO;EAE1B,KAAKG,SAAS,QAAQ,UAAU,SAAS,IAAI,mBAAmB;EAChE,KAAKH,SAAS,QAAQ;EACtB,KAAKC,OAAO,aAAa,OAAO,IAC5B,QAAQ,MACR,UAAU;GACR,cAAc,QAAQ;GACtB,OAAO,QAAQ;GACf,YAAY,QAAQ;GACpB,OAAO,QAAQ;EACjB,CAAC;CACP;CAEA,OAAO,OAAO,SAAuC;EACnD,OAAO,QAAQ,QAAQ,EAAE,WAAW,IAAI,MAAM,OAAO,CAAC;CACxD;CAEA,KAAK,OAAsC;EACzC,OAAO,KAAK,QAAQ,SAAS,EAAE,KAAK,KAAK;CAC3C;CAEA,QAAQ,KAA4B;EAClC,MAAM,WAAW,KAAKC,UAAU,IAAI,GAAG;EACvC,IAAI,UACF,OAAO;EAGT,MAAM,UAAU,IAAI,aAClB,KAAKD,MACL;GAAE;GAAK,OAAO,KAAKE;EAAO,GAC1B,KAAKH,MACP;EACA,MAAM,SAAwB;GAC5B,iBAAiB,QAAQ,UAAU;GACnC,YAAY;IACV,QAAQ,KAAK;IACb,KAAKE,UAAU,OAAO,GAAG;GAC3B;GACA,OAAO,UAAU,QAAQ,KAAK,KAAK;GACnC,QAAQ,UAAU,QAAQ,MAAM,KAAK;EACvC;EACA,KAAKA,UAAU,IAAI,KAAK,MAAM;EAC9B,OAAO;CACT;AACF;AAEA,SAAS,mBAAmB,SAAmD;CAC7E,IAAI,YAAY,QAAQ,OAAO,YAAY,UACzC,MAAM,IAAI,UACR,kEACF;CAGF,MAAM,SAAS,aAAa,OAAO;CACnC,MAAM,WACJ,WAAW,WAAW,QAAQ,UAAU,KAAA,KAAa,QAAQ,UAAU;CAEzE,IAAI,UAAU,UACZ,MAAM,IAAI,UACR,sEACF;CAGF,IAAI,SAAS,WAAW,QAAQ,QAAQ,KAAA,KAAa,CAAC,QACpD,MAAM,IAAI,UAAU,oCAAoC;CAG1D,IAAI,EAAE,UAAU,WACd,MAAM,IAAI,UAAU,sCAAsC;AAE9D;AAEA,SAAS,aAAa,SAA6C;CACjE,OAAO,SAAS,WAAW,OAAO,QAAQ,QAAQ;AACpD"}
+{"version":3,"file":"agent.js","names":["#internalLlm","#llm","#onPluginError","#plugins","#sessions","#store"],"sources":["../src/agent.ts"],"sourcesContent":["import type { LanguageModel, ToolSet } from \"ai\";\nimport { type AgentToolChoice, createLlm, type Llm } from \"./llm\";\nimport type { AgentPlugin } from \"./plugins\";\nimport {\n  type ResolvedAgentPlugins,\n  resolveAgentPlugins,\n} from \"./plugins/runner\";\nimport type { AgentPluginErrorHandler } from \"./session/lifecycle\";\nimport type { AgentRun } from \"./session/run\";\nimport { type AgentInput, AgentSession } from \"./session/session\";\nimport { MemorySessionStore } from \"./session/store/memory\";\nimport type { SessionStore } from \"./session/store/types\";\n\ninterface AgentLanguageModelOptions {\n  instructions?: string;\n  llm?: never;\n  model: LanguageModel;\n  onPluginError?: AgentPluginErrorHandler;\n  plugins?: readonly AgentPlugin[];\n  toolChoice?: AgentToolChoice;\n  tools?: ToolSet;\n}\n\ninterface AgentLlmOptions {\n  instructions?: never;\n  llm: Llm;\n  model?: never;\n  onPluginError?: AgentPluginErrorHandler;\n  plugins?: readonly AgentPlugin[];\n  toolChoice?: never;\n  tools?: never;\n}\n\nexport interface SessionHandle {\n  interrupt(): void;\n  kill(): void;\n  overlay(input: AgentInput): Promise<AgentRun>;\n  send(input: AgentInput): Promise<AgentRun>;\n  steer(input: AgentInput): Promise<AgentRun>;\n}\n\nexport type AgentOptions = AgentLanguageModelOptions | AgentLlmOptions;\n\nexport class Agent {\n  readonly #internalLlm: Llm;\n  readonly #llm: Llm;\n  readonly #onPluginError?: AgentPluginErrorHandler;\n  readonly #plugins: ResolvedAgentPlugins;\n  readonly #sessions = new Map<string, SessionHandle>();\n  readonly #store: SessionStore;\n\n  private constructor(\n    options: AgentOptions,\n    resolvedPlugins: ResolvedAgentPlugins\n  ) {\n    assertAgentOptions(options);\n\n    this.#plugins = resolvedPlugins;\n    this.#onPluginError = options.onPluginError;\n    this.#store =\n      resolvedPlugins.sessionStore?.store ?? new MemorySessionStore();\n    if (hasCustomLlm(options)) {\n      this.#internalLlm = options.llm;\n      this.#llm = options.llm;\n    } else {\n      this.#internalLlm = createLlm({\n        instructions: options.instructions,\n        model: options.model,\n      });\n      this.#llm = createLlm({\n        instructions: options.instructions,\n        model: options.model,\n        toolChoice: options.toolChoice,\n        tools: resolvedPlugins.tools,\n      });\n    }\n  }\n\n  static async create(options: AgentOptions): Promise<Agent> {\n    assertAgentOptions(options);\n    const resolvedPlugins = await resolveAgentPlugins({\n      callerTools: hasCustomLlm(options) ? undefined : options.tools,\n      plugins: options.plugins,\n    });\n    return new Agent(options, resolvedPlugins);\n  }\n\n  send(input: AgentInput): Promise<AgentRun> {\n    return this.session(\"default\").send(input);\n  }\n\n  session(key: string): SessionHandle {\n    const existing = this.#sessions.get(key);\n    if (existing) {\n      return existing;\n    }\n\n    const session = new AgentSession(\n      this.#llm,\n      { key, store: this.#store },\n      this.#plugins,\n      this.#internalLlm,\n      this.#onPluginError\n    );\n    const handle: SessionHandle = {\n      interrupt: () => session.interrupt(),\n      kill: () => {\n        session.kill();\n        this.#sessions.delete(key);\n      },\n      overlay: (input) => session.overlay(input),\n      send: (input) => session.send(input),\n      steer: (input) => session.steer(input),\n    };\n    this.#sessions.set(key, handle);\n    return handle;\n  }\n}\n\nfunction assertAgentOptions(options: unknown): asserts options is AgentOptions {\n  if (options === null || typeof options !== \"object\") {\n    throw new TypeError(\n      \"Agent options are required. Provide either { model } or { llm }.\"\n    );\n  }\n\n  if (\"sessions\" in options) {\n    throw new TypeError(\n      \"Agent.create: options.sessions was removed. Use plugins: [sessions.custom(store)].\"\n    );\n  }\n\n  if (\"hooks\" in options) {\n    throw new TypeError(\n      \"Agent.create: options.hooks was removed. Use run.events() with session.steer() for app control or plugin lifecycle handlers for middleware.\"\n    );\n  }\n\n  const hasLlm = hasCustomLlm(options);\n  const hasModel =\n    \"model\" in options && options.model !== undefined && options.model !== null;\n\n  if (hasLlm && hasModel) {\n    throw new TypeError(\n      \"Agent.create: provide either options.llm or options.model, not both.\"\n    );\n  }\n\n  if (\"llm\" in options && options.llm !== undefined && !hasLlm) {\n    throw new TypeError(\"Agent.create: invalid options.llm.\");\n  }\n\n  if (\n    \"onPluginError\" in options &&\n    options.onPluginError !== undefined &&\n    typeof options.onPluginError !== \"function\"\n  ) {\n    throw new TypeError(\"Agent.create: invalid options.onPluginError.\");\n  }\n\n  if (!(hasLlm || hasModel)) {\n    throw new TypeError(\"Agent.create: missing options.model.\");\n  }\n}\n\nfunction hasCustomLlm(options: object): options is AgentLlmOptions {\n  return \"llm\" in options && typeof options.llm === \"function\";\n}\n"],"mappings":";;;;;AA2CA,IAAa,QAAb,MAAa,MAAM;CACjB;CACA;CACA;CACA;CACA,4BAAqB,IAAI,IAA2B;CACpD;CAEA,YACE,SACA,iBACA;EACA,mBAAmB,OAAO;EAE1B,KAAKG,WAAW;EAChB,KAAKD,iBAAiB,QAAQ;EAC9B,KAAKG,SACH,gBAAgB,cAAc,SAAS,IAAI,mBAAmB;EAChE,IAAI,aAAa,OAAO,GAAG;GACzB,KAAKL,eAAe,QAAQ;GAC5B,KAAKC,OAAO,QAAQ;EACtB,OAAO;GACL,KAAKD,eAAe,UAAU;IAC5B,cAAc,QAAQ;IACtB,OAAO,QAAQ;GACjB,CAAC;GACD,KAAKC,OAAO,UAAU;IACpB,cAAc,QAAQ;IACtB,OAAO,QAAQ;IACf,YAAY,QAAQ;IACpB,OAAO,gBAAgB;GACzB,CAAC;EACH;CACF;CAEA,aAAa,OAAO,SAAuC;EACzD,mBAAmB,OAAO;EAK1B,OAAO,IAAI,MAAM,SAAS,MAJI,oBAAoB;GAChD,aAAa,aAAa,OAAO,IAAI,KAAA,IAAY,QAAQ;GACzD,SAAS,QAAQ;EACnB,CAAC,CACwC;CAC3C;CAEA,KAAK,OAAsC;EACzC,OAAO,KAAK,QAAQ,SAAS,EAAE,KAAK,KAAK;CAC3C;CAEA,QAAQ,KAA4B;EAClC,MAAM,WAAW,KAAKG,UAAU,IAAI,GAAG;EACvC,IAAI,UACF,OAAO;EAGT,MAAM,UAAU,IAAI,aAClB,KAAKH,MACL;GAAE;GAAK,OAAO,KAAKI;EAAO,GAC1B,KAAKF,UACL,KAAKH,cACL,KAAKE,cACP;EACA,MAAM,SAAwB;GAC5B,iBAAiB,QAAQ,UAAU;GACnC,YAAY;IACV,QAAQ,KAAK;IACb,KAAKE,UAAU,OAAO,GAAG;GAC3B;GACA,UAAU,UAAU,QAAQ,QAAQ,KAAK;GACzC,OAAO,UAAU,QAAQ,KAAK,KAAK;GACnC,QAAQ,UAAU,QAAQ,MAAM,KAAK;EACvC;EACA,KAAKA,UAAU,IAAI,KAAK,MAAM;EAC9B,OAAO;CACT;AACF;AAEA,SAAS,mBAAmB,SAAmD;CAC7E,IAAI,YAAY,QAAQ,OAAO,YAAY,UACzC,MAAM,IAAI,UACR,kEACF;CAGF,IAAI,cAAc,SAChB,MAAM,IAAI,UACR,oFACF;CAGF,IAAI,WAAW,SACb,MAAM,IAAI,UACR,6IACF;CAGF,MAAM,SAAS,aAAa,OAAO;CACnC,MAAM,WACJ,WAAW,WAAW,QAAQ,UAAU,KAAA,KAAa,QAAQ,UAAU;CAEzE,IAAI,UAAU,UACZ,MAAM,IAAI,UACR,sEACF;CAGF,IAAI,SAAS,WAAW,QAAQ,QAAQ,KAAA,KAAa,CAAC,QACpD,MAAM,IAAI,UAAU,oCAAoC;CAG1D,IACE,mBAAmB,WACnB,QAAQ,kBAAkB,KAAA,KAC1B,OAAO,QAAQ,kBAAkB,YAEjC,MAAM,IAAI,UAAU,8CAA8C;CAGpE,IAAI,EAAE,UAAU,WACd,MAAM,IAAI,UAAU,sCAAsC;AAE9D;AAEA,SAAS,aAAa,SAA6C;CACjE,OAAO,SAAS,WAAW,OAAO,QAAQ,QAAQ;AACpD"}

package/dist/index.d.ts

@@ -1,8 +1,12 @@
 import { AgentToolChoice, AgentToolExecute, AgentToolExecutionOptions, LlmOutputPart, RuntimeCreateLlmOptions, RuntimeLlm, RuntimeLlmContext, RuntimeLlmOutput, createLlm } from "./llm.js";
 import { AgentInput, SessionInput, UserInput, UserMessage, UserMessageContent, UserMessageContentPart, UserMessageFileData, UserMessageFilePart, UserMessageImagePart, UserMessageTextPart, UserText, UserTextContent } from "./session/input.js";
-import { AgentAfterStepContext, AgentAfterTurnContext, AgentBeforeStepContext, AgentBeforeTurnContext, AgentHooks, AgentStepResult, AgentTurnResult } from "./hooks.js";
-import { AgentEvent, AgentEventListener, AssistantReasoning, AssistantText, RuntimeInput, ToolCall, ToolResult } from "./session/events.js";
+import { AgentEvent, AgentEventListener, AssistantReasoning, AssistantText, OverlayAccepted, OverlayExpired, OverlayInputSummary, OverlayPlacement, RuntimeInput, ToolCall, ToolResult } from "./session/events.js";
 import { AgentRun } from "./session/run.js";
 import { CommitResult, ExpectedSessionVersion, SessionStore, SessionStoreCommit, StoredSession } from "./session/store/types.js";
-import { Agent, AgentOptions, AgentSessionOptions, SessionHandle } from "./agent.js";
-export { Agent, type AgentAfterStepContext, type AgentAfterTurnContext, type AgentBeforeStepContext, type AgentBeforeTurnContext, type AgentEvent, type AgentEventListener, type AgentHooks, type AgentInput, type AgentOptions, type AgentRun, type AgentSessionOptions, type AgentStepResult, type AgentToolChoice, type AgentToolExecute, type AgentToolExecutionOptions, type AgentTurnResult, type AssistantReasoning, type AssistantText, type CommitResult, type ExpectedSessionVersion, type LlmOutputPart, type RuntimeCreateLlmOptions, type RuntimeInput, type RuntimeLlm, type RuntimeLlmContext, type RuntimeLlmOutput, type SessionHandle, type SessionInput, type SessionStore, type SessionStoreCommit, type StoredSession, type ToolCall, type ToolResult, type UserInput, type UserMessage, type UserMessageContent, type UserMessageContentPart, type UserMessageFileData, type UserMessageFilePart, type UserMessageImagePart, type UserMessageTextPart, type UserText, type UserTextContent, createLlm };
+import { AgentContextTransform, AgentPlugin, AgentPluginEvent, AgentPluginEventFor, AgentPluginEventName, AgentPluginHandler, AgentPluginHandlerResult, AgentPluginHandlerReturn, AgentPluginHost, AgentPluginMaybePromise, AgentPluginStepAfterEvent, AgentPluginStepBeforeEvent, AgentPluginStepResult, AgentPluginToolCallEvent, AgentPluginToolCallResult, AgentPluginToolResultEvent, AgentPluginToolResultResult, AgentPluginToolResultStatus, AgentPluginToolSyntheticResult, AgentPluginTurnAfterEvent, AgentPluginTurnBeforeEvent, AgentPluginTurnResult, definePlugin } from "./plugins/types.js";
+import { CompactionOptions, compaction } from "./plugins/compaction.js";
+import { memory } from "./plugins/memory.js";
+import { sessions } from "./plugins/sessions.js";
+import { AgentPluginErrorHandler, AgentPluginHandlerError } from "./session/lifecycle.js";
+import { Agent, AgentOptions, SessionHandle } from "./agent.js";
+export { Agent, type AgentContextTransform, type AgentEvent, type AgentEventListener, type AgentInput, type AgentOptions, type AgentPlugin, type AgentPluginErrorHandler, type AgentPluginEvent, type AgentPluginEventFor, type AgentPluginEventName, type AgentPluginHandler, type AgentPluginHandlerError, type AgentPluginHandlerResult, type AgentPluginHandlerReturn, type AgentPluginHost, type AgentPluginMaybePromise, type AgentPluginStepAfterEvent, type AgentPluginStepBeforeEvent, type AgentPluginStepResult, type AgentPluginToolCallEvent, type AgentPluginToolCallResult, type AgentPluginToolResultEvent, type AgentPluginToolResultResult, type AgentPluginToolResultStatus, type AgentPluginToolSyntheticResult, type AgentPluginTurnAfterEvent, type AgentPluginTurnBeforeEvent, type AgentPluginTurnResult, type AgentRun, type AgentToolChoice, type AgentToolExecute, type AgentToolExecutionOptions, type AssistantReasoning, type AssistantText, type CommitResult, type CompactionOptions, type ExpectedSessionVersion, type LlmOutputPart, type OverlayAccepted, type OverlayExpired, type OverlayInputSummary, type OverlayPlacement, type RuntimeCreateLlmOptions, type RuntimeInput, type RuntimeLlm, type RuntimeLlmContext, type RuntimeLlmOutput, type SessionHandle, type SessionInput, type SessionStore, type SessionStoreCommit, type StoredSession, type ToolCall, type ToolResult, type UserInput, type UserMessage, type UserMessageContent, type UserMessageContentPart, type UserMessageFileData, type UserMessageFilePart, type UserMessageImagePart, type UserMessageTextPart, type UserText, type UserTextContent, compaction, createLlm, definePlugin, memory, sessions };

package/dist/index.js

@@ -1,3 +1,8 @@
 import { createLlm } from "./llm.js";
+import { definePlugin } from "./plugins/types.js";
 import { Agent } from "./agent.js";
-export { Agent, createLlm };
+import { compaction } from "./plugins/compaction.js";
+import { memory } from "./plugins/memory.js";
+import { sessions } from "./plugins/sessions.js";
+import "./plugins/index.js";
+export { Agent, compaction, createLlm, definePlugin, memory, sessions };

package/dist/llm.js

@@ -1,14 +1,20 @@
+import { wrapToolsWithPluginHooks } from "./plugins/tool-hooks.js";
 import { generateText } from "ai";
 //#region src/llm.ts
 function createLlm({ model, instructions, toolChoice, tools }) {
 	return async ({ history, signal }) => {
+		const scopedTools = wrapToolsWithPluginHooks({
+			history,
+			signal,
+			tools
+		});
 		const { responseMessages } = await generateText({
 			abortSignal: signal,
 			instructions,
 			messages: [...history],
 			model,
 			toolChoice,
-			tools
+			tools: scopedTools
 		});
 		return responseMessages;
 	};

package/dist/llm.js.map

@@ -1 +1 @@
-{"version":3,"file":"llm.js","names":[],"sources":["../src/llm.ts"],"sourcesContent":["import type {\n  LanguageModel,\n  ModelMessage,\n  Tool,\n  ToolExecutionOptions,\n  ToolSet,\n} from \"ai\";\nimport { generateText } from \"ai\";\n\nexport type AgentToolExecutionOptions = ToolExecutionOptions<unknown>;\nexport type AgentToolExecute = NonNullable<Tool[\"execute\"]>;\nexport type AgentToolChoice = \"auto\" | \"required\";\nexport type LlmOutput = Awaited<\n  ReturnType<typeof generateText>\n>[\"responseMessages\"];\nexport type LlmOutputPart = LlmOutput[number];\n\nexport interface LlmContext {\n  history: readonly ModelMessage[];\n  signal: AbortSignal;\n}\n\nexport type Llm = (context: LlmContext) => Promise<LlmOutput>;\n\nexport interface CreateLlmOptions {\n  instructions?: string;\n  model: LanguageModel;\n  toolChoice?: AgentToolChoice;\n  tools?: ToolSet;\n}\n\nexport type RuntimeCreateLlmOptions = CreateLlmOptions;\nexport type RuntimeLlm = Llm;\nexport type RuntimeLlmContext = LlmContext;\nexport type RuntimeLlmOutput = LlmOutput;\n\nexport function createLlm({\n  model,\n  instructions,\n  toolChoice,\n  tools,\n}: CreateLlmOptions): Llm {\n  return async ({ history, signal }) => {\n    const { responseMessages } = await generateText({\n      abortSignal: signal,\n      instructions,\n      messages: [...history],\n      model,\n      toolChoice,\n      tools,\n    });\n\n    return responseMessages;\n  };\n}\n"],"mappings":";;AAoCA,SAAgB,UAAU,EACxB,OACA,cACA,YACA,SACwB;CACxB,OAAO,OAAO,EAAE,SAAS,aAAa;EACpC,MAAM,EAAE,qBAAqB,MAAM,aAAa;GAC9C,aAAa;GACb;GACA,UAAU,CAAC,GAAG,OAAO;GACrB;GACA;GACA;EACF,CAAC;EAED,OAAO;CACT;AACF"}
+{"version":3,"file":"llm.js","names":[],"sources":["../src/llm.ts"],"sourcesContent":["import type {\n  LanguageModel,\n  ModelMessage,\n  Tool,\n  ToolExecutionOptions,\n  ToolSet,\n} from \"ai\";\nimport { generateText } from \"ai\";\nimport { wrapToolsWithPluginHooks } from \"./plugins/tool-hooks\";\n\nexport type AgentToolExecutionOptions = ToolExecutionOptions<unknown>;\nexport type AgentToolExecute = NonNullable<Tool[\"execute\"]>;\nexport type AgentToolChoice = \"auto\" | \"required\";\nexport type LlmOutput = Awaited<\n  ReturnType<typeof generateText>\n>[\"responseMessages\"];\nexport type LlmOutputPart = LlmOutput[number];\n\nexport interface LlmContext {\n  history: readonly ModelMessage[];\n  signal: AbortSignal;\n}\n\nexport type Llm = (context: LlmContext) => Promise<LlmOutput>;\n\nexport interface CreateLlmOptions {\n  instructions?: string;\n  model: LanguageModel;\n  toolChoice?: AgentToolChoice;\n  tools?: ToolSet;\n}\n\nexport type RuntimeCreateLlmOptions = CreateLlmOptions;\nexport type RuntimeLlm = Llm;\nexport type RuntimeLlmContext = LlmContext;\nexport type RuntimeLlmOutput = LlmOutput;\n\nexport function createLlm({\n  model,\n  instructions,\n  toolChoice,\n  tools,\n}: CreateLlmOptions): Llm {\n  return async ({ history, signal }) => {\n    const scopedTools = wrapToolsWithPluginHooks({\n      history,\n      signal,\n      tools,\n    });\n    const { responseMessages } = await generateText({\n      abortSignal: signal,\n      instructions,\n      messages: [...history],\n      model,\n      toolChoice,\n      tools: scopedTools,\n    });\n\n    return responseMessages;\n  };\n}\n"],"mappings":";;;AAqCA,SAAgB,UAAU,EACxB,OACA,cACA,YACA,SACwB;CACxB,OAAO,OAAO,EAAE,SAAS,aAAa;EACpC,MAAM,cAAc,yBAAyB;GAC3C;GACA;GACA;EACF,CAAC;EACD,MAAM,EAAE,qBAAqB,MAAM,aAAa;GAC9C,aAAa;GACb;GACA,UAAU,CAAC,GAAG,OAAO;GACrB;GACA;GACA,OAAO;EACT,CAAC;EAED,OAAO;CACT;AACF"}

package/dist/plugins/compaction.d.ts

@@ -0,0 +1,15 @@
+import { AgentPlugin } from "./types.js";
+import { ModelMessage } from "ai";
+
+//#region src/plugins/compaction.d.ts
+type CompactionSummarizer = (context: {
+  readonly messages: readonly ModelMessage[];
+}) => Promise<string> | string;
+interface CompactionOptions {
+  readonly summarize?: CompactionSummarizer;
+  readonly thresholdMessages?: number;
+}
+declare function compaction(options?: CompactionOptions): AgentPlugin;
+//#endregion
+export { CompactionOptions, compaction };
+//# sourceMappingURL=compaction.d.ts.map