@better-agent/core 0.1.0-canary.0

package/dist/app/create-app.mjs

@@ -0,0 +1,132 @@
+import { validateAgentDefinition } from "../agent/validation.mjs";
+import { createPluginRuntime } from "../plugins/runtime.mjs";
+import { createRuntime } from "../run/runtime.mjs";
+import { createServer } from "../server/create-server.mjs";
+import { validateConfig } from "./config.mjs";
+import { buildRegistryFromConfig } from "./registry.mjs";
+import { BetterAgentError } from "@better-agent/shared/errors";
+
+//#region src/app/create-app.ts
+/**
+* Creates a Better Agent app.
+*
+* Register agents, shared tools, plugins, and optional advanced settings.
+*
+* @param config App configuration.
+* @returns An app with `run`, `stream`, and `handler`.
+*
+* @example
+* ```ts
+* const app = betterAgent({
+*   agents: [supportAgent],
+*   secret: "dev-secret",
+* });
+*
+* const result = await app.run("support", {
+*   input: "Hello!",
+* });
+* ```
+*/
+function betterAgent(config) {
+	const normalizedConfig = validateConfig(config);
+	const advanced = normalizedConfig.advanced;
+	for (const agent of normalizedConfig.agents) validateAgentDefinition(agent);
+	const registry = buildRegistryFromConfig({
+		agents: normalizedConfig.agents,
+		tools: normalizedConfig.tools,
+		plugins: normalizedConfig.plugins
+	});
+	const pluginRuntime = normalizedConfig.plugins ? createPluginRuntime(normalizedConfig.plugins) : null;
+	let cachedRuntime = null;
+	let cachedServerRuntime = null;
+	let cachedServer = null;
+	const getRuntime = () => {
+		if (!cachedRuntime) cachedRuntime = createRuntime({
+			agents: normalizedConfig.agents,
+			pluginRuntime,
+			stream: normalizedConfig.persistence?.stream,
+			conversations: normalizedConfig.persistence?.conversations,
+			runtimeState: normalizedConfig.persistence?.runtimeState,
+			advanced
+		});
+		return cachedRuntime;
+	};
+	const getServerRuntime = () => {
+		if (!cachedServerRuntime) cachedServerRuntime = createRuntime({
+			agents: normalizedConfig.agents,
+			pluginRuntime,
+			stream: normalizedConfig.persistence?.stream,
+			conversations: normalizedConfig.persistence?.conversations,
+			runtimeState: normalizedConfig.persistence?.runtimeState,
+			streamLifecycle: advanced?.onRequestDisconnect === "continue" ? "detached" : void 0,
+			advanced
+		});
+		return cachedServerRuntime;
+	};
+	const normalizeBasePath = (baseURL) => {
+		try {
+			return new URL(baseURL).pathname;
+		} catch {
+			return new URL(baseURL, "http://better-agent.local").pathname;
+		}
+	};
+	const getServer = () => {
+		if (!cachedServer) cachedServer = createServer({
+			runtime: getServerRuntime(),
+			pluginRuntime,
+			secret: normalizedConfig.secret,
+			basePath: normalizedConfig.baseURL !== void 0 ? normalizeBasePath(normalizedConfig.baseURL) : void 0,
+			advanced
+		});
+		return cachedServer;
+	};
+	const getRegisteredAgent = (agentName, traceAt) => {
+		const agent = normalizedConfig.agents.find((candidate) => candidate.name === agentName);
+		if (!agent) throw BetterAgentError.fromCode("NOT_FOUND", `Agent '${agentName}' not found in app registry.`, {
+			context: {
+				agentName,
+				availableAgents: Array.from(registry.agents.keys())
+			},
+			trace: [{ at: traceAt }]
+		});
+		return agent;
+	};
+	return {
+		config: normalizedConfig,
+		run: (agentName, input) => {
+			getRegisteredAgent(agentName, "core.app.betterAgent.run");
+			return getRuntime().run(agentName, input);
+		},
+		stream: (agentName, input) => {
+			getRegisteredAgent(agentName, "core.app.betterAgent.stream");
+			return getRuntime().stream(agentName, input);
+		},
+		resumeStream: async (params) => {
+			return getRuntime().resumeStream(params);
+		},
+		resumeConversation: async (agentName, params) => {
+			getRegisteredAgent(agentName, "core.app.betterAgent.resumeConversation");
+			return getRuntime().resumeConversation(agentName, params);
+		},
+		abortRun: async (runId) => {
+			return getRuntime().abortRun(runId);
+		},
+		loadConversation: async (agentName, conversationId) => {
+			getRegisteredAgent(agentName, "core.app.betterAgent.loadConversation");
+			return getRuntime().loadConversation(agentName, conversationId);
+		},
+		submitToolResult: async (params) => {
+			return getRuntime().submitToolResult(params);
+		},
+		submitToolApproval: async (params) => {
+			return getRuntime().submitToolApproval(params);
+		},
+		handler: (request) => {
+			return getServer().handle(request);
+		}
+	};
+}
+
+//#endregion
+export { betterAgent };
+//# sourceMappingURL=create-app.mjs.map

