@minpeter/pss-runtime 0.0.5 → 0.0.7

package/README.md

@@ -32,11 +32,53 @@ for await (const event of run.stream()) {
 
 `agent.send(...)` is shorthand for `agent.session("default").send(...)`.
 
+For model providers that support multimodal input, send JSON-serializable content
+parts through the same API. String input and `readonly string[]` remain supported
+shortcuts for text-only turns.
+
+```ts
+const run = await agent.send([
+  { type: "text", text: "Describe this UI screenshot." },
+  {
+    type: "image",
+    image: "data:image/png;base64,iVBORw0KGgo...",
+    mediaType: "image/png",
+  },
+]);
+```
+
+File parts use the same JSON-serializable shape when the selected model supports
+file input:
+
+```ts
+await agent.send([
+  { type: "text", text: "Summarize the attached report." },
+  {
+    type: "file",
+    data: "data:application/pdf;base64,JVBERi0x...",
+    filename: "report.pdf",
+    mediaType: "application/pdf",
+  },
+]);
+```
+
+The runtime normalizes and persists these content parts as session continuation
+state; it does not fetch remote media, decode files, or guarantee provider support
+for every media type.
+
+The public transcript protocol is `AgentEvent`: live runs emit runtime-defined
+events through `run.stream()`. Provider/model message history is internal
+continuation state, not a public history API.
+
 ## Session storage and portability
 
 The runtime owns full session state encoding and history compaction semantics.
 Adapters own persistence only through `SessionStore`:
 
+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 type { SessionStore } from "@minpeter/pss-runtime";
 import { MemorySessionStore } from "@minpeter/pss-runtime/session-store/memory";

package/dist/agent-loop.d.ts

@@ -1,5 +1,6 @@
 import { Llm } from "./llm.js";
 import { AgentEventListener } from "./session/events.js";
+import { AgentHooks } from "./hooks.js";
 import { ModelMessage } from "ai";
 
 //#region src/agent-loop.d.ts
@@ -10,6 +11,7 @@ interface ModelHistory {
 interface RunAgentLoopOptions {
   emit: AgentEventListener;
   history: ModelHistory;
+  hooks?: AgentHooks;
   llm: Llm;
   signal?: AbortSignal;
 }
@@ -17,6 +19,7 @@ type AgentLoopResult = "completed" | "aborted";
 declare function runAgentLoop({
   emit,
   history,
+  hooks,
   llm,
   signal
 }: RunAgentLoopOptions): Promise<AgentLoopResult>;

package/dist/agent-loop.js

@@ -1,7 +1,14 @@
 import { modelMessageToAgentEvents } from "./session/mapping.js";
 //#region src/agent-loop.ts
-async function runAgentLoop({ emit, history, llm, signal = new AbortController().signal }) {
+async function runAgentLoop({ emit, history, hooks, llm, signal = new AbortController().signal }) {
+	let stepIndex = 0;
 	while (true) {
+		if (signal.aborted) return "aborted";
+		await hooks?.beforeStep?.({
+			history: history.modelSnapshot(),
+			signal,
+			stepIndex
+		});
 		if (signal.aborted) return "aborted";
 		emit({ type: "step-start" });
 		const output = await readLlmOutput({
@@ -17,10 +24,22 @@ async function runAgentLoop({ emit, history, llm, signal = new AbortController()
 			signal
 		});
 		if (result === "aborted") return "aborted";
+		await runAfterStepHook(hooks, {
+			history: history.modelSnapshot(),
+			result,
+			signal,
+			stepIndex
+		});
 		emit({ type: "step-end" });
 		if (result === "completed") return "completed";
+		stepIndex += 1;
 	}
 }
+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 {
 		return await llm({

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 { 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: AgentEventListener;\n  history: ModelHistory;\n  llm: Llm;\n  signal?: AbortSignal;\n}\n\nexport type AgentLoopResult = \"completed\" | \"aborted\";\ntype StepOutputResult = \"continue\" | \"completed\" | \"aborted\";\n\nexport async function runAgentLoop({\n  emit,\n  history,\n  llm,\n  signal = new AbortController().signal,\n}: RunAgentLoopOptions): Promise<AgentLoopResult> {\n  while (true) {\n    if (signal.aborted) {\n      return \"aborted\";\n    }\n\n    emit({ type: \"step-start\" });\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    emit({ type: \"step-end\" });\n\n    if (result === \"completed\") {\n      return \"completed\";\n    }\n  }\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}: Pick<RunAgentLoopOptions, \"emit\" | \"history\"> & {\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":";;AAoBA,eAAsB,aAAa,EACjC,MACA,SACA,KACA,SAAS,IAAI,gBAAgB,EAAE,UACiB;CAChD,OAAO,MAAM;EACX,IAAI,OAAO,SACT,OAAO;EAGT,KAAK,EAAE,MAAM,aAAa,CAAC;EAC3B,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,KAAK,EAAE,MAAM,WAAW,CAAC;EAEzB,IAAI,WAAW,aACb,OAAO;CAEX;AACF;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 { 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: AgentEventListener;\n  history: ModelHistory;\n  hooks?: AgentHooks;\n  llm: Llm;\n  signal?: AbortSignal;\n}\n\nexport type AgentLoopResult = \"completed\" | \"aborted\";\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    emit({ type: \"step-start\" });\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    emit({ type: \"step-end\" });\n\n    if (result === \"completed\") {\n      return \"completed\";\n    }\n\n    stepIndex += 1;\n  }\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}: Pick<RunAgentLoopOptions, \"emit\" | \"history\"> & {\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":";;AAsBA,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;EAGT,KAAK,EAAE,MAAM,aAAa,CAAC;EAC3B,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;EACD,KAAK,EAAE,MAAM,WAAW,CAAC;EAEzB,IAAI,WAAW,aACb,OAAO;EAGT,aAAa;CACf;AACF;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.d.ts

@@ -1,22 +1,27 @@
-import { AgentTools, Llm } from "./llm.js";
+import { AgentToolChoice, AgentTools, Llm } from "./llm.js";
 import { AgentRun } from "./session/run.js";
 import { SessionStore } from "./session/store/types.js";
 import { AgentInput } from "./session/session.js";
+import { AgentHooks } from "./hooks.js";
 import { LanguageModel } from "ai";
 
 //#region src/agent.d.ts
 interface AgentModelOptions {
+  hooks?: AgentHooks;
   instructions?: string;
   llm?: never;
   model: LanguageModel;
   sessions?: AgentSessionOptions;
+  toolChoice?: AgentToolChoice;
   tools?: AgentTools;
 }
 interface AgentLlmOptions {
+  hooks?: AgentHooks;
   instructions?: never;
   llm: Llm;
   model?: never;
   sessions?: AgentSessionOptions;
+  toolChoice?: never;
   tools?: never;
 }
 interface AgentSessionOptions {

package/dist/agent.js

@@ -3,15 +3,18 @@ import { AgentSession } from "./session/session.js";
 import { MemorySessionStore } from "./session/store/memory.js";
 //#region src/agent.ts
 var Agent = class Agent {
+	#hooks;
 	#llm;
 	#sessions = /* @__PURE__ */ new Map();
 	#store;
 	constructor(options) {
 		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
 		});
 	}
@@ -27,7 +30,7 @@ var Agent = class Agent {
 		const session = new AgentSession(this.#llm, {
 			key,
 			store: this.#store
-		});
+		}, this.#hooks);
 		const handle = {
 			interrupt: () => session.interrupt(),
 			kill: () => {

package/dist/agent.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent.js","names":["#llm","#sessions","#store"],"sources":["../src/agent.ts"],"sourcesContent":["import type { LanguageModel } from \"ai\";\nimport { type AgentTools, 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 AgentModelOptions {\n  instructions?: string;\n  llm?: never;\n  model: LanguageModel;\n  sessions?: AgentSessionOptions;\n  tools?: AgentTools;\n}\n\ninterface AgentLlmOptions {\n  instructions?: never;\n  llm: Llm;\n  model?: never;\n  sessions?: AgentSessionOptions;\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}\n\nexport type AgentOptions = AgentModelOptions | AgentLlmOptions;\n\nexport class Agent {\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.#llm = hasCustomLlm(options)\n      ? options.llm\n      : createLlm({\n          instructions: options.instructions,\n          model: options.model,\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(this.#llm, { key, store: this.#store });\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    };\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":";;;;AAmCA,IAAa,QAAb,MAAa,MAAM;CACjB;CACA,4BAAqB,IAAI,IAA2B;CACpD;CAEA,YAAoB,SAAuB;EACzC,mBAAmB,OAAO;EAE1B,KAAKE,SAAS,QAAQ,UAAU,SAAS,IAAI,mBAAmB;EAChE,KAAKF,OAAO,aAAa,OAAO,IAC5B,QAAQ,MACR,UAAU;GACR,cAAc,QAAQ;GACtB,OAAO,QAAQ;GACf,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,aAAa,KAAKD,MAAM;GAAE;GAAK,OAAO,KAAKE;EAAO,CAAC;EACvE,MAAM,SAAwB;GAC5B,iBAAiB,QAAQ,UAAU;GACnC,YAAY;IACV,QAAQ,KAAK;IACb,KAAKD,UAAU,OAAO,GAAG;GAC3B;GACA,OAAO,UAAU,QAAQ,KAAK,KAAK;EACrC;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":["#hooks","#llm","#sessions","#store"],"sources":["../src/agent.ts"],"sourcesContent":["import type { LanguageModel } from \"ai\";\nimport type { AgentHooks } from \"./hooks\";\nimport {\n  type AgentToolChoice,\n  type AgentTools,\n  createLlm,\n  type Llm,\n} 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 AgentModelOptions {\n  hooks?: AgentHooks;\n  instructions?: string;\n  llm?: never;\n  model: LanguageModel;\n  sessions?: AgentSessionOptions;\n  toolChoice?: AgentToolChoice;\n  tools?: AgentTools;\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}\n\nexport type AgentOptions = AgentModelOptions | 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    };\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":";;;;AA6CA,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;EACrC;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"}

package/dist/hooks.d.ts

@@ -0,0 +1,32 @@
+import { RuntimeLlmContext } from "./llm.js";
+import { UserInput } from "./session/session.js";
+
+//#region src/hooks.d.ts
+type AgentTurnResult = "aborted" | "completed";
+type AgentStepResult = "completed" | "continue";
+type MaybePromise<T> = PromiseLike<T> | T;
+interface AgentBeforeTurnContext {
+  readonly history: RuntimeLlmContext["history"];
+  readonly input: UserInput;
+  readonly signal: AbortSignal;
+}
+interface AgentAfterTurnContext extends AgentBeforeTurnContext {
+  readonly result: AgentTurnResult;
+}
+interface AgentBeforeStepContext {
+  readonly history: RuntimeLlmContext["history"];
+  readonly signal: AbortSignal;
+  readonly stepIndex: number;
+}
+interface AgentAfterStepContext extends AgentBeforeStepContext {
+  readonly result: AgentStepResult;
+}
+interface AgentHooks {
+  afterStep?(context: AgentAfterStepContext): MaybePromise<void>;
+  afterTurn?(context: AgentAfterTurnContext): MaybePromise<void>;
+  beforeStep?(context: AgentBeforeStepContext): MaybePromise<void>;
+  beforeTurn?(context: AgentBeforeTurnContext): MaybePromise<void>;
+}
+//#endregion
+export { AgentAfterStepContext, AgentAfterTurnContext, AgentBeforeStepContext, AgentBeforeTurnContext, AgentHooks, AgentStepResult, AgentTurnResult };
+//# sourceMappingURL=hooks.d.ts.map

package/dist/index.d.ts

@@ -1,8 +1,9 @@
-import { AgentMessage, AgentModel, AgentTool, AgentToolExecute, AgentToolExecutionOptions, AgentTools, LlmOutputPart, RuntimeCreateLlmOptions, RuntimeLlm, RuntimeLlmContext, RuntimeLlmOutput, createLlm } from "./llm.js";
-import { AgentEvent, AgentEventListener, AssistantReasoning, AssistantText, ToolCall, ToolResult, UserText, UserTextContent } from "./session/events.js";
+import { AgentModel, AgentTool, AgentToolChoice, AgentToolExecute, AgentToolExecutionOptions, AgentTools, LlmOutputPart, RuntimeCreateLlmOptions, RuntimeLlm, RuntimeLlmContext, RuntimeLlmOutput, createLlm } from "./llm.js";
+import { AgentEvent, AgentEventListener, AssistantReasoning, AssistantText, ToolCall, ToolResult, UserMessage, UserMessageContent, UserMessageContentPart, UserMessageFileData, UserMessageFilePart, UserMessageImagePart, UserMessageTextPart, UserText, UserTextContent } from "./session/events.js";
 import { AgentRun } from "./session/run.js";
 import { CommitResult, ExpectedSessionVersion, SessionStore, StoredSession } from "./session/store/types.js";
-import { AgentInput } from "./session/session.js";
+import { AgentInput, SessionInput, UserInput } from "./session/session.js";
+import { AgentAfterStepContext, AgentAfterTurnContext, AgentBeforeStepContext, AgentBeforeTurnContext, AgentHooks, AgentStepResult, AgentTurnResult } from "./hooks.js";
 import { Agent, AgentOptions, AgentSessionOptions, SessionHandle } from "./agent.js";
 import { AgentLoopResult, runAgentLoop } from "./agent-loop.js";
-export { Agent, type AgentEvent, type AgentEventListener, type AgentInput, type AgentLoopResult, type AgentMessage, type AgentModel, type AgentOptions, type AgentRun, type AgentSessionOptions, type AgentTool, type AgentToolExecute, type AgentToolExecutionOptions, type AgentTools, type AssistantReasoning, type AssistantText, type CommitResult, type ExpectedSessionVersion, type LlmOutputPart, type RuntimeCreateLlmOptions, type RuntimeLlm, type RuntimeLlmContext, type RuntimeLlmOutput, type SessionHandle, type SessionStore, type StoredSession, type ToolCall, type ToolResult, type UserText, type UserTextContent, createLlm, runAgentLoop };
+export { Agent, type AgentAfterStepContext, type AgentAfterTurnContext, type AgentBeforeStepContext, type AgentBeforeTurnContext, type AgentEvent, type AgentEventListener, type AgentHooks, type AgentInput, type AgentLoopResult, type AgentModel, type AgentOptions, type AgentRun, type AgentSessionOptions, type AgentStepResult, type AgentTool, type AgentToolChoice, type AgentToolExecute, type AgentToolExecutionOptions, type AgentTools, type AgentTurnResult, type AssistantReasoning, type AssistantText, type CommitResult, type ExpectedSessionVersion, type LlmOutputPart, type RuntimeCreateLlmOptions, type RuntimeLlm, type RuntimeLlmContext, type RuntimeLlmOutput, type SessionHandle, type SessionInput, type SessionStore, 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, runAgentLoop };

package/dist/llm.d.ts

@@ -5,8 +5,8 @@ type AgentToolExecutionOptions = ToolExecutionOptions<unknown>;
 type AgentToolExecute = NonNullable<Tool["execute"]>;
 type AgentTool = Tool;
 type AgentTools = ToolSet;
+type AgentToolChoice = "auto" | "required";
 type AgentModel = LanguageModel;
-type AgentMessage = ModelMessage;
 type LlmOutput = Awaited<ReturnType<typeof generateText>>["responseMessages"];
 type LlmOutputPart = LlmOutput[number];
 interface LlmContext {
@@ -17,6 +17,7 @@ type Llm = (context: LlmContext) => Promise<LlmOutput>;
 interface CreateLlmOptions {
   instructions?: string;
   model: LanguageModel;
+  toolChoice?: AgentToolChoice;
   tools?: AgentTools;
 }
 type RuntimeCreateLlmOptions = CreateLlmOptions;
@@ -26,8 +27,9 @@ type RuntimeLlmOutput = LlmOutput;
 declare function createLlm({
   model,
   instructions,
+  toolChoice,
   tools
 }: CreateLlmOptions): Llm;
 //#endregion
-export { AgentMessage, AgentModel, AgentTool, AgentToolExecute, AgentToolExecutionOptions, AgentTools, Llm, LlmOutputPart, RuntimeCreateLlmOptions, RuntimeLlm, RuntimeLlmContext, RuntimeLlmOutput, createLlm };
+export { AgentModel, AgentTool, AgentToolChoice, AgentToolExecute, AgentToolExecutionOptions, AgentTools, Llm, LlmOutputPart, RuntimeCreateLlmOptions, RuntimeLlm, RuntimeLlmContext, RuntimeLlmOutput, createLlm };
 //# sourceMappingURL=llm.d.ts.map

package/dist/llm.js

@@ -1,12 +1,13 @@
 import { generateText } from "ai";
 //#region src/llm.ts
-function createLlm({ model, instructions, tools }) {
+function createLlm({ model, instructions, toolChoice, tools }) {
 	return async ({ history, signal }) => {
 		const { responseMessages } = await generateText({
 			abortSignal: signal,
 			instructions,
 			messages: [...history],
 			model,
+			toolChoice,
 			tools
 		});
 		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 AgentTool = Tool;\nexport type AgentTools = ToolSet;\nexport type AgentModel = LanguageModel;\nexport type AgentMessage = ModelMessage;\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  tools?: AgentTools;\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  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      tools,\n    });\n\n    return responseMessages;\n  };\n}\n"],"mappings":";;AAsCA,SAAgB,UAAU,EACxB,OACA,cACA,SACwB;CACxB,OAAO,OAAO,EAAE,SAAS,aAAa;EACpC,MAAM,EAAE,qBAAqB,MAAM,aAAa;GAC9C,aAAa;GACb;GACA,UAAU,CAAC,GAAG,OAAO;GACrB;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\";\n\nexport type AgentToolExecutionOptions = ToolExecutionOptions<unknown>;\nexport type AgentToolExecute = NonNullable<Tool[\"execute\"]>;\nexport type AgentTool = Tool;\nexport type AgentTools = ToolSet;\nexport type AgentToolChoice = \"auto\" | \"required\";\nexport type AgentModel = LanguageModel;\nexport type AgentMessage = ModelMessage;\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?: AgentTools;\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":";;AAwCA,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"}

package/dist/session/events.d.ts

@@ -4,6 +4,40 @@ interface UserText {
   text: UserTextContent;
   type: "user-text";
 }
+interface UserMessageTextPart {
+  text: string;
+  type: "text";
+}
+interface UserMessageImagePart {
+  image: string;
+  mediaType?: string;
+  type: "image";
+}
+type UserMessageFileData = string | {
+  data: string;
+  type: "data";
+} | {
+  reference: Record<string, string>;
+  type: "reference";
+} | {
+  text: string;
+  type: "text";
+} | {
+  type: "url";
+  url: string;
+};
+interface UserMessageFilePart {
+  data: UserMessageFileData;
+  filename?: string;
+  mediaType: string;
+  type: "file";
+}
+type UserMessageContentPart = UserMessageFilePart | UserMessageImagePart | UserMessageTextPart;
+type UserMessageContent = readonly UserMessageContentPart[];
+interface UserMessage {
+  content: UserMessageContent;
+  type: "user-message";
+}
 interface AssistantText {
   text: string;
   type: "assistant-text";
@@ -24,7 +58,7 @@ interface ToolResult {
   toolName: string;
   type: "tool-result";
 }
-type AgentEvent = /** User input was accepted into the session queue. */UserText /** A queued user input started running as a turn. */ | {
+type AgentEvent = /** User input was accepted into the session queue. */UserMessage | UserText /** User multipart input was accepted into the session queue. */ | UserMessage /** A queued user input started running as a turn. */ | {
   type: "turn-start";
 } /** The active turn was interrupted before normal completion. */ | {
   type: "turn-abort";
@@ -40,5 +74,5 @@ type AgentEvent = /** User input was accepted into the session queue. */UserText
 };
 type AgentEventListener = (event: AgentEvent) => void;
 //#endregion
-export { AgentEvent, AgentEventListener, AssistantReasoning, AssistantText, ToolCall, ToolResult, UserText, UserTextContent };
+export { AgentEvent, AgentEventListener, AssistantReasoning, AssistantText, ToolCall, ToolResult, UserMessage, UserMessageContent, UserMessageContentPart, UserMessageFileData, UserMessageFilePart, UserMessageImagePart, UserMessageTextPart, UserText, UserTextContent };
 //# sourceMappingURL=events.d.ts.map

package/dist/session/history.js

@@ -1,4 +1,4 @@
-import { userTextToModelMessage } from "./mapping.js";
+import { userInputToModelMessage } from "./mapping.js";
 //#region src/session/history.ts
 var AgentModelHistory = class {
 	#modelHistory = [];
@@ -11,7 +11,7 @@ var AgentModelHistory = class {
 		return structuredClone(this.#modelHistory);
 	}
 	appendUserInput(input) {
-		this.#modelHistory.push(userTextToModelMessage(input));
+		this.#modelHistory.push(userInputToModelMessage(input));
 		this.#triggerChange();
 	}
 	appendModelMessage(message) {

package/dist/session/history.js.map

@@ -1 +1 @@
-{"version":3,"file":"history.js","names":["#modelHistory","#onChange","#triggerChange"],"sources":["../../src/session/history.ts"],"sourcesContent":["import type { ModelMessage } from \"ai\";\nimport type { UserText } from \"./events\";\nimport { userTextToModelMessage } from \"./mapping\";\n\nexport class AgentModelHistory {\n  readonly #modelHistory: ModelMessage[] = [];\n  readonly #onChange?: (snapshot: ModelMessage[]) => void;\n\n  constructor(\n    history?: ModelMessage[],\n    onChange?: (snapshot: ModelMessage[]) => void\n  ) {\n    if (history) {\n      this.#modelHistory = structuredClone(history);\n    }\n    this.#onChange = onChange;\n  }\n\n  modelSnapshot(): ModelMessage[] {\n    return structuredClone(this.#modelHistory);\n  }\n\n  appendUserInput(input: UserText): void {\n    this.#modelHistory.push(userTextToModelMessage(input));\n    this.#triggerChange();\n  }\n\n  appendModelMessage(message: ModelMessage): void {\n    this.#modelHistory.push(structuredClone(message));\n    this.#triggerChange();\n  }\n\n  rollback(snapshot: ModelMessage[]): void {\n    this.#modelHistory.length = 0;\n    this.#modelHistory.push(...structuredClone(snapshot));\n    this.#triggerChange();\n  }\n\n  #triggerChange(): void {\n    this.#onChange?.(this.modelSnapshot());\n  }\n}\n"],"mappings":";;AAIA,IAAa,oBAAb,MAA+B;CAC7B,gBAAyC,CAAC;CAC1C;CAEA,YACE,SACA,UACA;EACA,IAAI,SACF,KAAKA,gBAAgB,gBAAgB,OAAO;EAE9C,KAAKC,YAAY;CACnB;CAEA,gBAAgC;EAC9B,OAAO,gBAAgB,KAAKD,aAAa;CAC3C;CAEA,gBAAgB,OAAuB;EACrC,KAAKA,cAAc,KAAK,uBAAuB,KAAK,CAAC;EACrD,KAAKE,eAAe;CACtB;CAEA,mBAAmB,SAA6B;EAC9C,KAAKF,cAAc,KAAK,gBAAgB,OAAO,CAAC;EAChD,KAAKE,eAAe;CACtB;CAEA,SAAS,UAAgC;EACvC,KAAKF,cAAc,SAAS;EAC5B,KAAKA,cAAc,KAAK,GAAG,gBAAgB,QAAQ,CAAC;EACpD,KAAKE,eAAe;CACtB;CAEA,iBAAuB;EACrB,KAAKD,YAAY,KAAK,cAAc,CAAC;CACvC;AACF"}
+{"version":3,"file":"history.js","names":["#modelHistory","#onChange","#triggerChange"],"sources":["../../src/session/history.ts"],"sourcesContent":["import type { ModelMessage } from \"ai\";\nimport { userInputToModelMessage } from \"./mapping\";\nimport type { UserInput } from \"./session\";\n\nexport class AgentModelHistory {\n  readonly #modelHistory: ModelMessage[] = [];\n  readonly #onChange?: (snapshot: ModelMessage[]) => void;\n\n  constructor(\n    history?: ModelMessage[],\n    onChange?: (snapshot: ModelMessage[]) => void\n  ) {\n    if (history) {\n      this.#modelHistory = structuredClone(history);\n    }\n    this.#onChange = onChange;\n  }\n\n  modelSnapshot(): ModelMessage[] {\n    return structuredClone(this.#modelHistory);\n  }\n\n  appendUserInput(input: UserInput): void {\n    this.#modelHistory.push(userInputToModelMessage(input));\n    this.#triggerChange();\n  }\n\n  appendModelMessage(message: ModelMessage): void {\n    this.#modelHistory.push(structuredClone(message));\n    this.#triggerChange();\n  }\n\n  rollback(snapshot: ModelMessage[]): void {\n    this.#modelHistory.length = 0;\n    this.#modelHistory.push(...structuredClone(snapshot));\n    this.#triggerChange();\n  }\n\n  #triggerChange(): void {\n    this.#onChange?.(this.modelSnapshot());\n  }\n}\n"],"mappings":";;AAIA,IAAa,oBAAb,MAA+B;CAC7B,gBAAyC,CAAC;CAC1C;CAEA,YACE,SACA,UACA;EACA,IAAI,SACF,KAAKA,gBAAgB,gBAAgB,OAAO;EAE9C,KAAKC,YAAY;CACnB;CAEA,gBAAgC;EAC9B,OAAO,gBAAgB,KAAKD,aAAa;CAC3C;CAEA,gBAAgB,OAAwB;EACtC,KAAKA,cAAc,KAAK,wBAAwB,KAAK,CAAC;EACtD,KAAKE,eAAe;CACtB;CAEA,mBAAmB,SAA6B;EAC9C,KAAKF,cAAc,KAAK,gBAAgB,OAAO,CAAC;EAChD,KAAKE,eAAe;CACtB;CAEA,SAAS,UAAgC;EACvC,KAAKF,cAAc,SAAS;EAC5B,KAAKA,cAAc,KAAK,GAAG,gBAAgB,QAAQ,CAAC;EACpD,KAAKE,eAAe;CACtB;CAEA,iBAAuB;EACrB,KAAKD,YAAY,KAAK,cAAc,CAAC;CACvC;AACF"}

package/dist/session/mapping.js

@@ -1,4 +1,8 @@
 //#region src/session/mapping.ts
+function userInputToModelMessage(input) {
+	if (input.type === "user-message") return userMessageToModelMessage(input);
+	return userTextToModelMessage(input);
+}
 function userTextToModelMessage(input) {
 	return {
 		role: "user",
@@ -12,6 +16,48 @@ function userTextContentToUserContent(text) {
 		text: part
 	}));
 }
+function userMessageToModelMessage(input) {
+	return {
+		role: "user",
+		content: userMessageContentToUserContent(input.content)
+	};
+}
+function userMessageContentToUserContent(content) {
+	return content.map(userMessageContentPartToUserContentPart);
+}
+function userMessageContentPartToUserContentPart(part) {
+	if (part.type === "text") return {
+		type: "text",
+		text: part.text
+	};
+	if (part.type === "image") return {
+		type: "file",
+		data: part.image,
+		mediaType: part.mediaType ?? "image"
+	};
+	return {
+		type: "file",
+		data: userMessageFileDataToFileData(part.data),
+		mediaType: part.mediaType,
+		...part.filename === void 0 ? {} : { filename: part.filename }
+	};
+}
+function userMessageFileDataToFileData(data) {
+	if (typeof data === "string") return data;
+	if (data.type === "url") return data.url;
+	if (data.type === "data") return {
+		type: "data",
+		data: data.data
+	};
+	if (data.type === "reference") return {
+		type: "reference",
+		reference: { ...data.reference }
+	};
+	return {
+		type: "text",
+		text: data.text
+	};
+}
 function modelMessageToAgentEvents(message) {
 	if (message.role === "assistant") return assistantReasoningFirstParts(assistantContentParts(message)).flatMap(assistantContentPartToEvents);
 	if (message.role === "tool") return message.content.flatMap(toolContentPartToEvents);
@@ -56,6 +102,6 @@ function toolResultPartToEvents(part) {
 	}];
 }
 //#endregion
-export { modelMessageToAgentEvents, userTextToModelMessage };
+export { modelMessageToAgentEvents, userInputToModelMessage };
 
 //# sourceMappingURL=mapping.js.map

package/dist/session/mapping.js.map

@@ -1 +1 @@
-{"version":3,"file":"mapping.js","names":[],"sources":["../../src/session/mapping.ts"],"sourcesContent":["import type {\n  AssistantContent,\n  AssistantModelMessage,\n  ModelMessage,\n  ToolModelMessage,\n  UserModelMessage,\n} from \"ai\";\nimport type {\n  AssistantReasoning,\n  AssistantText,\n  ToolCall,\n  ToolResult,\n  UserText,\n  UserTextContent,\n} from \"./events\";\n\ntype AssistantContentPart = Exclude<AssistantContent, string>[number];\ntype ToolContentPart = ToolModelMessage[\"content\"][number];\ntype ModelEvent = AssistantReasoning | AssistantText | ToolCall | ToolResult;\n\n// UserText -> AI SDK UserModelMessage\nexport function userTextToModelMessage(input: UserText): UserModelMessage {\n  return { role: \"user\", content: userTextContentToUserContent(input.text) };\n}\n\nfunction userTextContentToUserContent(\n  text: UserTextContent\n): UserModelMessage[\"content\"] {\n  if (typeof text === \"string\") {\n    return text;\n  }\n\n  return text.map((part) => ({ type: \"text\", text: part }));\n}\n\n// AI SDK ModelMessage -> public agent events\nexport function modelMessageToAgentEvents(message: ModelMessage): ModelEvent[] {\n  if (message.role === \"assistant\") {\n    return assistantReasoningFirstParts(assistantContentParts(message)).flatMap(\n      assistantContentPartToEvents\n    );\n  }\n\n  if (message.role === \"tool\") {\n    return message.content.flatMap(toolContentPartToEvents);\n  }\n\n  return [];\n}\n\nfunction assistantContentParts(\n  message: AssistantModelMessage\n): AssistantContentPart[] {\n  return typeof message.content === \"string\"\n    ? [{ type: \"text\", text: message.content }]\n    : message.content;\n}\n\nfunction assistantReasoningFirstParts(\n  parts: AssistantContentPart[]\n): AssistantContentPart[] {\n  return [\n    ...parts.filter((part) => part.type === \"reasoning\"),\n    ...parts.filter((part) => part.type !== \"reasoning\"),\n  ];\n}\n\nfunction assistantContentPartToEvents(\n  part: AssistantContentPart\n): ModelEvent[] {\n  if (part.type === \"text\") {\n    return part.text ? [{ type: \"assistant-text\", text: part.text }] : [];\n  }\n\n  if (part.type === \"reasoning\") {\n    return part.text ? [{ type: \"assistant-reasoning\", text: part.text }] : [];\n  }\n\n  if (part.type === \"tool-call\") {\n    return [\n      {\n        type: \"tool-call\",\n        input: part.input,\n        toolCallId: part.toolCallId,\n        toolName: part.toolName,\n      },\n    ];\n  }\n\n  return [];\n}\n\nfunction toolContentPartToEvents(part: ToolContentPart): ModelEvent[] {\n  if (part.type === \"tool-result\") {\n    return toolResultPartToEvents(part);\n  }\n\n  return [];\n}\n\nfunction toolResultPartToEvents(part: {\n  output: unknown;\n  toolCallId: string;\n  toolName: string;\n  type: \"tool-result\";\n}): ModelEvent[] {\n  return [\n    {\n      type: \"tool-result\",\n      output: part.output,\n      toolCallId: part.toolCallId,\n      toolName: part.toolName,\n    },\n  ];\n}\n"],"mappings":";AAqBA,SAAgB,uBAAuB,OAAmC;CACxE,OAAO;EAAE,MAAM;EAAQ,SAAS,6BAA6B,MAAM,IAAI;CAAE;AAC3E;AAEA,SAAS,6BACP,MAC6B;CAC7B,IAAI,OAAO,SAAS,UAClB,OAAO;CAGT,OAAO,KAAK,KAAK,UAAU;EAAE,MAAM;EAAQ,MAAM;CAAK,EAAE;AAC1D;AAGA,SAAgB,0BAA0B,SAAqC;CAC7E,IAAI,QAAQ,SAAS,aACnB,OAAO,6BAA6B,sBAAsB,OAAO,CAAC,EAAE,QAClE,4BACF;CAGF,IAAI,QAAQ,SAAS,QACnB,OAAO,QAAQ,QAAQ,QAAQ,uBAAuB;CAGxD,OAAO,CAAC;AACV;AAEA,SAAS,sBACP,SACwB;CACxB,OAAO,OAAO,QAAQ,YAAY,WAC9B,CAAC;EAAE,MAAM;EAAQ,MAAM,QAAQ;CAAQ,CAAC,IACxC,QAAQ;AACd;AAEA,SAAS,6BACP,OACwB;CACxB,OAAO,CACL,GAAG,MAAM,QAAQ,SAAS,KAAK,SAAS,WAAW,GACnD,GAAG,MAAM,QAAQ,SAAS,KAAK,SAAS,WAAW,CACrD;AACF;AAEA,SAAS,6BACP,MACc;CACd,IAAI,KAAK,SAAS,QAChB,OAAO,KAAK,OAAO,CAAC;EAAE,MAAM;EAAkB,MAAM,KAAK;CAAK,CAAC,IAAI,CAAC;CAGtE,IAAI,KAAK,SAAS,aAChB,OAAO,KAAK,OAAO,CAAC;EAAE,MAAM;EAAuB,MAAM,KAAK;CAAK,CAAC,IAAI,CAAC;CAG3E,IAAI,KAAK,SAAS,aAChB,OAAO,CACL;EACE,MAAM;EACN,OAAO,KAAK;EACZ,YAAY,KAAK;EACjB,UAAU,KAAK;CACjB,CACF;CAGF,OAAO,CAAC;AACV;AAEA,SAAS,wBAAwB,MAAqC;CACpE,IAAI,KAAK,SAAS,eAChB,OAAO,uBAAuB,IAAI;CAGpC,OAAO,CAAC;AACV;AAEA,SAAS,uBAAuB,MAKf;CACf,OAAO,CACL;EACE,MAAM;EACN,QAAQ,KAAK;EACb,YAAY,KAAK;EACjB,UAAU,KAAK;CACjB,CACF;AACF"}
+{"version":3,"file":"mapping.js","names":[],"sources":["../../src/session/mapping.ts"],"sourcesContent":["import type {\n  AssistantContent,\n  AssistantModelMessage,\n  ModelMessage,\n  ToolModelMessage,\n  UserModelMessage,\n} from \"ai\";\nimport type {\n  AssistantReasoning,\n  AssistantText,\n  ToolCall,\n  ToolResult,\n  UserMessage,\n  UserMessageContent,\n  UserMessageContentPart,\n  UserMessageFileData,\n  UserText,\n  UserTextContent,\n} from \"./events\";\nimport type { UserInput } from \"./session\";\n\ntype AssistantContentPart = Exclude<AssistantContent, string>[number];\ntype ToolContentPart = ToolModelMessage[\"content\"][number];\ntype ModelEvent = AssistantReasoning | AssistantText | ToolCall | ToolResult;\n\n// UserInput -> AI SDK UserModelMessage\nexport function userInputToModelMessage(input: UserInput): UserModelMessage {\n  if (input.type === \"user-message\") {\n    return userMessageToModelMessage(input);\n  }\n\n  return userTextToModelMessage(input);\n}\n\nexport function userTextToModelMessage(input: UserText): UserModelMessage {\n  return { role: \"user\", content: userTextContentToUserContent(input.text) };\n}\n\nfunction userTextContentToUserContent(\n  text: UserTextContent\n): UserModelMessage[\"content\"] {\n  if (typeof text === \"string\") {\n    return text;\n  }\n\n  return text.map((part) => ({ type: \"text\", text: part }));\n}\n\nexport function userMessageToModelMessage(\n  input: UserMessage\n): UserModelMessage {\n  return {\n    role: \"user\",\n    content: userMessageContentToUserContent(input.content),\n  };\n}\n\nfunction userMessageContentToUserContent(\n  content: UserMessageContent\n): Exclude<UserModelMessage[\"content\"], string> {\n  return content.map(userMessageContentPartToUserContentPart);\n}\n\nfunction userMessageContentPartToUserContentPart(\n  part: UserMessageContentPart\n): Exclude<UserModelMessage[\"content\"], string>[number] {\n  if (part.type === \"text\") {\n    return { type: \"text\", text: part.text };\n  }\n\n  if (part.type === \"image\") {\n    return {\n      type: \"file\",\n      data: part.image,\n      mediaType: part.mediaType ?? \"image\",\n    };\n  }\n\n  return {\n    type: \"file\",\n    data: userMessageFileDataToFileData(part.data),\n    mediaType: part.mediaType,\n    ...(part.filename === undefined ? {} : { filename: part.filename }),\n  };\n}\n\nfunction userMessageFileDataToFileData(\n  data: UserMessageFileData\n): Extract<\n  Exclude<UserModelMessage[\"content\"], string>[number],\n  { type: \"file\" }\n>[\"data\"] {\n  if (typeof data === \"string\") {\n    return data;\n  }\n\n  if (data.type === \"url\") {\n    return data.url;\n  }\n\n  if (data.type === \"data\") {\n    return { type: \"data\", data: data.data };\n  }\n\n  if (data.type === \"reference\") {\n    return { type: \"reference\", reference: { ...data.reference } };\n  }\n\n  return { type: \"text\", text: data.text };\n}\n\n// AI SDK ModelMessage -> public agent events\nexport function modelMessageToAgentEvents(message: ModelMessage): ModelEvent[] {\n  if (message.role === \"assistant\") {\n    return assistantReasoningFirstParts(assistantContentParts(message)).flatMap(\n      assistantContentPartToEvents\n    );\n  }\n\n  if (message.role === \"tool\") {\n    return message.content.flatMap(toolContentPartToEvents);\n  }\n\n  return [];\n}\n\nfunction assistantContentParts(\n  message: AssistantModelMessage\n): AssistantContentPart[] {\n  return typeof message.content === \"string\"\n    ? [{ type: \"text\", text: message.content }]\n    : message.content;\n}\n\nfunction assistantReasoningFirstParts(\n  parts: AssistantContentPart[]\n): AssistantContentPart[] {\n  return [\n    ...parts.filter((part) => part.type === \"reasoning\"),\n    ...parts.filter((part) => part.type !== \"reasoning\"),\n  ];\n}\n\nfunction assistantContentPartToEvents(\n  part: AssistantContentPart\n): ModelEvent[] {\n  if (part.type === \"text\") {\n    return part.text ? [{ type: \"assistant-text\", text: part.text }] : [];\n  }\n\n  if (part.type === \"reasoning\") {\n    return part.text ? [{ type: \"assistant-reasoning\", text: part.text }] : [];\n  }\n\n  if (part.type === \"tool-call\") {\n    return [\n      {\n        type: \"tool-call\",\n        input: part.input,\n        toolCallId: part.toolCallId,\n        toolName: part.toolName,\n      },\n    ];\n  }\n\n  return [];\n}\n\nfunction toolContentPartToEvents(part: ToolContentPart): ModelEvent[] {\n  if (part.type === \"tool-result\") {\n    return toolResultPartToEvents(part);\n  }\n\n  return [];\n}\n\nfunction toolResultPartToEvents(part: {\n  output: unknown;\n  toolCallId: string;\n  toolName: string;\n  type: \"tool-result\";\n}): ModelEvent[] {\n  return [\n    {\n      type: \"tool-result\",\n      output: part.output,\n      toolCallId: part.toolCallId,\n      toolName: part.toolName,\n    },\n  ];\n}\n"],"mappings":";AA0BA,SAAgB,wBAAwB,OAAoC;CAC1E,IAAI,MAAM,SAAS,gBACjB,OAAO,0BAA0B,KAAK;CAGxC,OAAO,uBAAuB,KAAK;AACrC;AAEA,SAAgB,uBAAuB,OAAmC;CACxE,OAAO;EAAE,MAAM;EAAQ,SAAS,6BAA6B,MAAM,IAAI;CAAE;AAC3E;AAEA,SAAS,6BACP,MAC6B;CAC7B,IAAI,OAAO,SAAS,UAClB,OAAO;CAGT,OAAO,KAAK,KAAK,UAAU;EAAE,MAAM;EAAQ,MAAM;CAAK,EAAE;AAC1D;AAEA,SAAgB,0BACd,OACkB;CAClB,OAAO;EACL,MAAM;EACN,SAAS,gCAAgC,MAAM,OAAO;CACxD;AACF;AAEA,SAAS,gCACP,SAC8C;CAC9C,OAAO,QAAQ,IAAI,uCAAuC;AAC5D;AAEA,SAAS,wCACP,MACsD;CACtD,IAAI,KAAK,SAAS,QAChB,OAAO;EAAE,MAAM;EAAQ,MAAM,KAAK;CAAK;CAGzC,IAAI,KAAK,SAAS,SAChB,OAAO;EACL,MAAM;EACN,MAAM,KAAK;EACX,WAAW,KAAK,aAAa;CAC/B;CAGF,OAAO;EACL,MAAM;EACN,MAAM,8BAA8B,KAAK,IAAI;EAC7C,WAAW,KAAK;EAChB,GAAI,KAAK,aAAa,KAAA,IAAY,CAAC,IAAI,EAAE,UAAU,KAAK,SAAS;CACnE;AACF;AAEA,SAAS,8BACP,MAIQ;CACR,IAAI,OAAO,SAAS,UAClB,OAAO;CAGT,IAAI,KAAK,SAAS,OAChB,OAAO,KAAK;CAGd,IAAI,KAAK,SAAS,QAChB,OAAO;EAAE,MAAM;EAAQ,MAAM,KAAK;CAAK;CAGzC,IAAI,KAAK,SAAS,aAChB,OAAO;EAAE,MAAM;EAAa,WAAW,EAAE,GAAG,KAAK,UAAU;CAAE;CAG/D,OAAO;EAAE,MAAM;EAAQ,MAAM,KAAK;CAAK;AACzC;AAGA,SAAgB,0BAA0B,SAAqC;CAC7E,IAAI,QAAQ,SAAS,aACnB,OAAO,6BAA6B,sBAAsB,OAAO,CAAC,EAAE,QAClE,4BACF;CAGF,IAAI,QAAQ,SAAS,QACnB,OAAO,QAAQ,QAAQ,QAAQ,uBAAuB;CAGxD,OAAO,CAAC;AACV;AAEA,SAAS,sBACP,SACwB;CACxB,OAAO,OAAO,QAAQ,YAAY,WAC9B,CAAC;EAAE,MAAM;EAAQ,MAAM,QAAQ;CAAQ,CAAC,IACxC,QAAQ;AACd;AAEA,SAAS,6BACP,OACwB;CACxB,OAAO,CACL,GAAG,MAAM,QAAQ,SAAS,KAAK,SAAS,WAAW,GACnD,GAAG,MAAM,QAAQ,SAAS,KAAK,SAAS,WAAW,CACrD;AACF;AAEA,SAAS,6BACP,MACc;CACd,IAAI,KAAK,SAAS,QAChB,OAAO,KAAK,OAAO,CAAC;EAAE,MAAM;EAAkB,MAAM,KAAK;CAAK,CAAC,IAAI,CAAC;CAGtE,IAAI,KAAK,SAAS,aAChB,OAAO,KAAK,OAAO,CAAC;EAAE,MAAM;EAAuB,MAAM,KAAK;CAAK,CAAC,IAAI,CAAC;CAG3E,IAAI,KAAK,SAAS,aAChB,OAAO,CACL;EACE,MAAM;EACN,OAAO,KAAK;EACZ,YAAY,KAAK;EACjB,UAAU,KAAK;CACjB,CACF;CAGF,OAAO,CAAC;AACV;AAEA,SAAS,wBAAwB,MAAqC;CACpE,IAAI,KAAK,SAAS,eAChB,OAAO,uBAAuB,IAAI;CAGpC,OAAO,CAAC;AACV;AAEA,SAAS,uBAAuB,MAKf;CACf,OAAO,CACL;EACE,MAAM;EACN,QAAQ,KAAK;EACb,YAAY,KAAK;EACjB,UAAU,KAAK;CACjB,CACF;AACF"}

package/dist/session/session.d.ts

@@ -1,8 +1,9 @@
-import { UserText } from "./events.js";
+import { UserMessage, UserMessageContentPart, UserText } from "./events.js";
 import { AgentRun } from "./run.js";
-
 //#region src/session/session.d.ts
-type AgentInput = string | readonly string[] | UserText;
+type UserInput = UserMessage | UserText;
+type AgentInput = readonly string[] | readonly UserMessageContentPart[] | string | UserInput;
+type SessionInput = AgentInput;
 //#endregion
-export { AgentInput };
+export { AgentInput, SessionInput, UserInput };
 //# sourceMappingURL=session.d.ts.map

package/dist/session/session.js

@@ -1,8 +1,10 @@
 import { runAgentLoop } from "../agent-loop.js";
 import { AgentModelHistory } from "./history.js";
 import { BufferedAgentRun } from "./run.js";
+import { decodeStoredSessionSnapshot, encodeSessionSnapshot } from "./snapshot.js";
 //#region src/session/session.ts
 var AgentSession = class {
+	#hooks;
 	#inputQueue = [];
 	#llm;
 	#persistence;
@@ -13,7 +15,8 @@ var AgentSession = class {
 	#loaded = false;
 	#running = false;
 	#storeVersion;
-	constructor(llm, persistence) {
+	constructor(llm, persistence, hooks) {
+		this.#hooks = hooks;
 		this.#llm = llm;
 		this.#persistence = persistence;
 	}
@@ -71,7 +74,7 @@ var AgentSession = class {
 	async #replaceWithStoredSession() {
 		const stored = await this.#persistence.store.load(this.#persistence.key);
 		this.#storeVersion = stored?.version;
-		this.#history = new AgentModelHistory(decodeStoredHistory(stored));
+		this.#history = new AgentModelHistory(decodeStoredSessionSnapshot(stored));
 	}
 	async #drainInputQueue() {
 		if (this.#running) return;
@@ -89,16 +92,28 @@ var AgentSession = class {
 		this.#activeAbort = new AbortController();
 		const historySnapshot = this.#history.modelSnapshot();
 		try {
+			await this.#hooks?.beforeTurn?.({
+				history: this.#history.modelSnapshot(),
+				input,
+				signal: this.#activeAbort.signal
+			});
 			run.emit({ type: "turn-start" });
 			this.#history.appendUserInput(input);
 			await this.#commitHistory();
 			const result = await runAgentLoop({
 				emit: (event) => run.emit(event),
 				history: this.#history,
+				hooks: this.#hooks,
 				llm: this.#llm,
 				signal: this.#activeAbort.signal
 			});
 			await this.#commitHistory();
+			await runAfterTurnHook(this.#hooks, {
+				history: this.#history.modelSnapshot(),
+				input,
+				result,
+				signal: this.#activeAbort.signal
+			});
 			run.emit({ type: result === "aborted" ? "turn-abort" : "turn-end" });
 		} catch (error) {
 			if (error instanceof SessionCommitConflictError) {
@@ -129,7 +144,7 @@ var AgentSession = class {
 	}
 	async #commitHistory() {
 		const result = await this.#persistence.store.commit(this.#persistence.key, {
-			state: encodeHistory(this.#history.modelSnapshot()),
+			state: encodeSessionSnapshot(this.#history.modelSnapshot()),
 			version: this.#storeVersion
 		}, { expectedVersion: this.#storeVersion ?? null });
 		if (!result.ok) {
@@ -139,6 +154,11 @@ var AgentSession = class {
 		this.#storeVersion = result.version;
 	}
 };
+async function runAfterTurnHook(hooks, context) {
+	const hook = hooks?.afterTurn;
+	if (!hook) return;
+	await Promise.allSettled([Promise.resolve().then(() => hook(context))]);
+}
 function normalizeAgentInput(input) {
 	if (typeof input === "string") return {
 		type: "user-text",
@@ -148,22 +168,43 @@ function normalizeAgentInput(input) {
 		type: "user-text",
 		text: structuredClone(input)
 	};
+	if (isArrayInput(input)) {
+		assertUserMessageContent(input);
+		return {
+			type: "user-message",
+			content: structuredClone(input)
+		};
+	}
+	if (isUserMessage(input)) assertUserMessageContent(input.content);
 	return structuredClone(input);
 }
 function isStringArrayInput(input) {
+	return isArrayInput(input) && input.every((part) => typeof part === "string");
+}
+function isArrayInput(input) {
 	return Array.isArray(input);
 }
-function encodeHistory(history) {
-	return {
-		schemaVersion: 1,
-		history
-	};
+function isUserMessage(input) {
+	return input.type === "user-message";
+}
+function assertUserMessageContent(input) {
+	for (const part of input) if (!isUserMessageContentPart(part)) throw new TypeError("Agent input content parts must be { type: \"text\", text }, { type: \"image\", image }, or { type: \"file\", data, mediaType }.");
+}
+function isUserMessageContentPart(part) {
+	if (part === null || typeof part !== "object" || !("type" in part)) return false;
+	if (part.type === "text") return "text" in part && typeof part.text === "string";
+	if (part.type === "image") return "image" in part && typeof part.image === "string" && (!("mediaType" in part) || typeof part.mediaType === "string");
+	if (part.type === "file") return "data" in part && isUserMessageFileData(part.data) && "mediaType" in part && typeof part.mediaType === "string" && (!("filename" in part) || typeof part.filename === "string");
+	return false;
 }
-function decodeStoredHistory(stored) {
-	if (!stored) return [];
-	const state = stored.state;
-	if (state !== null && typeof state === "object" && "schemaVersion" in state && state.schemaVersion === 1 && "history" in state && Array.isArray(state.history)) return structuredClone(state.history);
-	throw new Error("Unsupported stored session state");
+function isUserMessageFileData(data) {
+	if (typeof data === "string") return true;
+	if (data === null || typeof data !== "object" || !("type" in data)) return false;
+	if (data.type === "data") return "data" in data && typeof data.data === "string";
+	if (data.type === "reference") return "reference" in data && data.reference !== null && typeof data.reference === "object" && Object.values(data.reference).every((value) => typeof value === "string");
+	if (data.type === "text") return "text" in data && typeof data.text === "string";
+	if (data.type === "url") return "url" in data && typeof data.url === "string";
+	return false;
 }
 function errorMessage(error) {
 	if (error instanceof Error) return error.message;

package/dist/session/session.js.map

@@ -1 +1 @@
-{"version":3,"file":"session.js","names":["#inputQueue","#llm","#persistence","#killed","#ensureLoaded","#drainInputQueue","#activeAbort","#loaded","#loadPromise","#loadSessionState","#replaceWithStoredSession","#storeVersion","#history","#running","#processQueuedInput","#commitHistory"],"sources":["../../src/session/session.ts"],"sourcesContent":["import { runAgentLoop } from \"../agent-loop\";\nimport type { AgentMessage, Llm } from \"../llm\";\nimport type { UserText } from \"./events\";\nimport { AgentModelHistory } from \"./history\";\nimport type { AgentRun } from \"./run\";\nimport { BufferedAgentRun } from \"./run\";\nimport type { SessionStore, StoredSession } from \"./store/types\";\n\nexport type AgentInput = string | readonly string[] | UserText;\nexport type SessionInput = AgentInput;\nexport type { AgentRun } from \"./run\";\n\ninterface SessionPersistenceOptions {\n  readonly key: string;\n  readonly store: SessionStore;\n}\n\ninterface QueuedInput {\n  readonly input: UserText;\n  readonly run: BufferedAgentRun;\n}\n\ninterface EncodedSessionState {\n  readonly history: AgentMessage[];\n  readonly schemaVersion: 1;\n}\n\nexport class AgentSession {\n  readonly #inputQueue: QueuedInput[] = [];\n  readonly #llm: Llm;\n  readonly #persistence: SessionPersistenceOptions;\n  #activeAbort?: AbortController;\n  #history = new AgentModelHistory();\n  #killed = false;\n  #loadPromise?: Promise<void>;\n  #loaded = false;\n  #running = false;\n  #storeVersion: string | undefined;\n\n  constructor(llm: Llm, persistence: SessionPersistenceOptions) {\n    this.#llm = llm;\n    this.#persistence = persistence;\n  }\n\n  async send(input: AgentInput): Promise<AgentRun> {\n    if (this.#killed) {\n      throw sessionKilledError();\n    }\n\n    await this.#ensureLoaded();\n\n    if (this.#killed) {\n      throw sessionKilledError();\n    }\n\n    const acceptedInput = normalizeAgentInput(input);\n    const run = new BufferedAgentRun();\n    run.emit(acceptedInput);\n    this.#inputQueue.push({ input: structuredClone(acceptedInput), run });\n    this.#drainInputQueue().catch((error: unknown) => {\n      run.emit({ type: \"turn-error\", message: errorMessage(error) });\n      run.close();\n    });\n    return run;\n  }\n\n  interrupt(): void {\n    this.#activeAbort?.abort();\n  }\n\n  kill(): void {\n    if (this.#killed) {\n      return;\n    }\n\n    this.#killed = true;\n    this.#activeAbort?.abort();\n\n    while (this.#inputQueue.length > 0) {\n      const item = this.#inputQueue.shift();\n      item?.run.emit({\n        type: \"turn-error\",\n        message: sessionKilledError().message,\n      });\n      item?.run.close();\n    }\n  }\n\n  async #ensureLoaded(): Promise<void> {\n    if (this.#loaded) {\n      return;\n    }\n\n    this.#loadPromise ??= this.#loadSessionState();\n    try {\n      await this.#loadPromise;\n    } catch (error) {\n      this.#loadPromise = undefined;\n      throw error;\n    }\n  }\n\n  async #loadSessionState(): Promise<void> {\n    if (this.#loaded) {\n      return;\n    }\n\n    await this.#replaceWithStoredSession();\n    this.#loaded = true;\n  }\n\n  async #replaceWithStoredSession(): Promise<void> {\n    const stored = await this.#persistence.store.load(this.#persistence.key);\n    this.#storeVersion = stored?.version;\n    this.#history = new AgentModelHistory(decodeStoredHistory(stored));\n  }\n\n  async #drainInputQueue(): Promise<void> {\n    if (this.#running) {\n      return;\n    }\n\n    this.#running = true;\n    try {\n      while (!this.#killed && this.#inputQueue.length > 0) {\n        const item = this.#inputQueue.shift();\n        if (item) {\n          await this.#processQueuedInput(item);\n        }\n      }\n    } finally {\n      this.#running = false;\n    }\n  }\n\n  async #processQueuedInput({ input, run }: QueuedInput): Promise<void> {\n    this.#activeAbort = new AbortController();\n    const historySnapshot = this.#history.modelSnapshot();\n\n    try {\n      run.emit({ type: \"turn-start\" });\n      this.#history.appendUserInput(input);\n      await this.#commitHistory();\n\n      const result = await runAgentLoop({\n        emit: (event) => run.emit(event),\n        history: this.#history,\n        llm: this.#llm,\n        signal: this.#activeAbort.signal,\n      });\n\n      await this.#commitHistory();\n      run.emit({ type: result === \"aborted\" ? \"turn-abort\" : \"turn-end\" });\n    } catch (error) {\n      if (error instanceof SessionCommitConflictError) {\n        run.emit({ type: \"turn-error\", message: error.message });\n        return;\n      }\n\n      this.#history.rollback(historySnapshot);\n      try {\n        await this.#commitHistory();\n      } catch (rollbackError) {\n        run.emit({\n          type: \"turn-error\",\n          message: `${errorMessage(error)}; history rollback persistence failed: ${errorMessage(\n            rollbackError\n          )}`,\n        });\n        return;\n      }\n      run.emit({ type: \"turn-error\", message: errorMessage(error) });\n    } finally {\n      run.close();\n      this.#activeAbort = undefined;\n    }\n  }\n\n  async #commitHistory(): Promise<void> {\n    const result = await this.#persistence.store.commit(\n      this.#persistence.key,\n      {\n        state: encodeHistory(this.#history.modelSnapshot()),\n        version: this.#storeVersion,\n      },\n      { expectedVersion: this.#storeVersion ?? null }\n    );\n\n    if (!result.ok) {\n      await this.#replaceWithStoredSession();\n      throw new SessionCommitConflictError(this.#persistence.key);\n    }\n\n    this.#storeVersion = result.version;\n  }\n}\n\nexport function normalizeAgentInput(input: AgentInput): UserText {\n  if (typeof input === \"string\") {\n    return {\n      type: \"user-text\",\n      text: input,\n    };\n  }\n\n  if (isStringArrayInput(input)) {\n    return {\n      type: \"user-text\",\n      text: structuredClone(input) as readonly string[],\n    };\n  }\n\n  return structuredClone(input);\n}\n\nfunction isStringArrayInput(input: AgentInput): input is readonly string[] {\n  return Array.isArray(input);\n}\n\nfunction encodeHistory(history: AgentMessage[]): EncodedSessionState {\n  return { schemaVersion: 1, history };\n}\n\nfunction decodeStoredHistory(stored: StoredSession | null): AgentMessage[] {\n  if (!stored) {\n    return [];\n  }\n\n  const state = stored.state;\n  if (\n    state !== null &&\n    typeof state === \"object\" &&\n    \"schemaVersion\" in state &&\n    state.schemaVersion === 1 &&\n    \"history\" in state &&\n    Array.isArray(state.history)\n  ) {\n    return structuredClone(state.history) as AgentMessage[];\n  }\n\n  throw new Error(\"Unsupported stored session state\");\n}\n\nfunction errorMessage(error: unknown): string {\n  if (error instanceof Error) {\n    return error.message;\n  }\n\n  return String(error);\n}\n\nfunction sessionKilledError(): Error {\n  return new Error(\"Session killed\");\n}\n\nclass SessionCommitConflictError extends Error {\n  constructor(key: string) {\n    super(`Session ${JSON.stringify(key)} commit conflict`);\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"session.js","names":["#hooks","#inputQueue","#llm","#persistence","#killed","#ensureLoaded","#drainInputQueue","#activeAbort","#loaded","#loadPromise","#loadSessionState","#replaceWithStoredSession","#storeVersion","#history","#running","#processQueuedInput","#commitHistory"],"sources":["../../src/session/session.ts"],"sourcesContent":["import { runAgentLoop } from \"../agent-loop\";\nimport type { AgentHooks } from \"../hooks\";\nimport type { Llm } from \"../llm\";\nimport type { UserMessage, UserMessageContentPart, UserText } from \"./events\";\nimport { AgentModelHistory } from \"./history\";\nimport type { AgentRun } from \"./run\";\nimport { BufferedAgentRun } from \"./run\";\nimport { decodeStoredSessionSnapshot, encodeSessionSnapshot } from \"./snapshot\";\nimport type { SessionStore } from \"./store/types\";\n\nexport type UserInput = UserMessage | UserText;\nexport type AgentInput =\n  | readonly string[]\n  | readonly UserMessageContentPart[]\n  | string\n  | UserInput;\nexport type SessionInput = AgentInput;\nexport type { AgentRun } from \"./run\";\n\ninterface SessionPersistenceOptions {\n  readonly key: string;\n  readonly store: SessionStore;\n}\n\ninterface QueuedInput {\n  readonly input: UserInput;\n  readonly run: BufferedAgentRun;\n}\n\nexport class AgentSession {\n  readonly #hooks?: AgentHooks;\n  readonly #inputQueue: QueuedInput[] = [];\n  readonly #llm: Llm;\n  readonly #persistence: SessionPersistenceOptions;\n  #activeAbort?: AbortController;\n  #history = new AgentModelHistory();\n  #killed = false;\n  #loadPromise?: Promise<void>;\n  #loaded = false;\n  #running = false;\n  #storeVersion: string | undefined;\n\n  constructor(\n    llm: Llm,\n    persistence: SessionPersistenceOptions,\n    hooks?: AgentHooks\n  ) {\n    this.#hooks = hooks;\n    this.#llm = llm;\n    this.#persistence = persistence;\n  }\n\n  async send(input: AgentInput): Promise<AgentRun> {\n    if (this.#killed) {\n      throw sessionKilledError();\n    }\n\n    await this.#ensureLoaded();\n\n    if (this.#killed) {\n      throw sessionKilledError();\n    }\n\n    const acceptedInput = normalizeAgentInput(input);\n    const run = new BufferedAgentRun();\n    run.emit(acceptedInput);\n    this.#inputQueue.push({ input: structuredClone(acceptedInput), run });\n    this.#drainInputQueue().catch((error: unknown) => {\n      run.emit({ type: \"turn-error\", message: errorMessage(error) });\n      run.close();\n    });\n    return run;\n  }\n\n  interrupt(): void {\n    this.#activeAbort?.abort();\n  }\n\n  kill(): void {\n    if (this.#killed) {\n      return;\n    }\n\n    this.#killed = true;\n    this.#activeAbort?.abort();\n\n    while (this.#inputQueue.length > 0) {\n      const item = this.#inputQueue.shift();\n      item?.run.emit({\n        type: \"turn-error\",\n        message: sessionKilledError().message,\n      });\n      item?.run.close();\n    }\n  }\n\n  async #ensureLoaded(): Promise<void> {\n    if (this.#loaded) {\n      return;\n    }\n\n    this.#loadPromise ??= this.#loadSessionState();\n    try {\n      await this.#loadPromise;\n    } catch (error) {\n      this.#loadPromise = undefined;\n      throw error;\n    }\n  }\n\n  async #loadSessionState(): Promise<void> {\n    if (this.#loaded) {\n      return;\n    }\n\n    await this.#replaceWithStoredSession();\n    this.#loaded = true;\n  }\n\n  async #replaceWithStoredSession(): Promise<void> {\n    const stored = await this.#persistence.store.load(this.#persistence.key);\n    this.#storeVersion = stored?.version;\n    this.#history = new AgentModelHistory(decodeStoredSessionSnapshot(stored));\n  }\n\n  async #drainInputQueue(): Promise<void> {\n    if (this.#running) {\n      return;\n    }\n\n    this.#running = true;\n    try {\n      while (!this.#killed && this.#inputQueue.length > 0) {\n        const item = this.#inputQueue.shift();\n        if (item) {\n          await this.#processQueuedInput(item);\n        }\n      }\n    } finally {\n      this.#running = false;\n    }\n  }\n\n  async #processQueuedInput({ input, run }: QueuedInput): Promise<void> {\n    this.#activeAbort = new AbortController();\n    const historySnapshot = this.#history.modelSnapshot();\n\n    try {\n      await this.#hooks?.beforeTurn?.({\n        history: this.#history.modelSnapshot(),\n        input,\n        signal: this.#activeAbort.signal,\n      });\n      run.emit({ type: \"turn-start\" });\n      this.#history.appendUserInput(input);\n      await this.#commitHistory();\n\n      const result = await runAgentLoop({\n        emit: (event) => run.emit(event),\n        history: this.#history,\n        hooks: this.#hooks,\n        llm: this.#llm,\n        signal: this.#activeAbort.signal,\n      });\n\n      await this.#commitHistory();\n      await runAfterTurnHook(this.#hooks, {\n        history: this.#history.modelSnapshot(),\n        input,\n        result,\n        signal: this.#activeAbort.signal,\n      });\n      run.emit({ type: result === \"aborted\" ? \"turn-abort\" : \"turn-end\" });\n    } catch (error) {\n      if (error instanceof SessionCommitConflictError) {\n        run.emit({ type: \"turn-error\", message: error.message });\n        return;\n      }\n\n      this.#history.rollback(historySnapshot);\n      try {\n        await this.#commitHistory();\n      } catch (rollbackError) {\n        run.emit({\n          type: \"turn-error\",\n          message: `${errorMessage(error)}; history rollback persistence failed: ${errorMessage(\n            rollbackError\n          )}`,\n        });\n        return;\n      }\n      run.emit({ type: \"turn-error\", message: errorMessage(error) });\n    } finally {\n      run.close();\n      this.#activeAbort = undefined;\n    }\n  }\n\n  async #commitHistory(): Promise<void> {\n    const result = await this.#persistence.store.commit(\n      this.#persistence.key,\n      {\n        state: encodeSessionSnapshot(this.#history.modelSnapshot()),\n        version: this.#storeVersion,\n      },\n      { expectedVersion: this.#storeVersion ?? null }\n    );\n\n    if (!result.ok) {\n      await this.#replaceWithStoredSession();\n      throw new SessionCommitConflictError(this.#persistence.key);\n    }\n\n    this.#storeVersion = result.version;\n  }\n}\n\nasync function runAfterTurnHook(\n  hooks: AgentHooks | undefined,\n  context: Parameters<NonNullable<AgentHooks[\"afterTurn\"]>>[0]\n): Promise<void> {\n  const hook = hooks?.afterTurn;\n  if (!hook) {\n    return;\n  }\n\n  await Promise.allSettled([Promise.resolve().then(() => hook(context))]);\n}\n\nexport function normalizeAgentInput(input: AgentInput): UserInput {\n  if (typeof input === \"string\") {\n    return {\n      type: \"user-text\",\n      text: input,\n    };\n  }\n\n  if (isStringArrayInput(input)) {\n    return {\n      type: \"user-text\",\n      text: structuredClone(input) as readonly string[],\n    };\n  }\n\n  if (isArrayInput(input)) {\n    assertUserMessageContent(input);\n    return {\n      type: \"user-message\",\n      content: structuredClone(input) as readonly UserMessageContentPart[],\n    };\n  }\n\n  if (isUserMessage(input)) {\n    assertUserMessageContent(input.content);\n  }\n\n  return structuredClone(input);\n}\n\nfunction isStringArrayInput(input: AgentInput): input is readonly string[] {\n  return isArrayInput(input) && input.every((part) => typeof part === \"string\");\n}\n\nfunction isArrayInput(\n  input: AgentInput\n): input is readonly string[] | readonly UserMessageContentPart[] {\n  return Array.isArray(input);\n}\n\nfunction isUserMessage(input: UserInput): input is UserMessage {\n  return input.type === \"user-message\";\n}\n\nfunction assertUserMessageContent(\n  input: readonly unknown[]\n): asserts input is readonly UserMessageContentPart[] {\n  for (const part of input) {\n    if (!isUserMessageContentPart(part)) {\n      throw new TypeError(\n        'Agent input content parts must be { type: \"text\", text }, { type: \"image\", image }, or { type: \"file\", data, mediaType }.'\n      );\n    }\n  }\n}\n\nfunction isUserMessageContentPart(\n  part: unknown\n): part is UserMessageContentPart {\n  if (part === null || typeof part !== \"object\" || !(\"type\" in part)) {\n    return false;\n  }\n\n  if (part.type === \"text\") {\n    return \"text\" in part && typeof part.text === \"string\";\n  }\n\n  if (part.type === \"image\") {\n    return (\n      \"image\" in part &&\n      typeof part.image === \"string\" &&\n      (!(\"mediaType\" in part) || typeof part.mediaType === \"string\")\n    );\n  }\n\n  if (part.type === \"file\") {\n    return (\n      \"data\" in part &&\n      isUserMessageFileData(part.data) &&\n      \"mediaType\" in part &&\n      typeof part.mediaType === \"string\" &&\n      (!(\"filename\" in part) || typeof part.filename === \"string\")\n    );\n  }\n\n  return false;\n}\n\nfunction isUserMessageFileData(data: unknown): boolean {\n  if (typeof data === \"string\") {\n    return true;\n  }\n\n  if (data === null || typeof data !== \"object\" || !(\"type\" in data)) {\n    return false;\n  }\n\n  if (data.type === \"data\") {\n    return \"data\" in data && typeof data.data === \"string\";\n  }\n\n  if (data.type === \"reference\") {\n    return (\n      \"reference\" in data &&\n      data.reference !== null &&\n      typeof data.reference === \"object\" &&\n      Object.values(data.reference).every((value) => typeof value === \"string\")\n    );\n  }\n\n  if (data.type === \"text\") {\n    return \"text\" in data && typeof data.text === \"string\";\n  }\n\n  if (data.type === \"url\") {\n    return \"url\" in data && typeof data.url === \"string\";\n  }\n\n  return false;\n}\n\nfunction errorMessage(error: unknown): string {\n  if (error instanceof Error) {\n    return error.message;\n  }\n\n  return String(error);\n}\n\nfunction sessionKilledError(): Error {\n  return new Error(\"Session killed\");\n}\n\nclass SessionCommitConflictError extends Error {\n  constructor(key: string) {\n    super(`Session ${JSON.stringify(key)} commit conflict`);\n  }\n}\n"],"mappings":"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"}

package/dist/session/snapshot.js

@@ -0,0 +1,20 @@
+//#region src/session/snapshot.ts
+function encodeSessionSnapshot(history) {
+	return {
+		schemaVersion: 1,
+		history: structuredClone(history)
+	};
+}
+function decodeStoredSessionSnapshot(stored) {
+	if (!stored) return [];
+	const snapshot = stored.state;
+	if (isSessionSnapshotV1(snapshot)) return structuredClone(snapshot.history);
+	throw new Error("Unsupported stored session state");
+}
+function isSessionSnapshotV1(value) {
+	return value !== null && typeof value === "object" && "schemaVersion" in value && value.schemaVersion === 1 && "history" in value && Array.isArray(value.history);
+}
+//#endregion
+export { decodeStoredSessionSnapshot, encodeSessionSnapshot };
+
+//# sourceMappingURL=snapshot.js.map

package/dist/session/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","names":[],"sources":["../../src/session/snapshot.ts"],"sourcesContent":["import type { AgentMessage } from \"../llm\";\nimport type { StoredSession } from \"./store/types\";\n\nexport interface AgentSessionSnapshotV1 {\n  readonly history: AgentMessage[];\n  readonly schemaVersion: 1;\n}\n\nexport type AgentSessionSnapshot = AgentSessionSnapshotV1;\n\nexport function encodeSessionSnapshot(\n  history: AgentMessage[]\n): AgentSessionSnapshot {\n  return { schemaVersion: 1, history: structuredClone(history) };\n}\n\nexport function decodeStoredSessionSnapshot(\n  stored: StoredSession | null\n): AgentMessage[] {\n  if (!stored) {\n    return [];\n  }\n\n  const snapshot = stored.state;\n  if (isSessionSnapshotV1(snapshot)) {\n    return structuredClone(snapshot.history);\n  }\n\n  throw new Error(\"Unsupported stored session state\");\n}\n\nfunction isSessionSnapshotV1(value: unknown): value is AgentSessionSnapshotV1 {\n  return (\n    value !== null &&\n    typeof value === \"object\" &&\n    \"schemaVersion\" in value &&\n    value.schemaVersion === 1 &&\n    \"history\" in value &&\n    Array.isArray(value.history)\n  );\n}\n"],"mappings":";AAUA,SAAgB,sBACd,SACsB;CACtB,OAAO;EAAE,eAAe;EAAG,SAAS,gBAAgB,OAAO;CAAE;AAC/D;AAEA,SAAgB,4BACd,QACgB;CAChB,IAAI,CAAC,QACH,OAAO,CAAC;CAGV,MAAM,WAAW,OAAO;CACxB,IAAI,oBAAoB,QAAQ,GAC9B,OAAO,gBAAgB,SAAS,OAAO;CAGzC,MAAM,IAAI,MAAM,kCAAkC;AACpD;AAEA,SAAS,oBAAoB,OAAiD;CAC5E,OACE,UAAU,QACV,OAAO,UAAU,YACjB,mBAAmB,SACnB,MAAM,kBAAkB,KACxB,aAAa,SACb,MAAM,QAAQ,MAAM,OAAO;AAE/B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minpeter/pss-runtime",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "Generic agent runtime for sessions, model loops, and event streams.",
   "type": "module",
   "main": "./dist/index.js",