@minpeter/pss-runtime 0.0.4 → 0.0.6

package/README.md

@@ -1,132 +1,120 @@
 # @minpeter/pss-runtime
 
-Reusable pss-next agent runtime for sessions, model loops, and event streams.
+Minimal, platform-agnostic agent runtime with sessions keyed through `run.stream()` and
+opaque persistence contracts.
+
+## Core DX
 
 ```ts
-import { Agent, type AgentModel } from "@minpeter/pss-runtime";
+import { Agent } from "@minpeter/pss-runtime";
+import { createYourLanguageModel } from "...";
 
-const model: AgentModel = createYourLanguageModel();
-const agent = new Agent({
+const agent = await Agent.create({
   instructions: "Answer briefly.",
-  model,
+  model: createYourLanguageModel(),
 });
-const session = agent.createSession();
-```
-
-The runtime does not read environment variables or create a default provider.
-Pass a caller-owned `LanguageModel` through `model`, or pass a custom `llm`.
-Product tools are intentionally not included; pass tools from a separate package
-when constructing an `Agent`.
 
-## Session history
+const run = await agent.send("Hello");
+for await (const event of run.stream()) {
+  console.log(event);
+}
+```
 
-Use `history` when the caller already owns the stored model-message history and
-needs a new `AgentSession` to continue from that state. This is the best fit for
-stateless request handlers, background jobs, and tests that persist history
-outside the runtime.
+Per-key conversations use `session(key)`:
 
 ```ts
-import { type AgentMessage } from "@minpeter/pss-runtime";
+const roomSession = agent.session("room:123:user:456");
+const run = await roomSession.send(["Context: user prefers short answers", "Hi"]);
+for await (const event of run.stream()) {
+  // stream events for this single turn
+}
+```
 
-const history: AgentMessage[] = [
-  { role: "user", content: "Hello!" },
-  { role: "assistant", content: "Hi! How can I help you today?" },
-];
+`agent.send(...)` is shorthand for `agent.session("default").send(...)`.
 
-const session = agent.createSession({ history });
+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.
 
-const currentHistory: AgentMessage[] = session.getHistory();
+```ts
+const run = await agent.send([
+  { type: "text", text: "Describe this UI screenshot." },
+  {
+    type: "image",
+    image: "data:image/png;base64,iVBORw0KGgo...",
+    mediaType: "image/png",
+  },
+]);
 ```
 
-`getHistory()` returns a cloned snapshot, so callers can persist or inspect it
-without mutating the session.
+File parts use the same JSON-serializable shape when the selected model supports
+file input:
 
-### Reactive storage synchronization
+```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",
+  },
+]);
+```
 
-Use `onHistoryChange` when the host should persist every history mutation as the
-turn runs. Calls are serialized, receive the mutation-time snapshot, and are
-awaited before `submit()` resolves, rejects, or advances to the next queued
-turn. If persistence fails, the turn rolls back in-memory history and surfaces a
-`turn-error`.
+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.
 
-This is the best fit for stateful serverless hosts such as Cloudflare Durable
-Objects, where a long-lived session mirrors history into Durable Object Storage,
-SQLite, or another caller-owned store.
+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.
 
-```ts
-import { Agent, type AgentMessage, type AgentSession } from "@minpeter/pss-runtime";
-
-export class AgentDurableObject {
-  private agent: Agent;
-  private session: AgentSession | null = null;
-  private storage: DurableObjectStorage;
-
-  constructor(state: DurableObjectState) {
-    this.storage = state.storage;
-    this.agent = new Agent({
-      instructions: "You are a helpful assistant.",
-      model: yourLanguageModel,
-    });
-  }
-
-  async fetch(request: Request) {
-    if (!this.session) {
-      const history =
-        (await this.storage.get<AgentMessage[]>("history")) ?? [];
-
-      this.session = this.agent.createSession({
-        history,
-        onHistoryChange: async (nextHistory) => {
-          await this.storage.put("history", nextHistory);
-        },
-      });
-    }
-
-    // Process the incoming request (e.g. submit user text and stream back events).
-    // ...
-  }
-}
-```
+## Session storage and portability
 
-### Safe event subscriptions
+The runtime owns full session state encoding and history compaction semantics.
+Adapters own persistence only through `SessionStore`:
 
-When subscribing to session events, unsubscribe in a `finally` block to prevent
-listener leaks in persistent environments or multi-turn execution loops.
+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
-const session = agent.createSession();
-
-// Subscribe to events and get the unsubscribe function
-const unsubscribe = session.subscribe((event) => {
-  switch (event.type) {
-    case "assistant-text":
-      process.stdout.write(event.text);
-      break;
-    case "tool-call":
-      console.log(`\nCalling tool: ${event.name}`);
-      break;
-  }
-});
+import type { SessionStore } from "@minpeter/pss-runtime";
+import { MemorySessionStore } from "@minpeter/pss-runtime/session-store/memory";
 
-try {
-  await session.submit({ type: "user-text", text: "What's the weather today?" });
-} finally {
-  // Always clean up to prevent memory/listener leaks!
-  unsubscribe();
-}
+const agent = await Agent.create({
+  model,
+  sessions: {
+    store: new MemorySessionStore(), // default when omitted
+  },
+});
 ```
 