package/dist/app/create-app.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-app.mjs","names":[],"sources":["../../src/app/create-app.ts"],"sourcesContent":["import { BetterAgentError } from \"@better-agent/shared/errors\";\nimport type { AnyAgentDefinition } from \"../agent\";\nimport { validateAgentDefinition } from \"../agent/validation\";\nimport type { Plugin } from \"../plugins\";\nimport { createPluginRuntime } from \"../plugins\";\nimport { type BetterAgentRuntime, createRuntime } from \"../run\";\nimport { createServer } from \"../server\";\nimport type { AgentToolDefinition } from \"../tools\";\nimport { validateConfig } from \"./config\";\nimport { buildRegistryFromConfig } from \"./registry\";\nimport type { AgentByName, BetterAgentApp, BetterAgentConfig, BetterAgentHandler } from \"./types\";\n\n/**\n * Creates a Better Agent app.\n *\n * Register agents, shared tools, plugins, and optional advanced settings.\n *\n * @param config App configuration.\n * @returns An app with `run`, `stream`, and `handler`.\n *\n * @example\n * ```ts\n * const app = betterAgent({\n *   agents: [supportAgent],\n *   secret: \"dev-secret\",\n * });\n *\n * const result = await app.run(\"support\", {\n *   input: \"Hello!\",\n * });\n * ```\n */\nexport function betterAgent<\n    const TAgents extends readonly AnyAgentDefinition[],\n    const TPlugins extends readonly Plugin[] = readonly Plugin[],\n    const TTools extends readonly AgentToolDefinition[] = readonly AgentToolDefinition[],\n>(\n    config: BetterAgentConfig<TAgents, TPlugins, TTools>,\n): BetterAgentApp<TAgents, TPlugins> & {\n    handler: BetterAgentHandler;\n    readonly __appTypes?: {\n        readonly agents: TAgents;\n        readonly tools: TTools;\n    };\n} {\n    // Validate once up front so runtime and server setup can assume a stable config shape.\n    const normalizedConfig = validateConfig(config);\n    const advanced = normalizedConfig.advanced;\n    for (const agent of normalizedConfig.agents) {\n        validateAgentDefinition(agent);\n    }\n\n    // Build a registry used for duplicate checks and agent lookup errors.\n    const registry = buildRegistryFromConfig({\n        agents: normalizedConfig.agents,\n        tools: normalizedConfig.tools,\n        plugins: normalizedConfig.plugins,\n    });\n\n    // Plugin runtime is shared by both the direct runtime and the HTTP server runtime.\n    const pluginRuntime = normalizedConfig.plugins\n        ? createPluginRuntime(normalizedConfig.plugins)\n        : null;\n\n    let cachedRuntime: BetterAgentRuntime<TAgents> | null = null;\n    let cachedServerRuntime: BetterAgentRuntime<TAgents> | null = null;\n    let cachedServer: ReturnType<typeof createServer> | null = null;\n\n    const getRuntime = () => {\n        if (!cachedRuntime) {\n            const runtimeOptions = {\n                agents: normalizedConfig.agents,\n                pluginRuntime,\n                stream: normalizedConfig.persistence?.stream,\n                conversations: normalizedConfig.persistence?.conversations,\n                runtimeState: normalizedConfig.persistence?.runtimeState,\n                advanced,\n            };\n\n            cachedRuntime = createRuntime(runtimeOptions);\n        }\n        return cachedRuntime;\n    };\n\n    const getServerRuntime = () => {\n        if (!cachedServerRuntime) {\n            const runtimeOptions = {\n                agents: normalizedConfig.agents,\n                pluginRuntime,\n                stream: normalizedConfig.persistence?.stream,\n                conversations: normalizedConfig.persistence?.conversations,\n                runtimeState: normalizedConfig.persistence?.runtimeState,\n                streamLifecycle:\n                    advanced?.onRequestDisconnect === \"continue\"\n                        ? (\"detached\" as const)\n                        : undefined,\n                advanced,\n            };\n\n            cachedServerRuntime = createRuntime(runtimeOptions);\n        }\n        return cachedServerRuntime;\n    };\n\n    const normalizeBasePath = (baseURL: string): string => {\n        try {\n            return new URL(baseURL).pathname;\n        } catch {\n            return new URL(baseURL, \"http://better-agent.local\").pathname;\n        }\n    };\n\n    const getServer = () => {\n        if (!cachedServer) {\n            const runtime = getServerRuntime();\n            const serverOptions: Parameters<typeof createServer>[0] = {\n                runtime,\n                pluginRuntime,\n                secret: normalizedConfig.secret,\n                basePath:\n                    normalizedConfig.baseURL !== undefined\n                        ? normalizeBasePath(normalizedConfig.baseURL)\n                        : undefined,\n                advanced,\n            };\n\n            cachedServer = createServer(serverOptions);\n        }\n        return cachedServer;\n    };\n\n    const getRegisteredAgent = <TName extends TAgents[number][\"name\"]>(\n        agentName: TName,\n        traceAt: string,\n    ): AgentByName<TAgents, TName> => {\n        const agent = normalizedConfig.agents.find((candidate) => candidate.name === agentName);\n        if (!agent) {\n            throw BetterAgentError.fromCode(\n                \"NOT_FOUND\",\n                `Agent '${agentName}' not found in app registry.`,\n                {\n                    context: { agentName, availableAgents: Array.from(registry.agents.keys()) },\n                    trace: [{ at: traceAt }],\n                },\n            );\n        }\n\n        return agent as AgentByName<TAgents, TName>;\n    };\n\n    const base: BetterAgentApp<TAgents, TPlugins> & { handler: BetterAgentHandler } = {\n        config: normalizedConfig,\n        run: (agentName, input) => {\n            getRegisteredAgent(agentName, \"core.app.betterAgent.run\");\n            const runtime = getRuntime();\n            return runtime.run(agentName, input);\n        },\n        stream: (agentName, input) => {\n            getRegisteredAgent(agentName, \"core.app.betterAgent.stream\");\n            const runtime = getRuntime();\n            return runtime.stream(agentName, input);\n        },\n        resumeStream: async (params) => {\n            const runtime = getRuntime();\n            return runtime.resumeStream(params);\n        },\n        resumeConversation: async (agentName, params) => {\n            getRegisteredAgent(agentName, \"core.app.betterAgent.resumeConversation\");\n            const runtime = getRuntime();\n            return runtime.resumeConversation(agentName, params);\n        },\n        abortRun: async (runId: string) => {\n            const runtime = getRuntime();\n            return runtime.abortRun(runId);\n        },\n        loadConversation: async (agentName, conversationId) => {\n            getRegisteredAgent(agentName, \"core.app.betterAgent.loadConversation\");\n            const runtime = getRuntime();\n            return runtime.loadConversation(agentName, conversationId);\n        },\n        submitToolResult: async (params) => {\n            const runtime = getRuntime();\n            return runtime.submitToolResult(params);\n        },\n        submitToolApproval: async (params) => {\n            const runtime = getRuntime();\n            return runtime.submitToolApproval(params);\n        },\n        handler: (request) => {\n            const server = getServer();\n            return server.handle(request);\n        },\n    };\n\n    return base as typeof base & {\n        readonly __appTypes?: {\n            readonly agents: TAgents;\n            readonly tools: TTools;\n        };\n    };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,SAAgB,YAKZ,QAOF;CAEE,MAAM,mBAAmB,eAAe,OAAO;CAC/C,MAAM,WAAW,iBAAiB;AAClC,MAAK,MAAM,SAAS,iBAAiB,OACjC,yBAAwB,MAAM;CAIlC,MAAM,WAAW,wBAAwB;EACrC,QAAQ,iBAAiB;EACzB,OAAO,iBAAiB;EACxB,SAAS,iBAAiB;EAC7B,CAAC;CAGF,MAAM,gBAAgB,iBAAiB,UACjC,oBAAoB,iBAAiB,QAAQ,GAC7C;CAEN,IAAI,gBAAoD;CACxD,IAAI,sBAA0D;CAC9D,IAAI,eAAuD;CAE3D,MAAM,mBAAmB;AACrB,MAAI,CAAC,cAUD,iBAAgB,cATO;GACnB,QAAQ,iBAAiB;GACzB;GACA,QAAQ,iBAAiB,aAAa;GACtC,eAAe,iBAAiB,aAAa;GAC7C,cAAc,iBAAiB,aAAa;GAC5C;GACH,CAE4C;AAEjD,SAAO;;CAGX,MAAM,yBAAyB;AAC3B,MAAI,CAAC,oBAcD,uBAAsB,cAbC;GACnB,QAAQ,iBAAiB;GACzB;GACA,QAAQ,iBAAiB,aAAa;GACtC,eAAe,iBAAiB,aAAa;GAC7C,cAAc,iBAAiB,aAAa;GAC5C,iBACI,UAAU,wBAAwB,aAC3B,aACD;GACV;GACH,CAEkD;AAEvD,SAAO;;CAGX,MAAM,qBAAqB,YAA4B;AACnD,MAAI;AACA,UAAO,IAAI,IAAI,QAAQ,CAAC;UACpB;AACJ,UAAO,IAAI,IAAI,SAAS,4BAA4B,CAAC;;;CAI7D,MAAM,kBAAkB;AACpB,MAAI,CAAC,aAaD,gBAAe,aAX2C;GACtD,SAFY,kBAAkB;GAG9B;GACA,QAAQ,iBAAiB;GACzB,UACI,iBAAiB,YAAY,SACvB,kBAAkB,iBAAiB,QAAQ,GAC3C;GACV;GACH,CAEyC;AAE9C,SAAO;;CAGX,MAAM,sBACF,WACA,YAC8B;EAC9B,MAAM,QAAQ,iBAAiB,OAAO,MAAM,cAAc,UAAU,SAAS,UAAU;AACvF,MAAI,CAAC,MACD,OAAM,iBAAiB,SACnB,aACA,UAAU,UAAU,+BACpB;GACI,SAAS;IAAE;IAAW,iBAAiB,MAAM,KAAK,SAAS,OAAO,MAAM,CAAC;IAAE;GAC3E,OAAO,CAAC,EAAE,IAAI,SAAS,CAAC;GAC3B,CACJ;AAGL,SAAO;;AA+CX,QA5CkF;EAC9E,QAAQ;EACR,MAAM,WAAW,UAAU;AACvB,sBAAmB,WAAW,2BAA2B;AAEzD,UADgB,YAAY,CACb,IAAI,WAAW,MAAM;;EAExC,SAAS,WAAW,UAAU;AAC1B,sBAAmB,WAAW,8BAA8B;AAE5D,UADgB,YAAY,CACb,OAAO,WAAW,MAAM;;EAE3C,cAAc,OAAO,WAAW;AAE5B,UADgB,YAAY,CACb,aAAa,OAAO;;EAEvC,oBAAoB,OAAO,WAAW,WAAW;AAC7C,sBAAmB,WAAW,0CAA0C;AAExE,UADgB,YAAY,CACb,mBAAmB,WAAW,OAAO;;EAExD,UAAU,OAAO,UAAkB;AAE/B,UADgB,YAAY,CACb,SAAS,MAAM;;EAElC,kBAAkB,OAAO,WAAW,mBAAmB;AACnD,sBAAmB,WAAW,wCAAwC;AAEtE,UADgB,YAAY,CACb,iBAAiB,WAAW,eAAe;;EAE9D,kBAAkB,OAAO,WAAW;AAEhC,UADgB,YAAY,CACb,iBAAiB,OAAO;;EAE3C,oBAAoB,OAAO,WAAW;AAElC,UADgB,YAAY,CACb,mBAAmB,OAAO;;EAE7C,UAAU,YAAY;AAElB,UADe,WAAW,CACZ,OAAO,QAAQ;;EAEpC"}

