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

package/README.md

@@ -13,7 +13,7 @@ Minimal, platform-agnostic agent runtime with keyed sessions, synchronized
 import { Agent } from "@minpeter/pss-runtime";
 import { createYourLanguageModel } from "...";
 
-const agent = await Agent.create({
+const agent = new Agent({
   instructions: "Answer briefly.",
   model: createYourLanguageModel(),
 });
@@ -80,6 +80,63 @@ The public transcript protocol is `AgentEvent`: live runs emit runtime-defined
 events through `run.events()`. Provider/model message history is internal
 continuation state, not a public history API.
 
+## Subagents
+
+Compose specialist agents by constructing them first and passing them as an
+array. Top-level agents may omit metadata, but agents used as subagents need a
+stable `name` and `description` so the runtime can expose clear model-facing
+delegate tools.
+
+```ts
+const researcher = new Agent({
+  name: "researcher",
+  description: "Researches facts and returns concise evidence.",
+  model,
+  instructions: "Research facts and return concise evidence.",
+});
+
+const coordinator = new Agent({
+  model,
+  instructions: "Coordinate work and delegate when useful.",
+  subagents: [researcher],
+});
+```
+
+For each subagent, the parent model receives a generated
+`delegate_to_<name>` tool. The tool accepts `prompt`, optional `description`,
+optional `sessionKey` suffix, and `run_in_background`. A provided `sessionKey`
+is always scoped under the parent session and subagent name; the model cannot
+select an arbitrary child session key. Omitting `run_in_background` defaults to
+blocking behavior and returns compact child text, not the full child event
+stream.
+
+```ts
+delegate_to_researcher({
+  prompt: "Find the current release notes and summarize the evidence.",
+});
+```
+
+When the model sets `run_in_background: true`, the parent run can finish while
+the child keeps working. The launch result includes a `bg_...` `task_id`. A
+compact runtime reminder is queued for the parent when the child finishes, and
+the model can retrieve the result with `background_output`.
+
+```ts
+delegate_to_researcher({
+  prompt: "Compare the API designs.",
+  run_in_background: true,
+});
+
+background_output({ task_id: "bg_...", block: true });
+background_cancel({ task_id: "bg_..." });
+```
+
+The parent model context stays compact by default: completion reminders include
+the task id, subagent name, description, and retrieval instruction. Full child
+traces are not injected into the parent transcript by default. Background jobs
+run in task-scoped child sessions, and retrieved completed jobs are forgotten
+after `background_output` returns.
+
 ## Send and Steer
 
 Use `session.send(input)` for a new user turn. If a run is already active, the
@@ -135,28 +192,33 @@ Custom stores own version generation. `load(key)` returns the opaque `state` wit
 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.
+new version to the runtime. `delete(key)` removes the persisted session for that
+key.
 
 ```ts
 import type { SessionStore } from "@minpeter/pss-runtime";
 import { MemorySessionStore } from "@minpeter/pss-runtime/session-store/memory";
 
-const agent = await Agent.create({
+const agent = new Agent({
   model,
   sessions: {
+    namespace: "support-agent",
     store: new MemorySessionStore(), // default when omitted
   },
 });
 ```
 
-For durable sessions, use the exported file POC:
+For durable sessions, use the exported file POC. Set a stable `namespace` when
+subagents also use durable stores, so reconstructed agents map the same parent
+session and child `sessionKey` suffixes back to the same child transcripts:
 
 ```ts
 import { FileSessionStore } from "@minpeter/pss-runtime/session-store/file";
 
-const agent = await Agent.create({
+const agent = new Agent({
   model,
   sessions: {
+    namespace: "support-agent",
     store: new FileSessionStore(".pss/sessions"),
   },
 });

package/dist/agent-namespace.js

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

package/dist/agent-namespace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-namespace.js","names":[],"sources":["../src/agent-namespace.ts"],"sourcesContent":["export function randomAgentNamespace(): string {\n  return agentNamespace(crypto.randomUUID());\n}\n\nexport function agentNamespace(namespace: string): string {\n  return `agent:${namespacePart(namespace)}`;\n}\n\nexport function namespacePart(value: string): string {\n  return encodeURIComponent(value);\n}\n\nexport function parentSessionNamespace({\n  generation,\n  sessionKey,\n  sessionNamespace,\n}: {\n  readonly generation: number;\n  readonly sessionKey: string;\n  readonly sessionNamespace: string;\n}): string {\n  return `${sessionNamespace}:session:${namespacePart(\n    sessionKey\n  )}:generation:${generation}`;\n}\n"],"mappings":";AAAA,SAAgB,uBAA+B;CAC7C,OAAO,eAAe,OAAO,WAAW,CAAC;AAC3C;AAEA,SAAgB,eAAe,WAA2B;CACxD,OAAO,SAAS,cAAc,SAAS;AACzC;AAEA,SAAgB,cAAc,OAAuB;CACnD,OAAO,mBAAmB,KAAK;AACjC;AAEA,SAAgB,uBAAuB,EACrC,YACA,YACA,oBAKS;CACT,OAAO,GAAG,iBAAiB,WAAW,cACpC,UACF,EAAE,cAAc;AAClB"}

package/dist/agent-validation.js

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

package/dist/agent-validation.js.map

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

package/dist/agent.d.ts

@@ -7,27 +7,35 @@ import { LanguageModel, ToolSet } from "ai";
 
 //#region src/agent.d.ts
 interface AgentLanguageModelOptions {
+  description?: string;
   hooks?: AgentHooks;
   instructions?: string;
   llm?: never;
   model: LanguageModel;
+  name?: string;
   sessions?: AgentSessionOptions;
+  subagents?: readonly Agent[];
   toolChoice?: AgentToolChoice;
   tools?: ToolSet;
 }
 interface AgentLlmOptions {
+  description?: string;
   hooks?: AgentHooks;
   instructions?: never;
   llm: Llm;
   model?: never;
+  name?: string;
   sessions?: AgentSessionOptions;
+  subagents?: never;
   toolChoice?: never;
   tools?: never;
 }
 interface AgentSessionOptions {
+  namespace?: string;
   store?: SessionStore;
 }
 interface SessionHandle {
+  delete(): Promise<void>;
   interrupt(): void;
   kill(): void;
   send(input: AgentInput): Promise<AgentRun>;
@@ -36,8 +44,9 @@ interface SessionHandle {
 type AgentOptions = AgentLanguageModelOptions | AgentLlmOptions;
 declare class Agent {
   #private;
-  private constructor();
-  static create(options: AgentOptions): Promise<Agent>;
+  readonly description?: string;
+  readonly name?: string;
+  constructor(options: AgentOptions);
   send(input: AgentInput): Promise<AgentRun>;
   session(key: string): SessionHandle;
 }

package/dist/agent.js

@@ -1,25 +1,42 @@
+import { agentNamespace, parentSessionNamespace, randomAgentNamespace } from "./agent-namespace.js";
+import { assertSubagents } from "./agent-validation.js";
+import { ChildSessionCleanups } from "./child-session-cleanups.js";
 import { createLlm } from "./llm.js";
 import { AgentSession } from "./session/session.js";
 import { MemorySessionStore } from "./session/store/memory.js";
+import { createSubagentTools } from "./subagents.js";
 //#region src/agent.ts
 var Agent = class Agent {
+	#baseTools;
 	#hooks;
 	#llm;
+	#modelOptions;
+	#childSessionCleanups = new ChildSessionCleanups();
+	#sessionGenerations = /* @__PURE__ */ new Map();
 	#sessions = /* @__PURE__ */ new Map();
+	#sessionNamespace;
 	#store;
+	#subagents;
+	description;
+	name;
 	constructor(options) {
 		assertAgentOptions(options);
+		this.description = options.description;
+		this.name = options.name;
+		this.#sessionNamespace = stableAgentNamespace(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
-		});
-	}
-	static create(options) {
-		return Promise.resolve().then(() => new Agent(options));
+		assertSubagents(options, Agent, hasCustomLlm(options));
+		this.#subagents = hasCustomLlm(options) ? [] : options.subagents ?? [];
+		if (hasCustomLlm(options)) this.#llm = options.llm;
+		else {
+			this.#baseTools = options.tools;
+			this.#modelOptions = {
+				instructions: options.instructions,
+				model: options.model,
+				toolChoice: options.toolChoice
+			};
+		}
 	}
 	send(input) {
 		return this.session("default").send(input);
@@ -27,14 +44,32 @@ var Agent = class Agent {
 	session(key) {
 		const existing = this.#sessions.get(key);
 		if (existing) return existing;
-		const session = new AgentSession(this.#llm, {
+		let session;
+		const getSession = () => {
+			if (!session) throw new Error("Agent session is not initialized.");
+			return session;
+		};
+		const parentAgentNamespace = parentSessionNamespace({
+			generation: this.#sessionGenerations.get(key) ?? 0,
+			sessionKey: key,
+			sessionNamespace: this.#sessionNamespace
+		});
+		session = new AgentSession(this.#llm ?? createLlm(this.#createLlmOptionsForSession(key, parentAgentNamespace, (input, placement) => getSession().enqueueRuntimeInput(input, placement), (event) => getSession().emitObserverEvent(event))), {
 			key,
 			store: this.#store
 		}, this.#hooks);
 		const handle = {
+			delete: async () => {
+				await session.delete();
+				this.#sessions.delete(key);
+				this.#sessionGenerations.set(key, (this.#sessionGenerations.get(key) ?? 0) + 1);
+				await this.#deleteChildSessions(key);
+			},
 			interrupt: () => session.interrupt(),
 			kill: () => {
 				session.kill();
+				this.#sessionGenerations.set(key, (this.#sessionGenerations.get(key) ?? 0) + 1);
+				this.#deleteChildSessions(key).catch(() => void 0);
 				this.#sessions.delete(key);
 			},
 			send: (input) => session.send(input),
@@ -43,14 +78,44 @@ var Agent = class Agent {
 		this.#sessions.set(key, handle);
 		return handle;
 	}
+	#createLlmOptionsForSession(key, parentAgentNamespace, enqueueRuntimeInput, emitObserverEvent) {
+		const modelOptions = this.#modelOptions;
+		if (!modelOptions) throw new Error("Agent: missing model options.");
+		const tools = this.#subagents.length === 0 ? this.#baseTools : {
+			...this.#baseTools,
+			...createSubagentTools({
+				parentAgentNamespace,
+				parentSession: {
+					emitObserverEvent,
+					enqueueRuntimeInput
+				},
+				parentSessionKey: key,
+				registerChildSession: (sessionKey, cleanup) => this.#childSessionCleanups.register(sessionKey, cleanup),
+				subagents: this.#subagents
+			})
+		};
+		return {
+			instructions: modelOptions.instructions,
+			model: modelOptions.model,
+			toolChoice: modelOptions.toolChoice,
+			tools
+		};
+	}
+	async #deleteChildSessions(parentSessionKey) {
+		await this.#childSessionCleanups.delete(parentSessionKey);
+	}
 };
+function stableAgentNamespace(options) {
+	const namespace = options.sessions?.namespace ?? options.name;
+	return namespace ? agentNamespace(namespace) : randomAgentNamespace();
+}
 function assertAgentOptions(options) {
 	if (options === null || typeof options !== "object") throw new TypeError("Agent options are required. Provide either { model } or { llm }.");
 	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 (!(hasLlm || hasModel)) throw new TypeError("Agent.create: missing options.model.");
+	const hasModel = "model" in options && options.model != null;
+	if (hasLlm && hasModel) throw new TypeError("Agent: provide either options.llm or options.model.");
+	if ("llm" in options && options.llm !== void 0 && !hasLlm) throw new TypeError("Agent: invalid options.llm.");
+	if (!(hasLlm || hasModel)) throw new TypeError("Agent: missing options.model.");
 }
 function hasCustomLlm(options) {
 	return "llm" in options && typeof options.llm === "function";

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":["#baseTools","#hooks","#llm","#modelOptions","#childSessionCleanups","#sessionGenerations","#sessions","#sessionNamespace","#store","#subagents","#createLlmOptionsForSession","#deleteChildSessions"],"sources":["../src/agent.ts"],"sourcesContent":["import type { LanguageModel, ToolSet } from \"ai\";\nimport {\n  agentNamespace,\n  parentSessionNamespace,\n  randomAgentNamespace,\n} from \"./agent-namespace\";\nimport { assertSubagents } from \"./agent-validation\";\nimport { ChildSessionCleanups } from \"./child-session-cleanups\";\nimport type { AgentHooks } from \"./hooks\";\nimport { type AgentToolChoice, createLlm, type Llm } from \"./llm\";\nimport type { UserInput } from \"./session/events\";\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\";\nimport { createSubagentTools } from \"./subagents\";\n\ninterface AgentLanguageModelOptions {\n  description?: string;\n  hooks?: AgentHooks;\n  instructions?: string;\n  llm?: never;\n  model: LanguageModel;\n  name?: string;\n  sessions?: AgentSessionOptions;\n  subagents?: readonly Agent[];\n  toolChoice?: AgentToolChoice;\n  tools?: ToolSet;\n}\n\ninterface AgentLlmOptions {\n  description?: string;\n  hooks?: AgentHooks;\n  instructions?: never;\n  llm: Llm;\n  model?: never;\n  name?: string;\n  sessions?: AgentSessionOptions;\n  subagents?: never;\n  toolChoice?: never;\n  tools?: never;\n}\n\nexport interface AgentSessionOptions {\n  namespace?: string;\n  store?: SessionStore;\n}\n\nexport interface SessionHandle {\n  delete(): Promise<void>;\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;\ntype AgentModelOptions = Pick<\n  AgentLanguageModelOptions,\n  \"instructions\" | \"model\" | \"toolChoice\"\n>;\n\nexport class Agent {\n  readonly #baseTools?: ToolSet;\n  readonly #hooks?: AgentHooks;\n  readonly #llm?: Llm;\n  readonly #modelOptions?: AgentModelOptions;\n  readonly #childSessionCleanups = new ChildSessionCleanups();\n  readonly #sessionGenerations = new Map<string, number>();\n  readonly #sessions = new Map<string, SessionHandle>();\n  readonly #sessionNamespace: string;\n  readonly #store: SessionStore;\n  readonly #subagents: readonly Agent[];\n  readonly description?: string;\n  readonly name?: string;\n\n  constructor(options: AgentOptions) {\n    assertAgentOptions(options);\n\n    this.description = options.description;\n    this.name = options.name;\n    this.#sessionNamespace = stableAgentNamespace(options);\n    this.#store = options.sessions?.store ?? new MemorySessionStore();\n    this.#hooks = options.hooks;\n    assertSubagents(options, Agent, hasCustomLlm(options));\n    this.#subagents = hasCustomLlm(options) ? [] : (options.subagents ?? []);\n    if (hasCustomLlm(options)) {\n      this.#llm = options.llm;\n    } else {\n      this.#baseTools = options.tools;\n      this.#modelOptions = {\n        instructions: options.instructions,\n        model: options.model,\n        toolChoice: options.toolChoice,\n      };\n    }\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    let session: AgentSession | undefined;\n    const getSession = () => {\n      if (!session) {\n        throw new Error(\"Agent session is not initialized.\");\n      }\n      return session;\n    };\n    const parentAgentNamespace = parentSessionNamespace({\n      generation: this.#sessionGenerations.get(key) ?? 0,\n      sessionKey: key,\n      sessionNamespace: this.#sessionNamespace,\n    });\n    const llm =\n      this.#llm ??\n      createLlm(\n        this.#createLlmOptionsForSession(\n          key,\n          parentAgentNamespace,\n          (input: UserInput, placement?: \"turn-start\") =>\n            getSession().enqueueRuntimeInput(input, placement),\n          (event) => getSession().emitObserverEvent(event)\n        )\n      );\n    session = new AgentSession(llm, { key, store: this.#store }, this.#hooks);\n    const handle: SessionHandle = {\n      delete: async () => {\n        await session.delete();\n        this.#sessions.delete(key);\n        this.#sessionGenerations.set(\n          key,\n          (this.#sessionGenerations.get(key) ?? 0) + 1\n        );\n        await this.#deleteChildSessions(key);\n      },\n      interrupt: () => session.interrupt(),\n      kill: () => {\n        session.kill();\n        this.#sessionGenerations.set(\n          key,\n          (this.#sessionGenerations.get(key) ?? 0) + 1\n        );\n        this.#deleteChildSessions(key).catch(() => undefined);\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  #createLlmOptionsForSession(\n    key: string,\n    parentAgentNamespace: string,\n    enqueueRuntimeInput: AgentSession[\"enqueueRuntimeInput\"],\n    emitObserverEvent: AgentSession[\"emitObserverEvent\"]\n  ): Parameters<typeof createLlm>[0] {\n    const modelOptions = this.#modelOptions;\n    if (!modelOptions) {\n      throw new Error(\"Agent: missing model options.\");\n    }\n    const tools =\n      this.#subagents.length === 0\n        ? this.#baseTools\n        : {\n            ...this.#baseTools,\n            ...createSubagentTools({\n              parentAgentNamespace,\n              parentSession: { emitObserverEvent, enqueueRuntimeInput },\n              parentSessionKey: key,\n              registerChildSession: (sessionKey, cleanup) =>\n                this.#childSessionCleanups.register(sessionKey, cleanup),\n              subagents: this.#subagents,\n            }),\n          };\n\n    return {\n      instructions: modelOptions.instructions,\n      model: modelOptions.model,\n      toolChoice: modelOptions.toolChoice,\n      tools,\n    };\n  }\n\n  async #deleteChildSessions(parentSessionKey: string): Promise<void> {\n    await this.#childSessionCleanups.delete(parentSessionKey);\n  }\n}\n\nfunction stableAgentNamespace(options: AgentOptions): string {\n  const namespace = options.sessions?.namespace ?? options.name;\n  return namespace ? agentNamespace(namespace) : randomAgentNamespace();\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 = \"model\" in options && options.model != null;\n\n  if (hasLlm && hasModel) {\n    throw new TypeError(\"Agent: provide either options.llm or options.model.\");\n  }\n\n  if (\"llm\" in options && options.llm !== undefined && !hasLlm) {\n    throw new TypeError(\"Agent: invalid options.llm.\");\n  }\n\n  if (!(hasLlm || hasModel)) {\n    throw new TypeError(\"Agent: 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":"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"}

package/dist/child-session-cleanups.js

@@ -0,0 +1,61 @@
+//#region src/child-session-cleanups.ts
+var ChildSessionCleanups = class {
+	#byParentSession = /* @__PURE__ */ new Map();
+	async delete(parentSessionKey) {
+		const cleanups = this.#byParentSession.get(parentSessionKey);
+		if (!cleanups) return;
+		this.#byParentSession.delete(parentSessionKey);
+		const results = await Promise.all([...cleanups].map(runCleanup));
+		const failedCleanups = [];
+		let firstError;
+		for (const result of results) {
+			if (result.ok) continue;
+			firstError ??= result.error;
+			failedCleanups.push(result.cleanup);
+		}
+		if (failedCleanups.length === 0) return;
+		this.#restore(parentSessionKey, failedCleanups);
+		throw firstError instanceof Error ? firstError : new Error(String(firstError));
+	}
+	register(parentSessionKey, cleanup) {
+		const existing = this.#byParentSession.get(parentSessionKey);
+		if (existing) {
+			existing.add(cleanup);
+			return () => this.#unregister(parentSessionKey, existing, cleanup);
+		}
+		const cleanups = new Set([cleanup]);
+		this.#byParentSession.set(parentSessionKey, cleanups);
+		return () => this.#unregister(parentSessionKey, cleanups, cleanup);
+	}
+	#unregister(parentSessionKey, cleanups, cleanup) {
+		cleanups.delete(cleanup);
+		if (cleanups.size === 0 && this.#byParentSession.get(parentSessionKey) === cleanups) this.#byParentSession.delete(parentSessionKey);
+	}
+	#restore(parentSessionKey, failedCleanups) {
+		const current = this.#byParentSession.get(parentSessionKey);
+		if (current) {
+			for (const cleanup of failedCleanups) current.add(cleanup);
+			return;
+		}
+		this.#byParentSession.set(parentSessionKey, new Set(failedCleanups));
+	}
+};
+async function runCleanup(cleanup) {
+	try {
+		await cleanup();
+		return {
+			cleanup,
+			ok: true
+		};
+	} catch (error) {
+		return {
+			cleanup,
+			error,
+			ok: false
+		};
+	}
+}
+//#endregion
+export { ChildSessionCleanups };
+
+//# sourceMappingURL=child-session-cleanups.js.map

package/dist/child-session-cleanups.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"child-session-cleanups.js","names":["#byParentSession","#restore","#unregister"],"sources":["../src/child-session-cleanups.ts"],"sourcesContent":["type ChildSessionCleanup = () => Promise<void>;\n\ntype CleanupResult =\n  | { readonly cleanup: ChildSessionCleanup; readonly ok: true }\n  | {\n      readonly cleanup: ChildSessionCleanup;\n      readonly error: unknown;\n      readonly ok: false;\n    };\n\nexport class ChildSessionCleanups {\n  readonly #byParentSession = new Map<string, Set<ChildSessionCleanup>>();\n\n  async delete(parentSessionKey: string): Promise<void> {\n    const cleanups = this.#byParentSession.get(parentSessionKey);\n    if (!cleanups) {\n      return;\n    }\n\n    this.#byParentSession.delete(parentSessionKey);\n    const results = await Promise.all([...cleanups].map(runCleanup));\n    const failedCleanups: ChildSessionCleanup[] = [];\n    let firstError: unknown;\n    for (const result of results) {\n      if (result.ok) {\n        continue;\n      }\n\n      firstError ??= result.error;\n      failedCleanups.push(result.cleanup);\n    }\n\n    if (failedCleanups.length === 0) {\n      return;\n    }\n\n    this.#restore(parentSessionKey, failedCleanups);\n    throw firstError instanceof Error\n      ? firstError\n      : new Error(String(firstError));\n  }\n\n  register(parentSessionKey: string, cleanup: ChildSessionCleanup): () => void {\n    const existing = this.#byParentSession.get(parentSessionKey);\n    if (existing) {\n      existing.add(cleanup);\n      return () => this.#unregister(parentSessionKey, existing, cleanup);\n    }\n\n    const cleanups = new Set([cleanup]);\n    this.#byParentSession.set(parentSessionKey, cleanups);\n    return () => this.#unregister(parentSessionKey, cleanups, cleanup);\n  }\n\n  #unregister(\n    parentSessionKey: string,\n    cleanups: Set<ChildSessionCleanup>,\n    cleanup: ChildSessionCleanup\n  ): void {\n    cleanups.delete(cleanup);\n    if (\n      cleanups.size === 0 &&\n      this.#byParentSession.get(parentSessionKey) === cleanups\n    ) {\n      this.#byParentSession.delete(parentSessionKey);\n    }\n  }\n\n  #restore(\n    parentSessionKey: string,\n    failedCleanups: readonly ChildSessionCleanup[]\n  ): void {\n    const current = this.#byParentSession.get(parentSessionKey);\n    if (current) {\n      for (const cleanup of failedCleanups) {\n        current.add(cleanup);\n      }\n      return;\n    }\n\n    this.#byParentSession.set(parentSessionKey, new Set(failedCleanups));\n  }\n}\n\nasync function runCleanup(\n  cleanup: ChildSessionCleanup\n): Promise<CleanupResult> {\n  try {\n    await cleanup();\n    return { cleanup, ok: true };\n  } catch (error) {\n    return { cleanup, error, ok: false };\n  }\n}\n"],"mappings":";AAUA,IAAa,uBAAb,MAAkC;CAChC,mCAA4B,IAAI,IAAsC;CAEtE,MAAM,OAAO,kBAAyC;EACpD,MAAM,WAAW,KAAKA,iBAAiB,IAAI,gBAAgB;EAC3D,IAAI,CAAC,UACH;EAGF,KAAKA,iBAAiB,OAAO,gBAAgB;EAC7C,MAAM,UAAU,MAAM,QAAQ,IAAI,CAAC,GAAG,QAAQ,EAAE,IAAI,UAAU,CAAC;EAC/D,MAAM,iBAAwC,CAAC;EAC/C,IAAI;EACJ,KAAK,MAAM,UAAU,SAAS;GAC5B,IAAI,OAAO,IACT;GAGF,eAAe,OAAO;GACtB,eAAe,KAAK,OAAO,OAAO;EACpC;EAEA,IAAI,eAAe,WAAW,GAC5B;EAGF,KAAKC,SAAS,kBAAkB,cAAc;EAC9C,MAAM,sBAAsB,QACxB,aACA,IAAI,MAAM,OAAO,UAAU,CAAC;CAClC;CAEA,SAAS,kBAA0B,SAA0C;EAC3E,MAAM,WAAW,KAAKD,iBAAiB,IAAI,gBAAgB;EAC3D,IAAI,UAAU;GACZ,SAAS,IAAI,OAAO;GACpB,aAAa,KAAKE,YAAY,kBAAkB,UAAU,OAAO;EACnE;EAEA,MAAM,WAAW,IAAI,IAAI,CAAC,OAAO,CAAC;EAClC,KAAKF,iBAAiB,IAAI,kBAAkB,QAAQ;EACpD,aAAa,KAAKE,YAAY,kBAAkB,UAAU,OAAO;CACnE;CAEA,YACE,kBACA,UACA,SACM;EACN,SAAS,OAAO,OAAO;EACvB,IACE,SAAS,SAAS,KAClB,KAAKF,iBAAiB,IAAI,gBAAgB,MAAM,UAEhD,KAAKA,iBAAiB,OAAO,gBAAgB;CAEjD;CAEA,SACE,kBACA,gBACM;EACN,MAAM,UAAU,KAAKA,iBAAiB,IAAI,gBAAgB;EAC1D,IAAI,SAAS;GACX,KAAK,MAAM,WAAW,gBACpB,QAAQ,IAAI,OAAO;GAErB;EACF;EAEA,KAAKA,iBAAiB,IAAI,kBAAkB,IAAI,IAAI,cAAc,CAAC;CACrE;AACF;AAEA,eAAe,WACb,SACwB;CACxB,IAAI;EACF,MAAM,QAAQ;EACd,OAAO;GAAE;GAAS,IAAI;EAAK;CAC7B,SAAS,OAAO;EACd,OAAO;GAAE;GAAS;GAAO,IAAI;EAAM;CACrC;AACF"}

package/dist/session/events.d.ts

@@ -30,6 +30,7 @@ interface ToolResult {
   toolName: string;
   type: "tool-result";
 }
+type SubagentJobStatus = "aborted" | "cancelled" | "completed" | "error" | "pending" | "running";
 type AgentEvent = /** User input was accepted into the session queue. */UserText /** User multipart input was accepted into the session queue. */ | UserMessage /** Runtime/API-originated input inserted into the current turn, not human input. */ | RuntimeInput /** A queued user input started running as a turn. */ | {
   type: "turn-start";
 } /** The active turn was interrupted before normal completion. */ | {
@@ -41,7 +42,26 @@ type AgentEvent = /** User input was accepted into the session queue. */UserText
   type: "turn-end";
 } /** One model/tool-loop iteration started within the active turn. */ | {
   type: "step-start";
-} /** The model produced reasoning content. */ | AssistantReasoning /** The model produced visible assistant text. */ | AssistantText /** The model requested a tool call. */ | ToolCall /** A tool call returned a result. */ | ToolResult /** One model/tool-loop iteration finished within the active turn. */ | {
+} /** The model produced reasoning content. */ | AssistantReasoning /** The model produced visible assistant text. */ | AssistantText /** The model requested a tool call. */ | ToolCall /** A tool call returned a result. */ | ToolResult | {
+  description?: string;
+  run_in_background: boolean;
+  subagent: string;
+  task_id?: string;
+  type: "subagent-job-start";
+} | {
+  eventType?: AgentEvent["type"];
+  status: SubagentJobStatus;
+  subagent: string;
+  task_id: string;
+  type: "subagent-job-update";
+} | {
+  error?: string;
+  eventCount: number;
+  status: Exclude<SubagentJobStatus, "pending" | "running">;
+  subagent: string;
+  task_id?: string;
+  type: "subagent-job-end";
+} /** One model/tool-loop iteration finished within the active turn. */ | {
   type: "step-end";
 };
 type AgentEventListener = (event: AgentEvent) => void;

package/dist/session/history.d.ts

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

package/dist/session/input-normalization.js

@@ -0,0 +1,66 @@
+//#region src/session/input-normalization.ts
+function normalizeAgentInput(input) {
+	if (typeof input === "string") return {
+		type: "user-text",
+		text: input
+	};
+	if (isStringArrayInput(input)) return {
+		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);
+	}
+	if (isUserText(input)) return structuredClone(input);
+	throw new TypeError("Agent input must be text, text parts, content parts, user-text, or user-message.");
+}
+function isStringArrayInput(input) {
+	return Array.isArray(input) && hasDenseItems(input, isString);
+}
+function isArrayInput(input) {
+	return Array.isArray(input);
+}
+function isUserMessage(input) {
+	return input !== null && typeof input === "object" && !isArrayInput(input) && input.type === "user-message" && "content" in input && Array.isArray(input.content);
+}
+function isUserText(input) {
+	return input !== null && typeof input === "object" && !isArrayInput(input) && input.type === "user-text" && (typeof input.text === "string" || isStringArrayInput(input.text));
+}
+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 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 hasDenseItems(input, predicate) {
+	for (let index = 0; index < input.length; index += 1) if (!(index in input && predicate(input[index]))) return false;
+	return true;
+}
+function isString(value) {
+	return typeof value === "string";
+}
+//#endregion
+export { normalizeAgentInput };
+
+//# sourceMappingURL=input-normalization.js.map

package/dist/session/input-normalization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-normalization.js","names":[],"sources":["../../src/session/input-normalization.ts"],"sourcesContent":["import type {\n  AgentInput,\n  UserInput,\n  UserMessage,\n  UserMessageContentPart,\n  UserText,\n} from \"./input\";\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),\n    };\n  }\n\n  if (isArrayInput(input)) {\n    assertUserMessageContent(input);\n    return {\n      type: \"user-message\",\n      content: structuredClone(input),\n    };\n  }\n\n  if (isUserMessage(input)) {\n    assertUserMessageContent(input.content);\n    return structuredClone(input);\n  }\n\n  if (isUserText(input)) {\n    return structuredClone(input);\n  }\n\n  throw new TypeError(\n    \"Agent input must be text, text parts, content parts, user-text, or user-message.\"\n  );\n}\n\nfunction isStringArrayInput(input: unknown): input is readonly string[] {\n  return Array.isArray(input) && hasDenseItems(input, isString);\n}\n\nfunction isArrayInput(\n  input: AgentInput\n): input is readonly string[] | readonly UserMessageContentPart[] {\n  return Array.isArray(input);\n}\n\nfunction isUserMessage(input: AgentInput): input is UserMessage {\n  return (\n    input !== null &&\n    typeof input === \"object\" &&\n    !isArrayInput(input) &&\n    input.type === \"user-message\" &&\n    \"content\" in input &&\n    Array.isArray(input.content)\n  );\n}\n\nfunction isUserText(input: AgentInput): input is UserText {\n  return (\n    input !== null &&\n    typeof input === \"object\" &&\n    !isArrayInput(input) &&\n    input.type === \"user-text\" &&\n    (typeof input.text === \"string\" || isStringArrayInput(input.text))\n  );\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 hasDenseItems<T>(\n  input: readonly unknown[],\n  predicate: (value: unknown) => value is T\n): input is readonly T[] {\n  for (let index = 0; index < input.length; index += 1) {\n    if (!(index in input && predicate(input[index]))) {\n      return false;\n    }\n  }\n\n  return true;\n}\n\nfunction isString(value: unknown): value is string {\n  return typeof value === \"string\";\n}\n"],"mappings":";AAQA,SAAgB,oBAAoB,OAA8B;CAChE,IAAI,OAAO,UAAU,UACnB,OAAO;EACL,MAAM;EACN,MAAM;CACR;CAGF,IAAI,mBAAmB,KAAK,GAC1B,OAAO;EACL,MAAM;EACN,MAAM,gBAAgB,KAAK;CAC7B;CAGF,IAAI,aAAa,KAAK,GAAG;EACvB,yBAAyB,KAAK;EAC9B,OAAO;GACL,MAAM;GACN,SAAS,gBAAgB,KAAK;EAChC;CACF;CAEA,IAAI,cAAc,KAAK,GAAG;EACxB,yBAAyB,MAAM,OAAO;EACtC,OAAO,gBAAgB,KAAK;CAC9B;CAEA,IAAI,WAAW,KAAK,GAClB,OAAO,gBAAgB,KAAK;CAG9B,MAAM,IAAI,UACR,kFACF;AACF;AAEA,SAAS,mBAAmB,OAA4C;CACtE,OAAO,MAAM,QAAQ,KAAK,KAAK,cAAc,OAAO,QAAQ;AAC9D;AAEA,SAAS,aACP,OACgE;CAChE,OAAO,MAAM,QAAQ,KAAK;AAC5B;AAEA,SAAS,cAAc,OAAyC;CAC9D,OACE,UAAU,QACV,OAAO,UAAU,YACjB,CAAC,aAAa,KAAK,KACnB,MAAM,SAAS,kBACf,aAAa,SACb,MAAM,QAAQ,MAAM,OAAO;AAE/B;AAEA,SAAS,WAAW,OAAsC;CACxD,OACE,UAAU,QACV,OAAO,UAAU,YACjB,CAAC,aAAa,KAAK,KACnB,MAAM,SAAS,gBACd,OAAO,MAAM,SAAS,YAAY,mBAAmB,MAAM,IAAI;AAEpE;AAEA,SAAS,yBACP,OACoD;CACpD,KAAK,MAAM,QAAQ,OACjB,IAAI,CAAC,yBAAyB,IAAI,GAChC,MAAM,IAAI,UACR,iIACF;AAGN;AAEA,SAAS,yBACP,MACgC;CAChC,IAAI,SAAS,QAAQ,OAAO,SAAS,YAAY,EAAE,UAAU,OAC3D,OAAO;CAGT,IAAI,KAAK,SAAS,QAChB,OAAO,UAAU,QAAQ,OAAO,KAAK,SAAS;CAGhD,IAAI,KAAK,SAAS,SAChB,OACE,WAAW,QACX,OAAO,KAAK,UAAU,aACrB,EAAE,eAAe,SAAS,OAAO,KAAK,cAAc;CAIzD,IAAI,KAAK,SAAS,QAChB,OACE,UAAU,QACV,sBAAsB,KAAK,IAAI,KAC/B,eAAe,QACf,OAAO,KAAK,cAAc,aACzB,EAAE,cAAc,SAAS,OAAO,KAAK,aAAa;CAIvD,OAAO;AACT;AAEA,SAAS,sBAAsB,MAAwB;CACrD,IAAI,OAAO,SAAS,UAClB,OAAO;CAGT,IAAI,SAAS,QAAQ,OAAO,SAAS,YAAY,EAAE,UAAU,OAC3D,OAAO;CAGT,IAAI,KAAK,SAAS,QAChB,OAAO,UAAU,QAAQ,OAAO,KAAK,SAAS;CAGhD,IAAI,KAAK,SAAS,aAChB,OACE,eAAe,QACf,KAAK,cAAc,QACnB,OAAO,KAAK,cAAc,YAC1B,OAAO,OAAO,KAAK,SAAS,EAAE,OAAO,UAAU,OAAO,UAAU,QAAQ;CAI5E,IAAI,KAAK,SAAS,QAChB,OAAO,UAAU,QAAQ,OAAO,KAAK,SAAS;CAGhD,IAAI,KAAK,SAAS,OAChB,OAAO,SAAS,QAAQ,OAAO,KAAK,QAAQ;CAG9C,OAAO;AACT;AAEA,SAAS,cACP,OACA,WACuB;CACvB,KAAK,IAAI,QAAQ,GAAG,QAAQ,MAAM,QAAQ,SAAS,GACjD,IAAI,EAAE,SAAS,SAAS,UAAU,MAAM,MAAM,IAC5C,OAAO;CAIX,OAAO;AACT;AAEA,SAAS,SAAS,OAAiC;CACjD,OAAO,OAAO,UAAU;AAC1B"}

package/dist/session/runtime-input.d.ts

@@ -0,0 +1 @@
+export { };