-`submit()` also accepts `text` as an array of strings. The runtime keeps those
-strings together as one user turn and forwards them to the model as AI SDK text
-content parts, which is useful when the host needs to prepend per-turn context
-without flattening it into the user's visible message.
+For durable sessions, use the exported file POC:
 
 ```ts
-await session.submit({
-  type: "user-text",
-  text: [
-    "Context: user timezone is Asia/Seoul.",
-    "Please remind me tomorrow morning.",
-  ],
+import { FileSessionStore } from "@minpeter/pss-runtime/session-store/file";
+
+const agent = await Agent.create({
+  model,
+  sessions: {
+    store: new FileSessionStore(".pss/sessions"),
+  },
 });
 ```
+
+## Future adapter boundary: Cloudflare multi-user DX
+
+Cloudflare Durable Objects are a future adapter target, not a runtime dependency.
+The same core API supports room/user/session routing through stable session keys.
+
+Recommended key patterns:
+
+- Shared room conversation: `room:<roomId>`
+- Per-user memory inside room: `room:<roomId>:user:<userId>`
+- Ticketed workspace flows: `tenant:<tenantId>:ticket:<ticketId>`
+
+In a Durable Object, map the `SessionStore` contract to `ctx.storage` so DO storage is
+durable across hibernation/restores, while in-memory state remains request-local.
+Do not store canonical agent session state in memory attachments.

package/dist/agent-loop.d.ts

@@ -1,17 +1,25 @@
-import type { ModelMessage } from "ai";
-import type { Llm } from "./llm";
-import type { AgentEventListener } from "./session/events";
+import { Llm } from "./llm.js";
+import { AgentEventListener } from "./session/events.js";
+import { ModelMessage } from "ai";
+
+//#region src/agent-loop.d.ts
 interface ModelHistory {
-    appendModelMessage(message: ModelMessage): void;
-    modelSnapshot(): ModelMessage[];
+  appendModelMessage(message: ModelMessage): void;
+  modelSnapshot(): ModelMessage[];
 }
 interface RunAgentLoopOptions {
-    emit: AgentEventListener;
-    history: ModelHistory;
-    llm: Llm;
-    signal?: AbortSignal;
+  emit: AgentEventListener;
+  history: ModelHistory;
+  llm: Llm;
+  signal?: AbortSignal;
 }