package/dist/app/registry.mjs

@@ -0,0 +1,43 @@
+//#region src/app/registry.ts
+/**
+* Builds an app registry from config.
+*/
+function buildRegistryFromConfig(config) {
+	const registry = createAppRegistry();
+	for (const agent of config.agents) registerAgent(registry, agent);
+	if (config.tools !== void 0) registerTools(registry, config.tools);
+	if (config.plugins !== void 0 && config.plugins.length > 0) registerPlugins(registry, config.plugins);
+	return registry;
+}
+/**
+* Creates an empty app registry.
+*/
+function createAppRegistry() {
+	return {
+		agents: /* @__PURE__ */ new Map(),
+		tools: void 0,
+		plugins: []
+	};
+}
+/**
+* Registers an agent.
+*/
+function registerAgent(registry, agent) {
+	registry.agents.set(agent.name, agent);
+}
+/**
+* Registers shared tools.
+*/
+function registerTools(registry, tools) {
+	registry.tools = tools;
+}
+/**
+* Registers multiple plugins.
+*/
+function registerPlugins(registry, plugins) {
+	registry.plugins.push(...plugins);
+}
+
+//#endregion
+export { buildRegistryFromConfig };
+//# sourceMappingURL=registry.mjs.map

package/dist/app/registry.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.mjs","names":[],"sources":["../../src/app/registry.ts"],"sourcesContent":["import type { AgentTools, AnyAgentDefinition } from \"../agent\";\nimport type { Plugin } from \"../plugins\";\n\n/**\n * Builds an app registry from config.\n */\nexport function buildRegistryFromConfig(config: {\n    agents: readonly AnyAgentDefinition[];\n    tools?: AgentTools<unknown> | undefined;\n    plugins?: readonly Plugin[] | undefined;\n}): AppRegistry {\n    const registry = createAppRegistry();\n\n    for (const agent of config.agents) {\n        registerAgent(registry, agent);\n    }\n\n    if (config.tools !== undefined) {\n        registerTools(registry, config.tools);\n    }\n\n    if (config.plugins !== undefined && config.plugins.length > 0) {\n        registerPlugins(registry, config.plugins);\n    }\n\n    return registry;\n}\n\n/**\n * Registry for app components.\n */\nexport interface AppRegistry {\n    /** Agents by name. */\n    agents: Map<string, AnyAgentDefinition>;\n    /** Shared tools available to all agents. */\n    tools: AgentTools<unknown> | undefined;\n    /** Registered plugins. */\n    plugins: Plugin[];\n}\n\n/**\n * Creates an empty app registry.\n */\nexport function createAppRegistry(): AppRegistry {\n    return {\n        agents: new Map(),\n        tools: undefined,\n        plugins: [],\n    };\n}\n\n/**\n * Registers an agent.\n */\nexport function registerAgent(registry: AppRegistry, agent: AnyAgentDefinition): void {\n    registry.agents.set(agent.name, agent);\n}\n\n/**\n * Looks up an agent by name.\n */\nexport function lookupAgent(registry: AppRegistry, name: string): AnyAgentDefinition | undefined {\n    return registry.agents.get(name);\n}\n\n/**\n * Registers shared tools.\n */\nexport function registerTools(registry: AppRegistry, tools: AgentTools<unknown>): void {\n    registry.tools = tools;\n}\n\n/**\n * Registers a plugin.\n */\nexport function registerPlugin(registry: AppRegistry, plugin: Plugin): void {\n    registry.plugins.push(plugin);\n}\n\n/**\n * Registers multiple plugins.\n */\nexport function registerPlugins(registry: AppRegistry, plugins: readonly Plugin[]): void {\n    registry.plugins.push(...plugins);\n}\n"],"mappings":";;;;AAMA,SAAgB,wBAAwB,QAIxB;CACZ,MAAM,WAAW,mBAAmB;AAEpC,MAAK,MAAM,SAAS,OAAO,OACvB,eAAc,UAAU,MAAM;AAGlC,KAAI,OAAO,UAAU,OACjB,eAAc,UAAU,OAAO,MAAM;AAGzC,KAAI,OAAO,YAAY,UAAa,OAAO,QAAQ,SAAS,EACxD,iBAAgB,UAAU,OAAO,QAAQ;AAG7C,QAAO;;;;;AAkBX,SAAgB,oBAAiC;AAC7C,QAAO;EACH,wBAAQ,IAAI,KAAK;EACjB,OAAO;EACP,SAAS,EAAE;EACd;;;;;AAML,SAAgB,cAAc,UAAuB,OAAiC;AAClF,UAAS,OAAO,IAAI,MAAM,MAAM,MAAM;;;;;AAa1C,SAAgB,cAAc,UAAuB,OAAkC;AACnF,UAAS,QAAQ;;;;;AAarB,SAAgB,gBAAgB,UAAuB,SAAkC;AACrF,UAAS,QAAQ,KAAK,GAAG,QAAQ"}

package/dist/app/types.d.mts

@@ -0,0 +1,142 @@
+import { AgentToolDefinition } from "../tools/types.mjs";
+import { ConversationItem } from "../providers/types/conversation.mjs";
+import { AnyAgentDefinition } from "../agent/types.mjs";
+import { ConversationRuntimeStateStore, ConversationStore, StreamEvent, StreamStore } from "../persistence/types.mjs";
+import { Plugin } from "../plugins/types.mjs";
+import { ResumeConversationOptions, ResumeStreamOptions, RunOptionsForAgent, RunOutputOverrideForAgent, RunResultForAgent, StreamResultForAgent, SubmitToolApprovalParams, SubmitToolResultParams } from "../run/types.mjs";
+//#region src/app/types.d.ts
+interface BetterAgentAdvancedConfig {
+  /**
+   * Default timeout for waiting on client tool results.
+   */
+  clientToolResultTimeoutMs?: number;
+  /**
+   * Default timeout for waiting on tool approvals.
+   */
+  toolApprovalTimeoutMs?: number;
+  /**
+   * Controls what the built-in HTTP handler does when the original request disconnects.
+   *
+   * - `abort`: abort the run with the request.
+   * - `continue`: keep the run executing on the server and only stop the disconnected reader.
+   *
+   * This only affects Better Agent's built-in HTTP/server layer.
+   */
+  onRequestDisconnect?: "abort" | "continue";
+  /** Heartbeat interval for built-in SSE responses.
+   *
+   * This only affects Better Agent's built-in HTTP/server layer.
+   */
+  sseHeartbeatMs?: number;
+}
+/**
+ * App configuration.
+ *
+ * @typeParam TAgents Agents bundled into the app.
+ * @typeParam TPlugins Plugins registered on the app.
+ * @typeParam TTools Shared tools available to agents.
+ */
+interface BetterAgentConfig<TAgents extends readonly AnyAgentDefinition[] = readonly AnyAgentDefinition[], TPlugins extends readonly Plugin[] = readonly Plugin[], TTools extends readonly AgentToolDefinition[] = readonly AgentToolDefinition[]> {
+  /** Built-in runtime and HTTP behavior. */
+  readonly advanced?: BetterAgentAdvancedConfig;
+  /** Agents included in the app. */
+  readonly agents: TAgents;
+  /**
+   * Shared tools available to agents in this app.
+   *
+   * Agents can still declare their own tools.
+   */
+  readonly tools?: TTools;
+  /**
+   * Plugins applied to the app.
+   *
+   * Use plugins for cross-cutting behavior such as logging, auth, or rate limiting.
+   */
+  readonly plugins?: TPlugins;
+  /** Persistence configuration for runs and streams. */
+  readonly persistence?: {
+    /** Stream store for event resumption. */stream?: StreamStore; /** Conversation store. */
+    conversations?: ConversationStore; /** Optional conversation runtime-state store for conversation-based stream resume. */
+    runtimeState?: ConversationRuntimeStateStore;
+  };
+  /**
+   * Optional bearer secret for the built-in HTTP server.
+   * When set, built-in server routes require `Authorization: Bearer <secret>`
+   * unless a plugin endpoint is marked `public: true`.
+   */
+  readonly secret?: string;
+  /**
+   * Optional base URL for the app's API, used by clients and framework integrations.
+   *
+   * If set, the URL pathname is also used as the built-in server `basePath`.
+   * For example, `https://example.com/api` makes the built-in server available under `/api`.
+   */
+  readonly baseURL?: string;
+}
+/**
+ * HTTP request handler used by framework integrations.
+ */
+type BetterAgentHandler = (request: Request) => Promise<Response>;
+/**
+ * Looks up one agent type by its name.
+ */
+type AgentByName<TAgents extends readonly AnyAgentDefinition[], TName extends TAgents[number]["name"]> = Extract<TAgents[number], {
+  name: TName;
+}>;
+/** Shared app-level input for `run()` and `stream()`. */
+type AppRunInput<TAgent extends AnyAgentDefinition = AnyAgentDefinition, TOutput extends RunOutputOverrideForAgent<TAgent> | undefined = undefined> = RunOptionsForAgent<TAgent, TOutput>;
+/** Run options for `app.run()`. */
+type AppRunOptions<TAgent extends AnyAgentDefinition = AnyAgentDefinition, TOutput extends RunOutputOverrideForAgent<TAgent> | undefined = undefined> = AppRunInput<TAgent, TOutput>;
+/** Stream options for `app.stream()`. */
+type AppStreamOptions<TAgent extends AnyAgentDefinition = AnyAgentDefinition, TOutput extends RunOutputOverrideForAgent<TAgent> | undefined = undefined> = AppRunInput<TAgent, TOutput>;
+/**
+ * Better Agent app bundle.
+ *
+ * @typeParam TAgents Agents bundled into the app.
+ * @typeParam TPlugins Plugins registered on the app.
+ */
+interface BetterAgentApp<TAgents extends readonly AnyAgentDefinition[] = readonly AnyAgentDefinition[], TPlugins extends readonly Plugin[] = readonly Plugin[]> {
+  /** App configuration used to construct this instance. */
+  readonly config: BetterAgentConfig<TAgents, TPlugins>;
+  /**
+   * Runs an agent and waits for the final result.
+   */
+  run: <TName extends TAgents[number]["name"], TOutput extends RunOutputOverrideForAgent<AgentByName<TAgents, TName>> | undefined = undefined>(agentName: TName, options: AppRunOptions<AgentByName<TAgents, TName>, TOutput>) => Promise<RunResultForAgent<AgentByName<TAgents, TName>, TOutput>>;
+  /**
+   * Streams agent execution events.
+   */
+  stream: <TName extends TAgents[number]["name"], TOutput extends RunOutputOverrideForAgent<AgentByName<TAgents, TName>> | undefined = undefined>(agentName: TName, options: AppStreamOptions<AgentByName<TAgents, TName>, TOutput>) => StreamResultForAgent<AgentByName<TAgents, TName>, TOutput>;
+  /**
+   * Resumes a stored stream by stream id.
+   */
+  resumeStream: (params: ResumeStreamOptions) => Promise<AsyncIterable<StreamEvent> | null>;
+  /**
+   * Resumes the active stream for a conversation.
+   */
+  resumeConversation: <TName extends TAgents[number]["name"]>(agentName: TName, params: ResumeConversationOptions) => Promise<AsyncIterable<StreamEvent> | null>;
+  /** Aborts an active run by id. */
+  abortRun: (runId: string) => Promise<boolean>;
+  /**
+   * Load the persisted durable history for one conversation.
+   *
+   * Returns `null` when no stored conversation exists.
+   */
+  loadConversation: <TName extends TAgents[number]["name"]>(agentName: TName, conversationId: string) => Promise<{
+    items: ConversationItem[];
+  } | null>;
+  /**
+   * Submits a result for a pending client tool call.
+   */
+  submitToolResult: (params: SubmitToolResultParams) => Promise<boolean>;
+  /**
+   * Submits a tool approval decision.
+   */
+  submitToolApproval: (params: SubmitToolApprovalParams) => Promise<boolean>;
+  /**
+   * HTTP handler for framework integration.
+   */
+  handler: BetterAgentHandler;
+}
+//#endregion
+export { AppRunInput, AppRunOptions, AppStreamOptions, BetterAgentAdvancedConfig, BetterAgentApp, BetterAgentConfig, BetterAgentHandler };
+//# sourceMappingURL=types.d.mts.map