-export type AgentLoopResult = "completed" | "aborted";
-export declare function runAgentLoop({ emit, history, llm, signal, }: RunAgentLoopOptions): Promise<AgentLoopResult>;
-export {};
+type AgentLoopResult = "completed" | "aborted";
+declare function runAgentLoop({
+  emit,
+  history,
+  llm,
+  signal
+}: RunAgentLoopOptions): Promise<AgentLoopResult>;
+//#endregion
+export { AgentLoopResult, runAgentLoop };
 //# sourceMappingURL=agent-loop.d.ts.map

package/dist/agent-loop.js

@@ -1,53 +1,50 @@
 import { modelMessageToAgentEvents } from "./session/mapping.js";
-export async function runAgentLoop({ emit, history, llm, signal = new AbortController().signal, }) {
-    while (true) {
-        if (signal.aborted) {
-            return "aborted";
-        }
-        emit({ type: "step-start" });
-        const output = await readLlmOutput({ history, llm, signal });
-        if (output === "aborted") {
-            return "aborted";
-        }
-        const result = appendStepOutput({ emit, history, output, signal });
-        if (result === "aborted") {
-            return "aborted";
-        }
-        emit({ type: "step-end" });
-        if (result === "completed") {
-            return "completed";
-        }
-    }
+//#region src/agent-loop.ts
+async function runAgentLoop({ emit, history, llm, signal = new AbortController().signal }) {
+	while (true) {
+		if (signal.aborted) return "aborted";
+		emit({ type: "step-start" });
+		const output = await readLlmOutput({
+			history,
+			llm,
+			signal
+		});
+		if (output === "aborted") return "aborted";
+		const result = appendStepOutput({
+			emit,
+			history,
+			output,
+			signal
+		});
+		if (result === "aborted") return "aborted";
+		emit({ type: "step-end" });
+		if (result === "completed") return "completed";
+	}
 }
-async function readLlmOutput({ history, llm, signal, }) {
-    try {
-        return await llm({ history: history.modelSnapshot(), signal });
-    }
-    catch (error) {
-        if (signal.aborted) {
-            return "aborted";
-        }
-        throw error;
-    }
+async function readLlmOutput({ history, llm, signal }) {
+	try {
+		return await llm({
+			history: history.modelSnapshot(),
+			signal
+		});
+	} catch (error) {
+		if (signal.aborted) return "aborted";
+		throw error;
+	}
 }
-function appendStepOutput({ emit, history, output, signal, }) {
-    if (signal.aborted) {
-        return "aborted";
-    }
-    let shouldContinue = false;
-    for (const message of output) {
-        if (signal.aborted) {
-            return "aborted";
-        }
-        history.appendModelMessage(message);
-        const events = modelMessageToAgentEvents(message);
-        for (const event of events) {
-            emit(event);
-        }
-        if (events.some((event) => event.type === "tool-call")) {
-            shouldContinue = true;
-        }
-    }
-    return shouldContinue ? "continue" : "completed";
+function appendStepOutput({ emit, history, output, signal }) {
+	if (signal.aborted) return "aborted";
+	let shouldContinue = false;
+	for (const message of output) {
+		if (signal.aborted) return "aborted";
+		history.appendModelMessage(message);
+		const events = modelMessageToAgentEvents(message);
+		for (const event of events) emit(event);
+		if (events.some((event) => event.type === "tool-call")) shouldContinue = true;
+	}
+	return shouldContinue ? "continue" : "completed";
 }
+//#endregion
+export { runAgentLoop };
+
 //# sourceMappingURL=agent-loop.js.map

package/dist/agent-loop.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-loop.js","sourceRoot":"","sources":["../src/agent-loop.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AAiB9D,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,EACjC,IAAI,EACJ,OAAO,EACP,GAAG,EACH,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC,MAAM,GACjB;IACpB,OAAO,IAAI,EAAE,CAAC;QACZ,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,IAAI,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC;QAC7B,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC;QAE7D,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,MAAM,GAAG,gBAAgB,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QAEnE,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;QAE3B,IAAI,MAAM,KAAK,WAAW,EAAE,CAAC;YAC3B,OAAO,WAAW,CAAC;QACrB,CAAC;IACH,CAAC;AACH,CAAC;AAED,KAAK,UAAU,aAAa,CAAC,EAC3B,OAAO,EACP,GAAG,EACH,MAAM,GAGP;IACC,IAAI,CAAC;QACH,OAAO,MAAM,GAAG,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,aAAa,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IACjE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,gBAAgB,CAAC,EACxB,IAAI,EACJ,OAAO,EACP,MAAM,EACN,MAAM,GAIP;IACC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,cAAc,GAAG,KAAK,CAAC;IAE3B,KAAK,MAAM,OAAO,IAAI,MAAM,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,OAAO,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;QACpC,MAAM,MAAM,GAAG,yBAAyB,CAAC,OAAO,CAAC,CAAC;QAElD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,IAAI,CAAC,KAAK,CAAC,CAAC;QACd,CAAC;QAED,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,WAAW,CAAC,EAAE,CAAC;YACvD,cAAc,GAAG,IAAI,CAAC;QACxB,CAAC;IACH,CAAC;IAED,OAAO,cAAc,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC;AACnD,CAAC"}
+{"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"}

package/dist/agent.d.ts

@@ -1,23 +1,40 @@
-import type { LanguageModel } from "ai";
-import { type AgentTools, type Llm } from "./llm";
-import { AgentSession, type SessionOptions } from "./session/session";
+import { 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 { LanguageModel } from "ai";
+
+//#region src/agent.d.ts
 interface AgentModelOptions {
-    instructions?: string;
-    llm?: never;
-    model: LanguageModel;
-    tools?: AgentTools;
+  instructions?: string;
+  llm?: never;
+  model: LanguageModel;
+  sessions?: AgentSessionOptions;
+  tools?: AgentTools;
 }
 interface AgentLlmOptions {
-    instructions?: never;
-    llm: Llm;
-    model?: never;
-    tools?: never;
+  instructions?: never;
+  llm: Llm;
+  model?: never;
+  sessions?: AgentSessionOptions;
+  tools?: never;
 }
-export type AgentOptions = AgentModelOptions | AgentLlmOptions;
-export declare class Agent {
-    #private;
-    constructor(options: AgentOptions);
-    createSession(options?: SessionOptions): AgentSession;
+interface AgentSessionOptions {
+  store?: SessionStore;
 }
-export {};
+interface SessionHandle {
+  interrupt(): void;
+  kill(): void;
+  send(input: AgentInput): Promise<AgentRun>;
+}
+type AgentOptions = AgentModelOptions | AgentLlmOptions;
+declare class Agent {
+  #private;
+  private constructor();
+  static create(options: AgentOptions): Promise<Agent>;
+  send(input: AgentInput): Promise<AgentRun>;
+  session(key: string): SessionHandle;
+}
+//#endregion
+export { Agent, AgentOptions, AgentSessionOptions, SessionHandle };
 //# sourceMappingURL=agent.d.ts.map

package/dist/agent.js

@@ -1,38 +1,57 @@
 import { createLlm } from "./llm.js";
 import { AgentSession } from "./session/session.js";
-export class Agent {
-    #llm;
-    constructor(options) {
-        assertAgentOptions(options);
-        this.#llm = hasCustomLlm(options)
-            ? options.llm
-            : createLlm({
-                instructions: options.instructions,
-                model: options.model,
-                tools: options.tools,
-            });
-    }
-    createSession(options) {
-        return new AgentSession(this.#llm, options);
-    }
-}
+import { MemorySessionStore } from "./session/store/memory.js";
+//#region src/agent.ts
+var Agent = class Agent {
+	#llm;
+	#sessions = /* @__PURE__ */ new Map();
+	#store;
+	constructor(options) {
+		assertAgentOptions(options);
+		this.#store = options.sessions?.store ?? new MemorySessionStore();
+		this.#llm = hasCustomLlm(options) ? options.llm : createLlm({
+			instructions: options.instructions,
+			model: options.model,
+			tools: options.tools
+		});
+	}
+	static create(options) {
+		return Promise.resolve().then(() => new Agent(options));
+	}
+	send(input) {
+		return this.session("default").send(input);
+	}
+	session(key) {
+		const existing = this.#sessions.get(key);
+		if (existing) return existing;
+		const session = new AgentSession(this.#llm, {
+			key,
+			store: this.#store
+		});
+		const handle = {
+			interrupt: () => session.interrupt(),
+			kill: () => {
+				session.kill();
+				this.#sessions.delete(key);
+			},
+			send: (input) => session.send(input)
+		};
+		this.#sessions.set(key, handle);
+		return handle;
+	}
+};
 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 !== undefined && options.model !== null;
-    if (hasLlm && hasModel) {
-        throw new TypeError("Agent constructor: provide either options.llm or options.model, not both.");
-    }
-    if ("llm" in options && options.llm !== undefined && !hasLlm) {
-        throw new TypeError("Agent constructor: invalid options.llm.");
-    }
-    if (!(hasLlm || hasModel)) {
-        throw new TypeError("Agent constructor: missing options.model.");
-    }
+	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.");
 }
 function hasCustomLlm(options) {
-    return "llm" in options && typeof options.llm === "function";
+	return "llm" in options && typeof options.llm === "function";
 }
+//#endregion
+export { Agent };
+
 //# sourceMappingURL=agent.js.map

package/dist/agent.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AACA,OAAO,EAAmB,SAAS,EAAY,MAAM,OAAO,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAuB,MAAM,mBAAmB,CAAC;AAkBtE,MAAM,OAAO,KAAK;IACP,IAAI,CAAM;IAEnB,YAAY,OAAqB;QAC/B,kBAAkB,CAAC,OAAO,CAAC,CAAC;QAE5B,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC,OAAO,CAAC;YAC/B,CAAC,CAAC,OAAO,CAAC,GAAG;YACb,CAAC,CAAC,SAAS,CAAC;gBACR,YAAY,EAAE,OAAO,CAAC,YAAY;gBAClC,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,KAAK,EAAE,OAAO,CAAC,KAAK;aACrB,CAAC,CAAC;IACT,CAAC;IAED,aAAa,CAAC,OAAwB;QACpC,OAAO,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC9C,CAAC;CACF;AAED,SAAS,kBAAkB,CAAC,OAAgB;IAC1C,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QACpD,MAAM,IAAI,SAAS,CACjB,kEAAkE,CACnE,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACrC,MAAM,QAAQ,GACZ,OAAO,IAAI,OAAO,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,IAAI,OAAO,CAAC,KAAK,KAAK,IAAI,CAAC;IAE9E,IAAI,MAAM,IAAI,QAAQ,EAAE,CAAC;QACvB,MAAM,IAAI,SAAS,CACjB,2EAA2E,CAC5E,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,IAAI,OAAO,IAAI,OAAO,CAAC,GAAG,KAAK,SAAS,IAAI,CAAC,MAAM,EAAE,CAAC;QAC7D,MAAM,IAAI,SAAS,CAAC,yCAAyC,CAAC,CAAC;IACjE,CAAC;IAED,IAAI,CAAC,CAAC,MAAM,IAAI,QAAQ,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,SAAS,CAAC,2CAA2C,CAAC,CAAC;IACnE,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CAAC,OAAe;IACnC,OAAO,KAAK,IAAI,OAAO,IAAI,OAAO,OAAO,CAAC,GAAG,KAAK,UAAU,CAAC;AAC/D,CAAC"}
+{"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"}

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-export { Agent, type AgentOptions } from "./agent";
-export { type AgentLoopResult, runAgentLoop } from "./agent-loop";
-export type { AgentMessage, AgentModel, AgentTool, AgentToolExecute, AgentToolExecutionOptions, AgentTools, LlmOutputPart, RuntimeCreateLlmOptions, RuntimeLlm, RuntimeLlmContext, RuntimeLlmOutput, } from "./llm";
-export { createLlm } from "./llm";
-export type { AgentEvent, AgentEventListener, AssistantReasoning, AssistantText, ToolCall, ToolResult, UserText, UserTextContent, } from "./session/events";
-export { AgentSession, type SessionInput, type SessionOptions, } from "./session/session";
-//# sourceMappingURL=index.d.ts.map
+import { AgentModel, AgentTool, 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, SessionInput, UserInput } from "./session/session.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 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 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/index.js

@@ -1,5 +1,4 @@
-export { Agent } from "./agent.js";
-export { runAgentLoop } from "./agent-loop.js";
-export { createLlm } from "./llm.js";
-export { AgentSession, } from "./session/session.js";
-//# sourceMappingURL=index.js.map
+import { createLlm } from "./llm.js";
+import { runAgentLoop } from "./agent-loop.js";
+import { Agent } from "./agent.js";
+export { Agent, createLlm, runAgentLoop };

package/dist/llm.d.ts

@@ -1,26 +1,32 @@
-import type { LanguageModel, ModelMessage, Tool, ToolExecutionOptions, ToolSet } from "ai";
-import { generateText } from "ai";
-export type AgentToolExecutionOptions = ToolExecutionOptions<unknown>;
-export type AgentToolExecute = NonNullable<Tool["execute"]>;
-export type AgentTool = Tool;
-export type AgentTools = ToolSet;
-export type AgentModel = LanguageModel;
-export type AgentMessage = ModelMessage;
-export type LlmOutput = Awaited<ReturnType<typeof generateText>>["responseMessages"];
-export type LlmOutputPart = LlmOutput[number];
-export interface LlmContext {
-    history: readonly ModelMessage[];
-    signal: AbortSignal;
+import { LanguageModel, ModelMessage, Tool, ToolExecutionOptions, ToolSet, generateText } from "ai";
+
+//#region src/llm.d.ts
+type AgentToolExecutionOptions = ToolExecutionOptions<unknown>;
+type AgentToolExecute = NonNullable<Tool["execute"]>;
+type AgentTool = Tool;
+type AgentTools = ToolSet;
+type AgentModel = LanguageModel;
+type LlmOutput = Awaited<ReturnType<typeof generateText>>["responseMessages"];
+type LlmOutputPart = LlmOutput[number];
+interface LlmContext {
+  history: readonly ModelMessage[];
+  signal: AbortSignal;
 }
-export type Llm = (context: LlmContext) => Promise<LlmOutput>;
-export interface CreateLlmOptions {
-    instructions?: string;
-    model: LanguageModel;
-    tools?: AgentTools;
+type Llm = (context: LlmContext) => Promise<LlmOutput>;
+interface CreateLlmOptions {
+  instructions?: string;
+  model: LanguageModel;
+  tools?: AgentTools;
 }
-export type RuntimeCreateLlmOptions = CreateLlmOptions;
-export type RuntimeLlm = Llm;
-export type RuntimeLlmContext = LlmContext;
-export type RuntimeLlmOutput = LlmOutput;
-export declare function createLlm({ model, instructions, tools, }: CreateLlmOptions): Llm;
+type RuntimeCreateLlmOptions = CreateLlmOptions;
+type RuntimeLlm = Llm;
+type RuntimeLlmContext = LlmContext;
+type RuntimeLlmOutput = LlmOutput;
+declare function createLlm({
+  model,
+  instructions,
+  tools
+}: CreateLlmOptions): Llm;
+//#endregion
+export { AgentModel, AgentTool, AgentToolExecute, AgentToolExecutionOptions, AgentTools, Llm, LlmOutputPart, RuntimeCreateLlmOptions, RuntimeLlm, RuntimeLlmContext, RuntimeLlmOutput, createLlm };
 //# sourceMappingURL=llm.d.ts.map