package/dist/app/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../src/app/types.ts"],"mappings":";;;;;;;UAsBiB,yBAAA;;;;EAIb,yBAAA;;;;EAIA,qBAAA;EARsC;;;;;;;;EAiBtC,mBAAA;EAea;;;;EAVb,cAAA;AAAA;;;;;;;;UAUa,iBAAA,0BACY,kBAAA,cAAgC,kBAAA,8BAC/B,MAAA,cAAoB,MAAA,4BACtB,mBAAA,cAAiC,mBAAA;EA2BrC;EAAA,SAxBX,QAAA,GAAW,yBAAA;EA0B4B;EAAA,SAvBvC,MAAA,EAAQ,OAAA;EARjB;;;;;EAAA,SAeS,KAAA,GAAQ,MAAA;EAbjB;;;;;EAAA,SAoBS,OAAA,GAAU,QAAA;EAdF;EAAA,SAiBR,WAAA;IAVQ,yCAYb,MAAA,GAAS,WAAA,EALM;IAOf,aAAA,GAAgB,iBAAA,EAFhB;IAIA,YAAA,GAAe,6BAAA;EAAA;EAFC;;;;;EAAA,SAUX,MAAA;EAQO;AAepB;;;;;EAfoB,SAAP,OAAA;AAAA;;;;KAeD,kBAAA,IAAsB,OAAA,EAAS,OAAA,KAAY,OAAA,CAAQ,QAAA;;;;KAKnD,WAAA,0BACiB,kBAAA,kBACX,OAAA,oBACd,OAAA,CAAQ,OAAA;EAAmB,IAAA,EAAM,KAAA;AAAA;;KAgEzB,WAAA,gBACO,kBAAA,GAAqB,kBAAA,kBACpB,yBAAA,CAA0B,MAAA,6BAC1C,kBAAA,CAAmB,MAAA,EAAQ,OAAA;;KAGnB,aAAA,gBACO,kBAAA,GAAqB,kBAAA,kBACpB,yBAAA,CAA0B,MAAA,6BAC1C,WAAA,CAAY,MAAA,EAAQ,OAAA;;KAGZ,gBAAA,gBACO,kBAAA,GAAqB,kBAAA,kBACpB,yBAAA,CAA0B,MAAA,6BAC1C,WAAA,CAAY,MAAA,EAAQ,OAAA;;;;;;;UAQP,cAAA,0BACY,kBAAA,cAAgC,kBAAA,8BAC/B,MAAA,cAAoB,MAAA;EAlBV;EAAA,SAqB3B,MAAA,EAAQ,iBAAA,CAAkB,OAAA,EAAS,QAAA;EApB5B;;;EAyBhB,GAAA,iBACkB,OAAA,kCAER,yBAAA,CAA0B,WAAA,CAAY,OAAA,EAAS,KAAA,4BAGrD,SAAA,EAAW,KAAA,EACX,OAAA,EAAS,aAAA,CAAc,WAAA,CAAY,OAAA,EAAS,KAAA,GAAQ,OAAA,MACnD,OAAA,CAAQ,iBAAA,CAAkB,WAAA,CAAY,OAAA,EAAS,KAAA,GAAQ,OAAA;EAhCxC;;;EAqCpB,MAAA,iBACkB,OAAA,kCAER,yBAAA,CAA0B,WAAA,CAAY,OAAA,EAAS,KAAA,4BAGrD,SAAA,EAAW,KAAA,EACX,OAAA,EAAS,gBAAA,CAAiB,WAAA,CAAY,OAAA,EAAS,KAAA,GAAQ,OAAA,MACtD,oBAAA,CAAqB,WAAA,CAAY,OAAA,EAAS,KAAA,GAAQ,OAAA;EA1C/B;;;EA+CxB,YAAA,GAAe,MAAA,EAAQ,mBAAA,KAAwB,OAAA,CAAQ,aAAA,CAAc,WAAA;EA7C3B;;;EAkD1C,kBAAA,iBAAmC,OAAA,kBAC/B,SAAA,EAAW,KAAA,EACX,MAAA,EAAQ,yBAAA,KACP,OAAA,CAAQ,aAAA,CAAc,WAAA;EApD3B;EAuDA,QAAA,GAAW,KAAA,aAAkB,OAAA;EAvDlB;;;;;EA8DX,gBAAA,iBAAiC,OAAA,kBAC7B,SAAA,EAAW,KAAA,EACX,cAAA,aACC,OAAA;IAAU,KAAA,EAAO,gBAAA;EAAA;EAjEV;;;EAsEZ,gBAAA,GAAmB,MAAA,EAAQ,sBAAA,KAA2B,OAAA;EA9DzC;;;EAmEb,kBAAA,GAAqB,MAAA,EAAQ,wBAAA,KAA6B,OAAA;EAlED;;;EAuEzD,OAAA,EAAS,kBAAA;AAAA"}

package/dist/events/constants.d.mts

@@ -0,0 +1,49 @@
+//#region src/events/constants.d.ts
+/**
+ * Event name constants emitted by the runtime.
+ */
+declare const Events: {
+  readonly RUN_STARTED: "RUN_STARTED";
+  readonly RUN_FINISHED: "RUN_FINISHED";
+  readonly RUN_ERROR: "RUN_ERROR";
+  readonly RUN_ABORTED: "RUN_ABORTED";
+  readonly DATA_PART: "DATA_PART";
+  readonly STEP_START: "STEP_START";
+  readonly STEP_FINISH: "STEP_FINISH";
+  readonly STEP_ERROR: "STEP_ERROR";
+  readonly TOOL_CALL_START: "TOOL_CALL_START";
+  readonly TOOL_CALL_ARGS: "TOOL_CALL_ARGS";
+  readonly TOOL_CALL_END: "TOOL_CALL_END";
+  readonly TOOL_CALL_RESULT: "TOOL_CALL_RESULT";
+  readonly TOOL_APPROVAL_REQUIRED: "TOOL_APPROVAL_REQUIRED";
+  readonly TOOL_APPROVAL_UPDATED: "TOOL_APPROVAL_UPDATED";
+  readonly TEXT_MESSAGE_START: "TEXT_MESSAGE_START";
+  readonly TEXT_MESSAGE_CONTENT: "TEXT_MESSAGE_CONTENT";
+  readonly TEXT_MESSAGE_END: "TEXT_MESSAGE_END";
+  readonly IMAGE_MESSAGE_START: "IMAGE_MESSAGE_START";
+  readonly IMAGE_MESSAGE_CONTENT: "IMAGE_MESSAGE_CONTENT";
+  readonly IMAGE_MESSAGE_END: "IMAGE_MESSAGE_END";
+  readonly VIDEO_MESSAGE_START: "VIDEO_MESSAGE_START";
+  readonly VIDEO_MESSAGE_CONTENT: "VIDEO_MESSAGE_CONTENT";
+  readonly VIDEO_MESSAGE_END: "VIDEO_MESSAGE_END";
+  readonly AUDIO_MESSAGE_START: "AUDIO_MESSAGE_START";
+  readonly AUDIO_MESSAGE_CONTENT: "AUDIO_MESSAGE_CONTENT";
+  readonly AUDIO_MESSAGE_END: "AUDIO_MESSAGE_END";
+  readonly TRANSCRIPT_MESSAGE_START: "TRANSCRIPT_MESSAGE_START";
+  readonly TRANSCRIPT_MESSAGE_CONTENT: "TRANSCRIPT_MESSAGE_CONTENT";
+  readonly TRANSCRIPT_MESSAGE_SEGMENT: "TRANSCRIPT_MESSAGE_SEGMENT";
+  readonly TRANSCRIPT_MESSAGE_END: "TRANSCRIPT_MESSAGE_END";
+  readonly REASONING_MESSAGE_START: "REASONING_MESSAGE_START";
+  readonly REASONING_MESSAGE_CONTENT: "REASONING_MESSAGE_CONTENT";
+  readonly REASONING_MESSAGE_END: "REASONING_MESSAGE_END";
+  readonly EMBEDDING_MESSAGE_START: "EMBEDDING_MESSAGE_START";
+  readonly EMBEDDING_MESSAGE_CONTENT: "EMBEDDING_MESSAGE_CONTENT";
+  readonly EMBEDDING_MESSAGE_END: "EMBEDDING_MESSAGE_END";
+};
+/**
+ * Union of all event names.
+ */
+type EventName = (typeof Events)[keyof typeof Events];
+//#endregion
+export { EventName, Events };
+//# sourceMappingURL=constants.d.mts.map

package/dist/events/constants.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.mts","names":[],"sources":["../../src/events/constants.ts"],"mappings":";;AAGA;;cAAa,MAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuDb;KAAY,SAAA,WAAoB,MAAA,eAAqB,MAAA"}

package/dist/events/constants.mjs

@@ -0,0 +1,46 @@
+//#region src/events/constants.ts
+/**
+* Event name constants emitted by the runtime.
+*/
+const Events = {
+	RUN_STARTED: "RUN_STARTED",
+	RUN_FINISHED: "RUN_FINISHED",
+	RUN_ERROR: "RUN_ERROR",
+	RUN_ABORTED: "RUN_ABORTED",
+	DATA_PART: "DATA_PART",
+	STEP_START: "STEP_START",
+	STEP_FINISH: "STEP_FINISH",
+	STEP_ERROR: "STEP_ERROR",
+	TOOL_CALL_START: "TOOL_CALL_START",
+	TOOL_CALL_ARGS: "TOOL_CALL_ARGS",
+	TOOL_CALL_END: "TOOL_CALL_END",
+	TOOL_CALL_RESULT: "TOOL_CALL_RESULT",
+	TOOL_APPROVAL_REQUIRED: "TOOL_APPROVAL_REQUIRED",
+	TOOL_APPROVAL_UPDATED: "TOOL_APPROVAL_UPDATED",
+	TEXT_MESSAGE_START: "TEXT_MESSAGE_START",
+	TEXT_MESSAGE_CONTENT: "TEXT_MESSAGE_CONTENT",
+	TEXT_MESSAGE_END: "TEXT_MESSAGE_END",
+	IMAGE_MESSAGE_START: "IMAGE_MESSAGE_START",
+	IMAGE_MESSAGE_CONTENT: "IMAGE_MESSAGE_CONTENT",
+	IMAGE_MESSAGE_END: "IMAGE_MESSAGE_END",
+	VIDEO_MESSAGE_START: "VIDEO_MESSAGE_START",
+	VIDEO_MESSAGE_CONTENT: "VIDEO_MESSAGE_CONTENT",
+	VIDEO_MESSAGE_END: "VIDEO_MESSAGE_END",
+	AUDIO_MESSAGE_START: "AUDIO_MESSAGE_START",
+	AUDIO_MESSAGE_CONTENT: "AUDIO_MESSAGE_CONTENT",
+	AUDIO_MESSAGE_END: "AUDIO_MESSAGE_END",
+	TRANSCRIPT_MESSAGE_START: "TRANSCRIPT_MESSAGE_START",
+	TRANSCRIPT_MESSAGE_CONTENT: "TRANSCRIPT_MESSAGE_CONTENT",
+	TRANSCRIPT_MESSAGE_SEGMENT: "TRANSCRIPT_MESSAGE_SEGMENT",
+	TRANSCRIPT_MESSAGE_END: "TRANSCRIPT_MESSAGE_END",
+	REASONING_MESSAGE_START: "REASONING_MESSAGE_START",
+	REASONING_MESSAGE_CONTENT: "REASONING_MESSAGE_CONTENT",
+	REASONING_MESSAGE_END: "REASONING_MESSAGE_END",
+	EMBEDDING_MESSAGE_START: "EMBEDDING_MESSAGE_START",
+	EMBEDDING_MESSAGE_CONTENT: "EMBEDDING_MESSAGE_CONTENT",
+	EMBEDDING_MESSAGE_END: "EMBEDDING_MESSAGE_END"
+};
+
+//#endregion
+export { Events };
+//# sourceMappingURL=constants.mjs.map

package/dist/events/constants.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.mjs","names":[],"sources":["../../src/events/constants.ts"],"sourcesContent":["/**\n * Event name constants emitted by the runtime.\n */\nexport const Events = {\n    RUN_STARTED: \"RUN_STARTED\",\n    RUN_FINISHED: \"RUN_FINISHED\",\n    RUN_ERROR: \"RUN_ERROR\",\n    RUN_ABORTED: \"RUN_ABORTED\",\n\n    // User-defined runtime data payload.\n    DATA_PART: \"DATA_PART\",\n\n    STEP_START: \"STEP_START\",\n    STEP_FINISH: \"STEP_FINISH\",\n    STEP_ERROR: \"STEP_ERROR\",\n\n    TOOL_CALL_START: \"TOOL_CALL_START\",\n    TOOL_CALL_ARGS: \"TOOL_CALL_ARGS\",\n    TOOL_CALL_END: \"TOOL_CALL_END\",\n    TOOL_CALL_RESULT: \"TOOL_CALL_RESULT\",\n\n    TOOL_APPROVAL_REQUIRED: \"TOOL_APPROVAL_REQUIRED\",\n    TOOL_APPROVAL_UPDATED: \"TOOL_APPROVAL_UPDATED\",\n\n    TEXT_MESSAGE_START: \"TEXT_MESSAGE_START\",\n    TEXT_MESSAGE_CONTENT: \"TEXT_MESSAGE_CONTENT\",\n    TEXT_MESSAGE_END: \"TEXT_MESSAGE_END\",\n\n    IMAGE_MESSAGE_START: \"IMAGE_MESSAGE_START\",\n    IMAGE_MESSAGE_CONTENT: \"IMAGE_MESSAGE_CONTENT\",\n    IMAGE_MESSAGE_END: \"IMAGE_MESSAGE_END\",\n\n    VIDEO_MESSAGE_START: \"VIDEO_MESSAGE_START\",\n    VIDEO_MESSAGE_CONTENT: \"VIDEO_MESSAGE_CONTENT\",\n    VIDEO_MESSAGE_END: \"VIDEO_MESSAGE_END\",\n\n    AUDIO_MESSAGE_START: \"AUDIO_MESSAGE_START\",\n    AUDIO_MESSAGE_CONTENT: \"AUDIO_MESSAGE_CONTENT\",\n    AUDIO_MESSAGE_END: \"AUDIO_MESSAGE_END\",\n\n    TRANSCRIPT_MESSAGE_START: \"TRANSCRIPT_MESSAGE_START\",\n    TRANSCRIPT_MESSAGE_CONTENT: \"TRANSCRIPT_MESSAGE_CONTENT\",\n    // Finalized transcript segment.\n    TRANSCRIPT_MESSAGE_SEGMENT: \"TRANSCRIPT_MESSAGE_SEGMENT\",\n    TRANSCRIPT_MESSAGE_END: \"TRANSCRIPT_MESSAGE_END\",\n\n    REASONING_MESSAGE_START: \"REASONING_MESSAGE_START\",\n    REASONING_MESSAGE_CONTENT: \"REASONING_MESSAGE_CONTENT\",\n    REASONING_MESSAGE_END: \"REASONING_MESSAGE_END\",\n\n    EMBEDDING_MESSAGE_START: \"EMBEDDING_MESSAGE_START\",\n    EMBEDDING_MESSAGE_CONTENT: \"EMBEDDING_MESSAGE_CONTENT\",\n    EMBEDDING_MESSAGE_END: \"EMBEDDING_MESSAGE_END\",\n} as const;\n\n/**\n * Union of all event names.\n */\nexport type EventName = (typeof Events)[keyof typeof Events];\n"],"mappings":";;;;AAGA,MAAa,SAAS;CAClB,aAAa;CACb,cAAc;CACd,WAAW;CACX,aAAa;CAGb,WAAW;CAEX,YAAY;CACZ,aAAa;CACb,YAAY;CAEZ,iBAAiB;CACjB,gBAAgB;CAChB,eAAe;CACf,kBAAkB;CAElB,wBAAwB;CACxB,uBAAuB;CAEvB,oBAAoB;CACpB,sBAAsB;CACtB,kBAAkB;CAElB,qBAAqB;CACrB,uBAAuB;CACvB,mBAAmB;CAEnB,qBAAqB;CACrB,uBAAuB;CACvB,mBAAmB;CAEnB,qBAAqB;CACrB,uBAAuB;CACvB,mBAAmB;CAEnB,0BAA0B;CAC1B,4BAA4B;CAE5B,4BAA4B;CAC5B,wBAAwB;CAExB,yBAAyB;CACzB,2BAA2B;CAC3B,uBAAuB;CAEvB,yBAAyB;CACzB,2BAA2B;CAC3B,uBAAuB;CAC1B"}

package/dist/events/index.d.mts

@@ -0,0 +1,4 @@
+import { EventName, Events } from "./constants.mjs";
+import { ToolApprovalState, ToolTarget } from "../tools/types.mjs";
+import { AudioMessageContentEvent, AudioMessageEndEvent, AudioMessageStartEvent, BaseEvent, BetterAgentErrorLike, DataPartEvent, EmbeddingMessageContentEvent, EmbeddingMessageEndEvent, EmbeddingMessageStartEvent, Event, ImageMessageContentEvent, ImageMessageEndEvent, ImageMessageStartEvent, ModelEvent, ReasoningMessageContentEvent, ReasoningMessageEndEvent, ReasoningMessageStartEvent, ReasoningVisibility, Role, RunAbortedEvent, RunErrorEvent, RunFinishedEvent, RunStartedEvent, StepErrorEvent, StepFinishEvent, StepStartEvent, StepTerminationReason, TextMessageContentEvent, TextMessageEndEvent, TextMessageStartEvent, ToolApprovalRequiredEvent, ToolApprovalUpdatedEvent, ToolCallArgsEvent, ToolCallEndEvent, ToolCallResultEvent, ToolCallStartEvent, TranscriptMessageContentEvent, TranscriptMessageEndEvent, TranscriptMessageSegmentEvent, TranscriptMessageStartEvent, VideoMessageContentEvent, VideoMessageEndEvent, VideoMessageStartEvent } from "./types.mjs";
+export { AudioMessageContentEvent, AudioMessageEndEvent, AudioMessageStartEvent, BaseEvent, BetterAgentErrorLike, DataPartEvent, EmbeddingMessageContentEvent, EmbeddingMessageEndEvent, EmbeddingMessageStartEvent, Event, type EventName, Events, ImageMessageContentEvent, ImageMessageEndEvent, ImageMessageStartEvent, ModelEvent, ReasoningMessageContentEvent, ReasoningMessageEndEvent, ReasoningMessageStartEvent, ReasoningVisibility, Role, RunAbortedEvent, RunErrorEvent, RunFinishedEvent, RunStartedEvent, StepErrorEvent, StepFinishEvent, StepStartEvent, StepTerminationReason, TextMessageContentEvent, TextMessageEndEvent, TextMessageStartEvent, ToolApprovalRequiredEvent, ToolApprovalState, ToolApprovalUpdatedEvent, ToolCallArgsEvent, ToolCallEndEvent, ToolCallResultEvent, ToolCallStartEvent, ToolTarget, TranscriptMessageContentEvent, TranscriptMessageEndEvent, TranscriptMessageSegmentEvent, TranscriptMessageStartEvent, VideoMessageContentEvent, VideoMessageEndEvent, VideoMessageStartEvent };

package/dist/events/index.mjs

@@ -0,0 +1,3 @@
+import { Events } from "./constants.mjs";
+
+export { Events };