@better-agent/core 0.1.0-canary.0

package/README.md

@@ -0,0 +1,3 @@
+# @better-agent/core
+
+Core package for Better Agent.

package/dist/agent/constants.mjs

@@ -0,0 +1,6 @@
+//#region src/agent/constants.ts
+const AGENT_OUTPUT_JSON_SCHEMA = Symbol.for("better-agent.agent.output.json_schema");
+
+//#endregion
+export { AGENT_OUTPUT_JSON_SCHEMA };
+//# sourceMappingURL=constants.mjs.map

package/dist/agent/constants.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.mjs","names":[],"sources":["../../src/agent/constants.ts"],"sourcesContent":["export const AGENT_OUTPUT_JSON_SCHEMA = Symbol.for(\"better-agent.agent.output.json_schema\");\n"],"mappings":";AAAA,MAAa,2BAA2B,OAAO,IAAI,wCAAwC"}

package/dist/agent/define-agent.d.mts

@@ -0,0 +1,29 @@
+import { ResolvableSchema } from "../schema/types.mjs";
+import { Capabilities, ModalitiesParam, OutputSchemaForCaps } from "../providers/types/capabilities.mjs";
+import { AgentContextFromSchema, AgentModelCaps, DefineAgentConfig, DefinedAgent } from "./types.mjs";
+
+//#region src/agent/define-agent.d.ts
+/**
+ * Defines an agent.
+ *
+ * @param config Agent configuration.
+ * @returns The defined agent.
+ *
+ * @example
+ * ```ts
+ * const supportAgent = defineAgent({
+ *   name: "support",
+ *   model: openai.model("gpt-5"),
+ *   instruction: "You are a helpful support agent.",
+ *   tools: [getWeather],
+ * });
+ * ```
+ */
+declare function defineAgent<const TName extends string, const TModel extends {
+  providerId: string;
+  modelId: string;
+  caps: Capabilities;
+}, const TContextSchema extends ResolvableSchema | undefined = undefined, const TContext = AgentContextFromSchema<TContextSchema>, const TTools = undefined, const TOutputSchema extends OutputSchemaForCaps<AgentModelCaps<TModel>> | undefined = undefined, const TDefaultModalities extends ModalitiesParam<AgentModelCaps<TModel>> | undefined = undefined>(config: DefineAgentConfig<TName, TModel, TContextSchema, TContext, TTools, TOutputSchema, TDefaultModalities>): DefinedAgent<TName, TModel, TContextSchema, TContext, TTools, TOutputSchema, TDefaultModalities>;
+//#endregion
+export { defineAgent };
+//# sourceMappingURL=define-agent.d.mts.map

package/dist/agent/define-agent.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-agent.d.mts","names":[],"sources":["../../src/agent/define-agent.ts"],"mappings":";;;;;;;;;AA0BA;;;;;;;;;;;;iBAAgB,WAAA;EAEW,UAAA;EAAoB,OAAA;EAAiB,IAAA,EAAM,YAAA;AAAA,gCACrC,gBAAA,2CACZ,sBAAA,CAAuB,cAAA,yDAEZ,mBAAA,CAAoB,cAAA,CAAe,MAAA,6DAEzD,eAAA,CAAgB,cAAA,CAAe,MAAA,2BAAA,CAGrC,MAAA,EAAQ,iBAAA,CACJ,KAAA,EACA,MAAA,EACA,cAAA,EACA,QAAA,EACA,MAAA,EACA,aAAA,EACA,kBAAA,IAEL,YAAA,CACC,KAAA,EACA,MAAA,EACA,cAAA,EACA,QAAA,EACA,MAAA,EACA,aAAA,EACA,kBAAA"}

package/dist/agent/define-agent.mjs

@@ -0,0 +1,27 @@
+import { validateAgentDefinition } from "./validation.mjs";
+
+//#region src/agent/define-agent.ts
+/**
+* Defines an agent.
+*
+* @param config Agent configuration.
+* @returns The defined agent.
+*
+* @example
+* ```ts
+* const supportAgent = defineAgent({
+*   name: "support",
+*   model: openai.model("gpt-5"),
+*   instruction: "You are a helpful support agent.",
+*   tools: [getWeather],
+* });
+* ```
+*/
+function defineAgent(config) {
+	validateAgentDefinition(config);
+	return config;
+}
+
+//#endregion
+export { defineAgent };
+//# sourceMappingURL=define-agent.mjs.map

package/dist/agent/define-agent.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-agent.mjs","names":[],"sources":["../../src/agent/define-agent.ts"],"sourcesContent":["import type { Capabilities, ModalitiesParam, OutputSchemaForCaps } from \"../providers\";\nimport type { ResolvableSchema } from \"../schema\";\nimport type {\n    AgentContextFromSchema,\n    AgentModelCaps,\n    DefineAgentConfig,\n    DefinedAgent,\n} from \"./types\";\nimport { validateAgentDefinition } from \"./validation\";\n\n/**\n * Defines an agent.\n *\n * @param config Agent configuration.\n * @returns The defined agent.\n *\n * @example\n * ```ts\n * const supportAgent = defineAgent({\n *   name: \"support\",\n *   model: openai.model(\"gpt-5\"),\n *   instruction: \"You are a helpful support agent.\",\n *   tools: [getWeather],\n * });\n * ```\n */\nexport function defineAgent<\n    const TName extends string,\n    const TModel extends { providerId: string; modelId: string; caps: Capabilities },\n    const TContextSchema extends ResolvableSchema | undefined = undefined,\n    const TContext = AgentContextFromSchema<TContextSchema>,\n    const TTools = undefined,\n    const TOutputSchema extends OutputSchemaForCaps<AgentModelCaps<TModel>> | undefined = undefined,\n    const TDefaultModalities extends\n        | ModalitiesParam<AgentModelCaps<TModel>>\n        | undefined = undefined,\n>(\n    config: DefineAgentConfig<\n        TName,\n        TModel,\n        TContextSchema,\n        TContext,\n        TTools,\n        TOutputSchema,\n        TDefaultModalities\n    >,\n): DefinedAgent<\n    TName,\n    TModel,\n    TContextSchema,\n    TContext,\n    TTools,\n    TOutputSchema,\n    TDefaultModalities\n> {\n    validateAgentDefinition(config);\n\n    return config as DefinedAgent<\n        TName,\n        TModel,\n        TContextSchema,\n        TContext,\n        TTools,\n        TOutputSchema,\n        TDefaultModalities\n    >;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AA0BA,SAAgB,YAWZ,QAiBF;AACE,yBAAwB,OAAO;AAE/B,QAAO"}

package/dist/agent/index.d.mts

@@ -0,0 +1,2 @@
+import { AgentContext, AgentContextFromSchema, AgentContextSchema, AgentConversationReplayOptions, AgentDefinition, AgentInstruction, AgentKnownToolName, AgentModelCaps, AgentModelOptions, AgentOnStep, AgentOnStepFinish, AgentOutputSchema, AgentStructuredOutput, AgentTools, AnyAgentDefinition, DefineAgentConfig, DefinedAgent } from "./types.mjs";
+import { defineAgent } from "./define-agent.mjs";

package/dist/agent/types.d.mts

@@ -0,0 +1,216 @@
+import { Awaitable, BivariantFn } from "../internal/types.mjs";
+import { InferSchemaInput, ResolvableSchema } from "../schema/types.mjs";
+import { Capabilities, InferOutputSchema, InstructionEnabled, ModalitiesParam, ModalityOptionsFor, OutputSchemaDefinition, OutputSchemaForCaps } from "../providers/types/capabilities.mjs";
+import { OnToolError, OpenString, ToolErrorMode, ToolNamesOf, ToolSource } from "../tools/types.mjs";
+import { GenerativeModelInputMessageContent, ModelOptions } from "../providers/types/input.mjs";
+import { GenerativeModel } from "../providers/types/model.mjs";
+import { ConversationReplayOptions, OnStepContext, OnStepFinishContext, RunAdvancedOptions, StopWhen } from "../run/types.mjs";
+import { OnOutputError, OutputErrorMode } from "../run/output-errors.mjs";
+//#region src/agent/types.d.ts
+/**
+ * Defines an agent.
+ */
+type AgentConversationReplayOptions = Omit<ConversationReplayOptions, "prepareInput"> & {
+  prepareInput?: Exclude<ConversationReplayOptions["prepareInput"], null>;
+};
+/**
+ * Defines an agent.
+ */
+interface AgentDefinition<TName extends string = string, TModel extends AnyAgentModel = AnyAgentModel, TContextSchema extends ResolvableSchema | undefined = undefined, TContext = AgentContextFromSchema<TContextSchema>, TTools = undefined, TOutputSchema extends OutputSchemaForCaps<AgentModelCaps<TModel>> | undefined = undefined, TDefaultModalities extends ModalitiesParam<AgentModelCaps<TModel>> | undefined = undefined> {
+  /** Stable agent name. */
+  name: TName;
+  /** Short description for humans. */
+  description?: string;
+  /** Model used for runs. */
+  model: TModel;
+  /**
+   * Default model options for this agent's runs.
+   *
+   * Per-run overrides always win.
+   */
+  defaultModelOptions?: AgentModelOptions<TModel> & ModalityOptionsFor<AgentModelCaps<TModel>, TDefaultModalities>;
+  /**
+   * Default output modalities for this agent's runs.
+   *
+   * Per-run modalities always win.
+   */
+  defaultModalities?: TDefaultModalities;
+  /**
+   * Default system instruction.
+   *
+   * Can be static or derived from validated context.
+   */
+  instruction?: AgentInstruction<TContext, AgentModelCaps<TModel>>;
+  /** Optional schema used to validate run context. */
+  contextSchema?: TContextSchema;
+  /**
+   * Default structured output schema.
+   *
+   * Requires model with `outputModalities: { text: true }`.
+   */
+  outputSchema?: TOutputSchema;
+  /** Tools available to the agent. */
+  tools?: TTools;
+  /** Default handling mode for recoverable tool failures. */
+  toolErrorMode?: ToolErrorMode;
+  /** Optional hook for customizing recoverable tool failures. */
+  onToolError?: OnToolError;
+  /** Default handling mode for structured output finalization failures. */
+  outputErrorMode?: OutputErrorMode;
+  /** Optional hook for customizing structured output finalization failures. */
+  onOutputError?: OnOutputError;
+  /**
+   * Maximum number of loop steps per run.
+   *
+   * When omitted, a run stops naturally or when `stopWhen` returns `true`.
+   */
+  maxSteps?: number;
+  /** Advanced runtime defaults for interactive flows. */
+  advanced?: RunAdvancedOptions;
+  /** Default replay shaping for stored conversation history used by this agent. */
+  conversationReplay?: AgentConversationReplayOptions;
+  /** Optional stop condition checked after each completed step. */
+  stopWhen?: StopWhen<TContextSchema, TContext>;
+  /** Optional hook called before each step starts. */
+  onStep?: AgentOnStep<TContextSchema, TContext>;
+  /** Optional hook called after each step completes. */
+  onStepFinish?: AgentOnStepFinish<TContextSchema, TContext>;
+}
+/**
+ * Broad agent definition type for heterogeneous collections.
+ */
+type AnyAgentDefinition = {
+  name: string;
+  description?: string;
+  model: any;
+  defaultModelOptions?: Record<string, unknown>;
+  defaultModalities?: ModalitiesParam<Capabilities>;
+  instruction?: unknown;
+  contextSchema?: ResolvableSchema | undefined;
+  outputSchema?: OutputSchemaDefinition | undefined;
+  tools?: unknown;
+  toolErrorMode?: ToolErrorMode;
+  onToolError?: OnToolError;
+  outputErrorMode?: OutputErrorMode;
+  onOutputError?: OnOutputError;
+  maxSteps?: number;
+  advanced?: RunAdvancedOptions;
+  conversationReplay?: AgentConversationReplayOptions;
+  stopWhen?: StopWhen<any, any>;
+  onStep?: AgentOnStep<any, any, Capabilities>;
+  onStepFinish?: AgentOnStepFinish<any, any>;
+};
+/**
+ * Concrete agent shape after all generics are resolved.
+ */
+type DefinedAgent<TName extends string, TModel extends AnyAgentModel, TContextSchema extends ResolvableSchema | undefined, TContext, TTools, TOutputSchema extends OutputSchemaForCaps<AgentModelCaps<TModel>> | undefined, TDefaultModalities extends ModalitiesParam<AgentModelCaps<TModel>> | undefined> = {
+  name: TName;
+  description?: string;
+  model: TModel;
+  defaultModelOptions?: AgentModelOptions<TModel> & ModalityOptionsFor<AgentModelCaps<TModel>, TDefaultModalities>;
+  defaultModalities?: TDefaultModalities;
+  instruction?: AgentInstruction<TContext, AgentModelCaps<TModel>>;
+  tools?: TTools;
+  toolErrorMode?: ToolErrorMode;
+  onToolError?: OnToolError;
+  outputErrorMode?: OutputErrorMode;
+  onOutputError?: OnOutputError;
+  maxSteps?: number;
+  advanced?: RunAdvancedOptions;
+  conversationReplay?: AgentConversationReplayOptions;
+  stopWhen?: StopWhen<TContextSchema, TContext>;
+  onStep?: AgentOnStep<TContextSchema, TContext, any>;
+  onStepFinish?: AgentOnStepFinish<TContextSchema, TContext>;
+} & ([TContextSchema] extends [undefined] ? {
+  contextSchema?: undefined;
+} : {
+  contextSchema: TContextSchema;
+}) & ([TOutputSchema] extends [undefined] ? {
+  outputSchema?: undefined;
+} : {
+  outputSchema: TOutputSchema;
+});
+type DefineAgentConfig<TName extends string, TModel extends AnyAgentModel, TContextSchema extends ResolvableSchema | undefined, TContext, TTools, TOutputSchema extends OutputSchemaForCaps<AgentModelCaps<TModel>> | undefined, TDefaultModalities extends ModalitiesParam<AgentModelCaps<TModel>> | undefined> = Omit<AgentDefinition<TName, TModel, TContextSchema, TContext, TTools, TOutputSchema, TDefaultModalities>, "outputSchema" | "outputErrorMode" | "onOutputError" | "tools" | "toolErrorMode" | "onToolError" | "instruction" | "onStep"> & DefineAgentInstructionField<TModel, TContext> & DefineAgentToolFields<TModel, TContext, TTools> & DefineAgentHookFields<TModel, TContextSchema, TContext> & DefineAgentOutputSchemaField<TModel, TOutputSchema> & DefineAgentOutputErrorFields<TModel>;
+/**
+ * Instruction value accepted by an agent.
+ */
+type AgentInstruction<TContext = unknown, TModelCaps extends Capabilities = Capabilities> = InstructionEnabled<TModelCaps> extends true ? GenerativeModelInputMessageContent<TModelCaps> | BivariantFn<[TContext], GenerativeModelInputMessageContent<TModelCaps>> : never;
+/**
+ * Tool sources accepted by an agent.
+ */
+type AgentTools<TContext = unknown> = ToolSource<TContext> | readonly ToolSource<TContext>[];
+/**
+ * `onStep` hook for an agent.
+ */
+type AgentOnStep<TContextSchema extends ResolvableSchema | undefined = undefined, TContext = unknown, TModelCaps extends Capabilities = Capabilities> = BivariantFn<[OnStepContext<TContextSchema, TContext, TModelCaps>], Awaitable<void>>;
+/**
+ * `onStepFinish` hook for an agent.
+ */
+type AgentOnStepFinish<TContextSchema extends ResolvableSchema | undefined = undefined, TContext = unknown> = (context: OnStepFinishContext<TContextSchema, TContext>) => Awaitable<void>;
+/**
+ * Provider-specific model options accepted by an agent's model.
+ */
+type AgentModelOptions<TModel> = TModel extends GenerativeModel<infer TOptions, infer _TProviderId, infer _TModelId, infer _TCaps> ? ModelOptions<TOptions> : Record<never, never>;
+/**
+ * Infers the validated context type from a context schema.
+ */
+type AgentContextFromSchema<TSchema> = [TSchema] extends [undefined] ? unknown : InferSchemaInput<NonNullable<TSchema>>;
+/**
+ * Extracts the validated context type from an agent.
+ */
+type AgentContext<TAgent> = TAgent extends AgentDefinition<infer _TName, infer _TModel, infer _TContextSchema, infer TContext, infer _TTools, infer _TOutputSchema, infer _TDefaultModalities> ? TContext : unknown;
+/**
+ * Extracts the declared context schema from an agent.
+ */
+type AgentContextSchema<TAgent> = TAgent extends AgentDefinition<infer _TName, infer _TModel, infer _TContextSchema, infer _TContext, infer _TTools, infer _TOutputSchema, infer _TDefaultModalities> ? TAgent extends {
+  contextSchema: infer TContextSchema;
+} ? TContextSchema : undefined : undefined;
+/**
+ * Extracts the default output schema from an agent.
+ */
+type AgentOutputSchema<TAgent> = TAgent extends AgentDefinition<infer _TName, infer _TModel, infer _TContextSchema, infer _TContext, infer _TTools, infer _TOutputSchema, infer _TDefaultModalities> ? TAgent extends {
+  outputSchema: infer TOutputSchema;
+} ? TOutputSchema : undefined : undefined;
+/**
+ * Infers the structured output payload produced by an agent.
+ */
+type AgentStructuredOutput<TAgent> = InferOutputSchema<AgentOutputSchema<TAgent>>;
+/**
+ * Static tool-name union for an agent.
+ */
+type AgentKnownToolName<TAgent> = TAgent extends AgentDefinition<infer _TName, infer _TModel, infer _TContextSchema, infer _TContext, infer TTools, infer _TOutputSchema, infer _TDefaultModalities> ? OpenString<ToolNamesOf<NonNullable<TTools>>> : string;
+type AnyAgentModel = {
+  readonly providerId: string;
+  readonly modelId: string;
+  readonly caps: Capabilities;
+  doGenerate?(...args: any[]): unknown;
+  doGenerateStream?(...args: any[]): unknown;
+};
+type AgentModelCaps<TModel> = TModel extends {
+  caps: infer TCaps extends Capabilities;
+} ? TCaps : Capabilities;
+type DefineAgentOutputSchemaField<TModel extends AnyAgentModel, TOutputSchema extends OutputSchemaForCaps<AgentModelCaps<TModel>> | undefined> = [OutputSchemaForCaps<AgentModelCaps<TModel>>] extends [never] ? object : {
+  /** Optional default structured output schema for runs that do not override `output`. */outputSchema?: TOutputSchema;
+};
+type DefineAgentOutputErrorFields<TModel extends AnyAgentModel> = [OutputSchemaForCaps<AgentModelCaps<TModel>>] extends [never] ? object : {
+  /** Default handling mode for structured output finalization failures. */outputErrorMode?: OutputErrorMode; /** Optional hook for customizing structured output finalization failures. */
+  onOutputError?: OnOutputError;
+};
+type DefineAgentInstructionField<TModel extends AnyAgentModel, TContext> = InstructionEnabled<AgentModelCaps<TModel>> extends true ? {
+  /**
+   * Main instruction for the agent.
+   * Can be static or derived from validated context.
+   */
+  instruction?: AgentInstruction<TContext, AgentModelCaps<TModel>>;
+} : object;
+type DefineAgentToolFields<TModel extends AnyAgentModel, _TContext, TTools> = AgentModelCaps<TModel>["tools"] extends true ? {
+  /** Tools available to the agent. */tools?: TTools; /** Default handling mode for recoverable tool failures. */
+  toolErrorMode?: ToolErrorMode; /** Optional hook for customizing recoverable tool failures. */
+  onToolError?: OnToolError;
+} : object;
+type DefineAgentHookFields<TModel extends AnyAgentModel, TContextSchema extends ResolvableSchema | undefined, TContext> = {
+  /** Optional hook called before each step starts. */onStep?: AgentOnStep<TContextSchema, TContext, AgentModelCaps<TModel>>;
+};
+//#endregion
+export { AgentContext, AgentContextFromSchema, AgentContextSchema, AgentConversationReplayOptions, AgentDefinition, AgentInstruction, AgentKnownToolName, AgentModelCaps, AgentModelOptions, AgentOnStep, AgentOnStepFinish, AgentOutputSchema, AgentStructuredOutput, AgentTools, AnyAgentDefinition, DefineAgentConfig, DefinedAgent };
+//# sourceMappingURL=types.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../src/agent/types.ts"],"mappings":"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"}

package/dist/agent/validation.mjs

@@ -0,0 +1,64 @@
+import { resolveToJsonSchema } from "../schema/resolve-json-schema.mjs";
+import { AGENT_OUTPUT_JSON_SCHEMA } from "./constants.mjs";
+import { BetterAgentError } from "@better-agent/shared/errors";
+
+//#region src/agent/validation.ts
+const cachePreflightedOutputSchema = (agent, schema) => {
+	Object.defineProperty(agent, AGENT_OUTPUT_JSON_SCHEMA, {
+		value: schema,
+		configurable: true,
+		writable: true
+	});
+};
+const validateOptionalPositiveNumber = (value, field, traceAt, context) => {
+	if (value !== void 0 && (!Number.isFinite(value) || value <= 0)) throw BetterAgentError.fromCode("VALIDATION_FAILED", `${field} must be a positive number.`, {
+		context: {
+			[field]: value,
+			...context ?? {}
+		},
+		trace: [{ at: traceAt }]
+	});
+};
+/**
+* Validates one agent definition and caches any preflighted structured output schema.
+*/
+const validateAgentDefinition = (agent) => {
+	if (typeof agent.name !== "string" || agent.name.length === 0) throw BetterAgentError.fromCode("VALIDATION_FAILED", "Agent name must be a non-empty string.", { trace: [{ at: "core.agent.validateAgentDefinition.name" }] });
+	if (agent.model === void 0 || agent.model === null) throw BetterAgentError.fromCode("VALIDATION_FAILED", `Agent '${agent.name}' must have a model.`, {
+		context: { agentName: agent.name },
+		trace: [{ at: "core.agent.validateAgentDefinition.model" }]
+	});
+	validateOptionalPositiveNumber(agent.advanced?.clientToolResultTimeoutMs, "clientToolResultTimeoutMs", "core.agent.validateAgentDefinition.advanced.clientToolResultTimeoutMs", { agentName: agent.name });
+	validateOptionalPositiveNumber(agent.advanced?.toolApprovalTimeoutMs, "toolApprovalTimeoutMs", "core.agent.validateAgentDefinition.advanced.toolApprovalTimeoutMs", { agentName: agent.name });
+	if (agent.conversationReplay?.omitUnsupportedParts !== void 0 && typeof agent.conversationReplay.omitUnsupportedParts !== "boolean") throw BetterAgentError.fromCode("VALIDATION_FAILED", "conversationReplay.omitUnsupportedParts must be a boolean.", {
+		context: { agentName: agent.name },
+		trace: [{ at: "core.agent.validateAgentDefinition.conversationReplay.omitUnsupportedParts" }]
+	});
+	if (agent.conversationReplay?.prepareInput !== void 0 && typeof agent.conversationReplay.prepareInput !== "function") throw BetterAgentError.fromCode("VALIDATION_FAILED", "conversationReplay.prepareInput must be a function.", {
+		context: { agentName: agent.name },
+		trace: [{ at: "core.agent.validateAgentDefinition.conversationReplay.prepareInput" }]
+	});
+	if (agent.outputSchema !== void 0 && agent[AGENT_OUTPUT_JSON_SCHEMA] === void 0) {
+		const resolvedSchema = resolveToJsonSchema(agent.outputSchema.schema);
+		if (resolvedSchema.isErr()) throw resolvedSchema.error.at({
+			at: "core.agent.validateAgentDefinition.outputSchema",
+			data: { agentName: agent.name }
+		});
+		cachePreflightedOutputSchema(agent, resolvedSchema.value);
+	}
+	const contextStandard = agent.contextSchema?.["~standard"];
+	const contextJsonSchema = contextStandard && typeof contextStandard === "object" ? contextStandard.jsonSchema : void 0;
+	if (agent.contextSchema !== void 0 && (contextJsonSchema !== void 0 || contextStandard === void 0)) {
+		const resolvedSchema = resolveToJsonSchema(agent.contextSchema);
+		if (resolvedSchema.isErr()) throw resolvedSchema.error.at({
+			at: "core.agent.validateAgentDefinition.contextSchema",
+			data: { agentName: agent.name }
+		});
+	}
+	return agent;
+};
+const getPreflightedOutputSchema = (agent) => agent[AGENT_OUTPUT_JSON_SCHEMA];
+
+//#endregion
+export { getPreflightedOutputSchema, validateAgentDefinition };
+//# sourceMappingURL=validation.mjs.map

package/dist/agent/validation.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.mjs","names":[],"sources":["../../src/agent/validation.ts"],"sourcesContent":["import { BetterAgentError } from \"@better-agent/shared/errors\";\nimport { resolveToJsonSchema } from \"../schema\";\nimport type { ResolvableSchema, ValidatableSchema } from \"../schema\";\nimport { AGENT_OUTPUT_JSON_SCHEMA } from \"./constants\";\n\ntype AgentValidationTarget = {\n    name?: unknown;\n    model?: unknown;\n    maxSteps?: number;\n    conversationReplay?: {\n        omitUnsupportedParts?: boolean;\n        prepareInput?: unknown;\n    };\n    advanced?: {\n        clientToolResultTimeoutMs?: number;\n        toolApprovalTimeoutMs?: number;\n    };\n    contextSchema?: ValidatableSchema | undefined;\n    outputSchema?: {\n        schema: ResolvableSchema;\n    };\n    [AGENT_OUTPUT_JSON_SCHEMA]?: Record<string, unknown>;\n};\n\nconst cachePreflightedOutputSchema = (\n    agent: AgentValidationTarget,\n    schema: Record<string, unknown>,\n): void => {\n    Object.defineProperty(agent, AGENT_OUTPUT_JSON_SCHEMA, {\n        value: schema,\n        configurable: true,\n        writable: true,\n    });\n};\n\nconst validateOptionalPositiveNumber = (\n    value: number | undefined,\n    field: string,\n    traceAt: string,\n    context?: Record<string, unknown>,\n) => {\n    if (value !== undefined && (!Number.isFinite(value) || value <= 0)) {\n        throw BetterAgentError.fromCode(\n            \"VALIDATION_FAILED\",\n            `${field} must be a positive number.`,\n            {\n                context: {\n                    [field]: value,\n                    ...(context ?? {}),\n                },\n                trace: [{ at: traceAt }],\n            },\n        );\n    }\n};\n\n/**\n * Validates one agent definition and caches any preflighted structured output schema.\n */\nexport const validateAgentDefinition = <const TAgent extends AgentValidationTarget>(\n    agent: TAgent,\n): TAgent => {\n    if (typeof agent.name !== \"string\" || agent.name.length === 0) {\n        throw BetterAgentError.fromCode(\n            \"VALIDATION_FAILED\",\n            \"Agent name must be a non-empty string.\",\n            {\n                trace: [{ at: \"core.agent.validateAgentDefinition.name\" }],\n            },\n        );\n    }\n\n    if (agent.model === undefined || agent.model === null) {\n        throw BetterAgentError.fromCode(\n            \"VALIDATION_FAILED\",\n            `Agent '${agent.name}' must have a model.`,\n            {\n                context: { agentName: agent.name },\n                trace: [{ at: \"core.agent.validateAgentDefinition.model\" }],\n            },\n        );\n    }\n\n    validateOptionalPositiveNumber(\n        agent.advanced?.clientToolResultTimeoutMs,\n        \"clientToolResultTimeoutMs\",\n        \"core.agent.validateAgentDefinition.advanced.clientToolResultTimeoutMs\",\n        { agentName: agent.name },\n    );\n    validateOptionalPositiveNumber(\n        agent.advanced?.toolApprovalTimeoutMs,\n        \"toolApprovalTimeoutMs\",\n        \"core.agent.validateAgentDefinition.advanced.toolApprovalTimeoutMs\",\n        { agentName: agent.name },\n    );\n\n    if (\n        agent.conversationReplay?.omitUnsupportedParts !== undefined &&\n        typeof agent.conversationReplay.omitUnsupportedParts !== \"boolean\"\n    ) {\n        throw BetterAgentError.fromCode(\n            \"VALIDATION_FAILED\",\n            \"conversationReplay.omitUnsupportedParts must be a boolean.\",\n            {\n                context: { agentName: agent.name },\n                trace: [\n                    {\n                        at: \"core.agent.validateAgentDefinition.conversationReplay.omitUnsupportedParts\",\n                    },\n                ],\n            },\n        );\n    }\n\n    if (\n        agent.conversationReplay?.prepareInput !== undefined &&\n        typeof agent.conversationReplay.prepareInput !== \"function\"\n    ) {\n        throw BetterAgentError.fromCode(\n            \"VALIDATION_FAILED\",\n            \"conversationReplay.prepareInput must be a function.\",\n            {\n                context: { agentName: agent.name },\n                trace: [\n                    { at: \"core.agent.validateAgentDefinition.conversationReplay.prepareInput\" },\n                ],\n            },\n        );\n    }\n\n    if (agent.outputSchema !== undefined && agent[AGENT_OUTPUT_JSON_SCHEMA] === undefined) {\n        const resolvedSchema = resolveToJsonSchema(agent.outputSchema.schema);\n        if (resolvedSchema.isErr()) {\n            throw resolvedSchema.error.at({\n                at: \"core.agent.validateAgentDefinition.outputSchema\",\n                data: { agentName: agent.name },\n            });\n        }\n\n        cachePreflightedOutputSchema(agent, resolvedSchema.value);\n    }\n\n    const contextStandard = (agent.contextSchema as { \"~standard\"?: unknown })?.[\"~standard\"];\n    const contextJsonSchema =\n        contextStandard && typeof contextStandard === \"object\"\n            ? (contextStandard as { jsonSchema?: unknown }).jsonSchema\n            : undefined;\n\n    if (\n        agent.contextSchema !== undefined &&\n        (contextJsonSchema !== undefined || contextStandard === undefined)\n    ) {\n        const resolvedSchema = resolveToJsonSchema(agent.contextSchema as ResolvableSchema);\n        if (resolvedSchema.isErr()) {\n            throw resolvedSchema.error.at({\n                at: \"core.agent.validateAgentDefinition.contextSchema\",\n                data: { agentName: agent.name },\n            });\n        }\n    }\n\n    return agent;\n};\n\nexport const getPreflightedOutputSchema = (agent: object): Record<string, unknown> | undefined =>\n    (agent as { [AGENT_OUTPUT_JSON_SCHEMA]?: Record<string, unknown> })[AGENT_OUTPUT_JSON_SCHEMA];\n"],"mappings":";;;;;AAwBA,MAAM,gCACF,OACA,WACO;AACP,QAAO,eAAe,OAAO,0BAA0B;EACnD,OAAO;EACP,cAAc;EACd,UAAU;EACb,CAAC;;AAGN,MAAM,kCACF,OACA,OACA,SACA,YACC;AACD,KAAI,UAAU,WAAc,CAAC,OAAO,SAAS,MAAM,IAAI,SAAS,GAC5D,OAAM,iBAAiB,SACnB,qBACA,GAAG,MAAM,8BACT;EACI,SAAS;IACJ,QAAQ;GACT,GAAI,WAAW,EAAE;GACpB;EACD,OAAO,CAAC,EAAE,IAAI,SAAS,CAAC;EAC3B,CACJ;;;;;AAOT,MAAa,2BACT,UACS;AACT,KAAI,OAAO,MAAM,SAAS,YAAY,MAAM,KAAK,WAAW,EACxD,OAAM,iBAAiB,SACnB,qBACA,0CACA,EACI,OAAO,CAAC,EAAE,IAAI,2CAA2C,CAAC,EAC7D,CACJ;AAGL,KAAI,MAAM,UAAU,UAAa,MAAM,UAAU,KAC7C,OAAM,iBAAiB,SACnB,qBACA,UAAU,MAAM,KAAK,uBACrB;EACI,SAAS,EAAE,WAAW,MAAM,MAAM;EAClC,OAAO,CAAC,EAAE,IAAI,4CAA4C,CAAC;EAC9D,CACJ;AAGL,gCACI,MAAM,UAAU,2BAChB,6BACA,yEACA,EAAE,WAAW,MAAM,MAAM,CAC5B;AACD,gCACI,MAAM,UAAU,uBAChB,yBACA,qEACA,EAAE,WAAW,MAAM,MAAM,CAC5B;AAED,KACI,MAAM,oBAAoB,yBAAyB,UACnD,OAAO,MAAM,mBAAmB,yBAAyB,UAEzD,OAAM,iBAAiB,SACnB,qBACA,8DACA;EACI,SAAS,EAAE,WAAW,MAAM,MAAM;EAClC,OAAO,CACH,EACI,IAAI,8EACP,CACJ;EACJ,CACJ;AAGL,KACI,MAAM,oBAAoB,iBAAiB,UAC3C,OAAO,MAAM,mBAAmB,iBAAiB,WAEjD,OAAM,iBAAiB,SACnB,qBACA,uDACA;EACI,SAAS,EAAE,WAAW,MAAM,MAAM;EAClC,OAAO,CACH,EAAE,IAAI,sEAAsE,CAC/E;EACJ,CACJ;AAGL,KAAI,MAAM,iBAAiB,UAAa,MAAM,8BAA8B,QAAW;EACnF,MAAM,iBAAiB,oBAAoB,MAAM,aAAa,OAAO;AACrE,MAAI,eAAe,OAAO,CACtB,OAAM,eAAe,MAAM,GAAG;GAC1B,IAAI;GACJ,MAAM,EAAE,WAAW,MAAM,MAAM;GAClC,CAAC;AAGN,+BAA6B,OAAO,eAAe,MAAM;;CAG7D,MAAM,kBAAmB,MAAM,gBAA8C;CAC7E,MAAM,oBACF,mBAAmB,OAAO,oBAAoB,WACvC,gBAA6C,aAC9C;AAEV,KACI,MAAM,kBAAkB,WACvB,sBAAsB,UAAa,oBAAoB,SAC1D;EACE,MAAM,iBAAiB,oBAAoB,MAAM,cAAkC;AACnF,MAAI,eAAe,OAAO,CACtB,OAAM,eAAe,MAAM,GAAG;GAC1B,IAAI;GACJ,MAAM,EAAE,WAAW,MAAM,MAAM;GAClC,CAAC;;AAIV,QAAO;;AAGX,MAAa,8BAA8B,UACtC,MAAmE"}

package/dist/api.d.mts

@@ -0,0 +1,8 @@
+//#region src/api.d.ts
+/**
+ * Supported HTTP methods for Better Agent routes.
+ */
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS";
+//#endregion
+export { HttpMethod };
+//# sourceMappingURL=api.d.mts.map

package/dist/api.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.mts","names":[],"sources":["../src/api.ts"],"mappings":";;AAGA;;KAAY,UAAA"}

package/dist/api.mjs

@@ -0,0 +1,63 @@
+//#region src/api.ts
+/**
+* Defines one typed route entry.
+*/
+const defineRoute = (route) => route;
+/**
+* Matches a URL path against a route pattern.
+*/
+const matchRoutePath = (pattern, path) => {
+	const routeParts = pattern.split("/").filter(Boolean);
+	const pathParts = path.split("/").filter(Boolean);
+	if (routeParts.length !== pathParts.length) return null;
+	const params = {};
+	for (let index = 0; index < routeParts.length; index += 1) {
+		const expected = routeParts[index];
+		const actual = pathParts[index];
+		if (expected === void 0 || actual === void 0) return null;
+		if (expected.startsWith(":")) {
+			params[expected.slice(1)] = actual;
+			continue;
+		}
+		if (expected !== actual) return null;
+	}
+	return params;
+};
+/**
+* Creates a simple method-aware router from a route table.
+*/
+const createRouter = (routes) => ({
+	routes,
+	match(method, path) {
+		for (const route of routes) {
+			if (route.method !== method) continue;
+			const params = matchRoutePath(route.pattern, path);
+			if (params) return {
+				route,
+				params
+			};
+		}
+		return null;
+	},
+	matchPath(path) {
+		const methods = [];
+		let firstMatch = null;
+		for (const route of routes) {
+			const params = matchRoutePath(route.pattern, path);
+			if (!params) continue;
+			methods.push(route.method);
+			if (!firstMatch) firstMatch = {
+				route,
+				params
+			};
+		}
+		return firstMatch ? {
+			...firstMatch,
+			methods
+		} : null;
+	}
+});
+
+//#endregion
+export { createRouter, defineRoute };
+//# sourceMappingURL=api.mjs.map

package/dist/api.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.mjs","names":[],"sources":["../src/api.ts"],"sourcesContent":["/**\n * Supported HTTP methods for Better Agent routes.\n */\nexport type HttpMethod = \"GET\" | \"POST\" | \"PUT\" | \"PATCH\" | \"DELETE\" | \"OPTIONS\";\n\n/**\n * Path params extracted from a matched route.\n */\nexport type RouteParams = Record<string, string>;\n\n/**\n * Context passed to a route handler.\n */\nexport interface RouteContext<P extends RouteParams = RouteParams> {\n    request: Request;\n    path: string;\n    params: P;\n    query: URLSearchParams;\n}\n\n/**\n * One route entry in the server router.\n */\nexport interface RouteEntry<Path extends string = string> {\n    method: HttpMethod;\n    pattern: Path;\n    public?: boolean;\n    handler(ctx: RouteContext<ParamsFromPath<Path>>): Response | Promise<Response>;\n}\n\n/**\n * Route table consumed by the router.\n */\nexport type RouteTable = RouteEntry[];\n\n/**\n * Successful route match for one method and path.\n */\nexport interface RouteMatch {\n    route: RouteEntry;\n    params: RouteParams;\n}\n\n/**\n * Route match for a path regardless of method.\n */\nexport interface RoutePathMatch {\n    params: RouteParams;\n    methods: HttpMethod[];\n    route: RouteEntry;\n}\n\n/**\n * Method-aware router used by the built-in server.\n */\nexport interface Router {\n    readonly routes: RouteTable;\n    match(method: HttpMethod, path: string): RouteMatch | null;\n    matchPath(path: string): RoutePathMatch | null;\n}\n\n/**\n * Defines one typed route entry.\n */\nexport const defineRoute = <const P extends string>(route: RouteEntry<P>): RouteEntry<P> => route;\n\n/**\n * Matches a URL path against a route pattern.\n */\nexport const matchRoutePath = (pattern: string, path: string): RouteParams | null => {\n    const routeParts = pattern.split(\"/\").filter(Boolean);\n    const pathParts = path.split(\"/\").filter(Boolean);\n    if (routeParts.length !== pathParts.length) {\n        return null;\n    }\n\n    const params: RouteParams = {};\n    for (let index = 0; index < routeParts.length; index += 1) {\n        const expected = routeParts[index];\n        const actual = pathParts[index];\n        if (expected === undefined || actual === undefined) {\n            return null;\n        }\n\n        if (expected.startsWith(\":\")) {\n            params[expected.slice(1)] = actual;\n            continue;\n        }\n\n        if (expected !== actual) {\n            return null;\n        }\n    }\n\n    return params;\n};\n\n/**\n * Creates a simple method-aware router from a route table.\n */\nexport const createRouter = (routes: RouteTable): Router => ({\n    routes,\n    match(method, path) {\n        for (const route of routes) {\n            if (route.method !== method) {\n                continue;\n            }\n\n            const params = matchRoutePath(route.pattern, path);\n            if (params) {\n                return { route, params };\n            }\n        }\n\n        return null;\n    },\n    matchPath(path) {\n        const methods: HttpMethod[] = [];\n        let firstMatch: { route: RouteEntry; params: RouteParams } | null = null;\n\n        for (const route of routes) {\n            const params = matchRoutePath(route.pattern, path);\n            if (!params) {\n                continue;\n            }\n\n            methods.push(route.method);\n            if (!firstMatch) {\n                firstMatch = { route, params };\n            }\n        }\n\n        return firstMatch ? { ...firstMatch, methods } : null;\n    },\n});\n\ntype ExtractParamKeys<Path extends string> = Path extends `${string}:${infer Param}/${infer Rest}`\n    ? Param | ExtractParamKeys<`/${Rest}`>\n    : Path extends `${string}:${infer Param}`\n      ? Param\n      : never;\n\ntype ParamsFromPath<Path extends string> = {\n    [K in ExtractParamKeys<Path>]: string;\n};\n"],"mappings":";;;;AAgEA,MAAa,eAAuC,UAAwC;;;;AAK5F,MAAa,kBAAkB,SAAiB,SAAqC;CACjF,MAAM,aAAa,QAAQ,MAAM,IAAI,CAAC,OAAO,QAAQ;CACrD,MAAM,YAAY,KAAK,MAAM,IAAI,CAAC,OAAO,QAAQ;AACjD,KAAI,WAAW,WAAW,UAAU,OAChC,QAAO;CAGX,MAAM,SAAsB,EAAE;AAC9B,MAAK,IAAI,QAAQ,GAAG,QAAQ,WAAW,QAAQ,SAAS,GAAG;EACvD,MAAM,WAAW,WAAW;EAC5B,MAAM,SAAS,UAAU;AACzB,MAAI,aAAa,UAAa,WAAW,OACrC,QAAO;AAGX,MAAI,SAAS,WAAW,IAAI,EAAE;AAC1B,UAAO,SAAS,MAAM,EAAE,IAAI;AAC5B;;AAGJ,MAAI,aAAa,OACb,QAAO;;AAIf,QAAO;;;;;AAMX,MAAa,gBAAgB,YAAgC;CACzD;CACA,MAAM,QAAQ,MAAM;AAChB,OAAK,MAAM,SAAS,QAAQ;AACxB,OAAI,MAAM,WAAW,OACjB;GAGJ,MAAM,SAAS,eAAe,MAAM,SAAS,KAAK;AAClD,OAAI,OACA,QAAO;IAAE;IAAO;IAAQ;;AAIhC,SAAO;;CAEX,UAAU,MAAM;EACZ,MAAM,UAAwB,EAAE;EAChC,IAAI,aAAgE;AAEpE,OAAK,MAAM,SAAS,QAAQ;GACxB,MAAM,SAAS,eAAe,MAAM,SAAS,KAAK;AAClD,OAAI,CAAC,OACD;AAGJ,WAAQ,KAAK,MAAM,OAAO;AAC1B,OAAI,CAAC,WACD,cAAa;IAAE;IAAO;IAAQ;;AAItC,SAAO,aAAa;GAAE,GAAG;GAAY;GAAS,GAAG;;CAExD"}

package/dist/app/config.mjs

@@ -0,0 +1,43 @@
+import { BetterAgentError } from "@better-agent/shared/errors";
+
+//#region src/app/config.ts
+/**
+* Validates app configuration.
+*/
+function validateConfig(config) {
+	const validateOptionalPositiveNumber = (value, field) => {
+		if (value !== void 0 && (!Number.isFinite(value) || value <= 0)) throw BetterAgentError.fromCode("VALIDATION_FAILED", `${field} must be a positive number.`, {
+			context: { [field]: value },
+			trace: [{ at: "core.app.validateConfig" }]
+		});
+	};
+	if (!config.agents || config.agents.length === 0) throw BetterAgentError.fromCode("VALIDATION_FAILED", "App configuration must include at least one agent.", { trace: [{ at: "core.app.validateConfig" }] });
+	for (const agent of config.agents) if (typeof agent.name !== "string" || agent.name.length === 0) throw BetterAgentError.fromCode("VALIDATION_FAILED", "All agents must have a name.", { trace: [{ at: "core.app.validateConfig" }] });
+	const seenNames = /* @__PURE__ */ new Set();
+	for (const agent of config.agents) {
+		if (seenNames.has(agent.name)) throw BetterAgentError.fromCode("VALIDATION_FAILED", `Duplicate agent name '${agent.name}'.`, {
+			context: { agentName: agent.name },
+			trace: [{ at: "core.app.validateConfig" }]
+		});
+		seenNames.add(agent.name);
+	}
+	if (config.plugins) {
+		const seenPluginIds = /* @__PURE__ */ new Set();
+		for (const plugin of config.plugins) {
+			if (seenPluginIds.has(plugin.id)) throw BetterAgentError.fromCode("VALIDATION_FAILED", `Duplicate plugin id '${plugin.id}' in app config.`, {
+				context: { pluginId: plugin.id },
+				trace: [{ at: "core.app.validateConfig" }]
+			});
+			seenPluginIds.add(plugin.id);
+		}
+	}
+	validateOptionalPositiveNumber(config.advanced?.clientToolResultTimeoutMs, "advanced.clientToolResultTimeoutMs");
+	validateOptionalPositiveNumber(config.advanced?.toolApprovalTimeoutMs, "advanced.toolApprovalTimeoutMs");
+	validateOptionalPositiveNumber(config.advanced?.sseHeartbeatMs, "advanced.sseHeartbeatMs");
+	if (config.advanced?.onRequestDisconnect === "continue" && !config.persistence?.stream) throw BetterAgentError.fromCode("VALIDATION_FAILED", "advanced.onRequestDisconnect='continue' requires persistence.stream to be configured.", { trace: [{ at: "core.app.validateConfig" }] });
+	return config;
+}
+
+//#endregion
+export { validateConfig };
+//# sourceMappingURL=config.mjs.map

package/dist/app/config.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.mjs","names":[],"sources":["../../src/app/config.ts"],"sourcesContent":["import { BetterAgentError } from \"@better-agent/shared/errors\";\nimport type { AnyBetterAgentConfig } from \"./types\";\n\n/**\n * Validates app configuration.\n */\nexport function validateConfig<const TConfig extends AnyBetterAgentConfig>(\n    config: TConfig,\n): TConfig {\n    const validateOptionalPositiveNumber = (value: number | undefined, field: string) => {\n        if (value !== undefined && (!Number.isFinite(value) || value <= 0)) {\n            throw BetterAgentError.fromCode(\n                \"VALIDATION_FAILED\",\n                `${field} must be a positive number.`,\n                {\n                    context: { [field]: value },\n                    trace: [{ at: \"core.app.validateConfig\" }],\n                },\n            );\n        }\n    };\n\n    // Validate required agents field\n    if (!config.agents || config.agents.length === 0) {\n        throw BetterAgentError.fromCode(\n            \"VALIDATION_FAILED\",\n            \"App configuration must include at least one agent.\",\n            {\n                trace: [{ at: \"core.app.validateConfig\" }],\n            },\n        );\n    }\n\n    // Validate app-level agent defaults that only make sense in app assembly.\n    for (const agent of config.agents) {\n        if (typeof agent.name !== \"string\" || agent.name.length === 0) {\n            throw BetterAgentError.fromCode(\"VALIDATION_FAILED\", \"All agents must have a name.\", {\n                trace: [{ at: \"core.app.validateConfig\" }],\n            });\n        }\n    }\n\n    // Validate unique agent names\n    const seenNames = new Set<string>();\n    for (const agent of config.agents) {\n        if (seenNames.has(agent.name)) {\n            throw BetterAgentError.fromCode(\n                \"VALIDATION_FAILED\",\n                `Duplicate agent name '${agent.name}'.`,\n                {\n                    context: { agentName: agent.name },\n                    trace: [{ at: \"core.app.validateConfig\" }],\n                },\n            );\n        }\n        seenNames.add(agent.name);\n    }\n\n    // Validate unique plugin ids\n    if (config.plugins) {\n        const seenPluginIds = new Set<string>();\n        for (const plugin of config.plugins) {\n            if (seenPluginIds.has(plugin.id)) {\n                throw BetterAgentError.fromCode(\n                    \"VALIDATION_FAILED\",\n                    `Duplicate plugin id '${plugin.id}' in app config.`,\n                    {\n                        context: { pluginId: plugin.id },\n                        trace: [{ at: \"core.app.validateConfig\" }],\n                    },\n                );\n            }\n            seenPluginIds.add(plugin.id);\n        }\n    }\n\n    // Normalize optional fields\n    validateOptionalPositiveNumber(\n        config.advanced?.clientToolResultTimeoutMs,\n        \"advanced.clientToolResultTimeoutMs\",\n    );\n    validateOptionalPositiveNumber(\n        config.advanced?.toolApprovalTimeoutMs,\n        \"advanced.toolApprovalTimeoutMs\",\n    );\n    validateOptionalPositiveNumber(config.advanced?.sseHeartbeatMs, \"advanced.sseHeartbeatMs\");\n\n    if (config.advanced?.onRequestDisconnect === \"continue\" && !config.persistence?.stream) {\n        throw BetterAgentError.fromCode(\n            \"VALIDATION_FAILED\",\n            \"advanced.onRequestDisconnect='continue' requires persistence.stream to be configured.\",\n            {\n                trace: [{ at: \"core.app.validateConfig\" }],\n            },\n        );\n    }\n\n    return config;\n}\n"],"mappings":";;;;;;AAMA,SAAgB,eACZ,QACO;CACP,MAAM,kCAAkC,OAA2B,UAAkB;AACjF,MAAI,UAAU,WAAc,CAAC,OAAO,SAAS,MAAM,IAAI,SAAS,GAC5D,OAAM,iBAAiB,SACnB,qBACA,GAAG,MAAM,8BACT;GACI,SAAS,GAAG,QAAQ,OAAO;GAC3B,OAAO,CAAC,EAAE,IAAI,2BAA2B,CAAC;GAC7C,CACJ;;AAKT,KAAI,CAAC,OAAO,UAAU,OAAO,OAAO,WAAW,EAC3C,OAAM,iBAAiB,SACnB,qBACA,sDACA,EACI,OAAO,CAAC,EAAE,IAAI,2BAA2B,CAAC,EAC7C,CACJ;AAIL,MAAK,MAAM,SAAS,OAAO,OACvB,KAAI,OAAO,MAAM,SAAS,YAAY,MAAM,KAAK,WAAW,EACxD,OAAM,iBAAiB,SAAS,qBAAqB,gCAAgC,EACjF,OAAO,CAAC,EAAE,IAAI,2BAA2B,CAAC,EAC7C,CAAC;CAKV,MAAM,4BAAY,IAAI,KAAa;AACnC,MAAK,MAAM,SAAS,OAAO,QAAQ;AAC/B,MAAI,UAAU,IAAI,MAAM,KAAK,CACzB,OAAM,iBAAiB,SACnB,qBACA,yBAAyB,MAAM,KAAK,KACpC;GACI,SAAS,EAAE,WAAW,MAAM,MAAM;GAClC,OAAO,CAAC,EAAE,IAAI,2BAA2B,CAAC;GAC7C,CACJ;AAEL,YAAU,IAAI,MAAM,KAAK;;AAI7B,KAAI,OAAO,SAAS;EAChB,MAAM,gCAAgB,IAAI,KAAa;AACvC,OAAK,MAAM,UAAU,OAAO,SAAS;AACjC,OAAI,cAAc,IAAI,OAAO,GAAG,CAC5B,OAAM,iBAAiB,SACnB,qBACA,wBAAwB,OAAO,GAAG,mBAClC;IACI,SAAS,EAAE,UAAU,OAAO,IAAI;IAChC,OAAO,CAAC,EAAE,IAAI,2BAA2B,CAAC;IAC7C,CACJ;AAEL,iBAAc,IAAI,OAAO,GAAG;;;AAKpC,gCACI,OAAO,UAAU,2BACjB,qCACH;AACD,gCACI,OAAO,UAAU,uBACjB,iCACH;AACD,gCAA+B,OAAO,UAAU,gBAAgB,0BAA0B;AAE1F,KAAI,OAAO,UAAU,wBAAwB,cAAc,CAAC,OAAO,aAAa,OAC5E,OAAM,iBAAiB,SACnB,qBACA,yFACA,EACI,OAAO,CAAC,EAAE,IAAI,2BAA2B,CAAC,EAC7C,CACJ;AAGL,QAAO"}

package/dist/app/create-app.d.mts

@@ -0,0 +1,36 @@
+import { AgentToolDefinition } from "../tools/types.mjs";
+import { AnyAgentDefinition } from "../agent/types.mjs";
+import { Plugin } from "../plugins/types.mjs";
+import { BetterAgentApp, BetterAgentConfig, BetterAgentHandler } from "./types.mjs";
+
+//#region src/app/create-app.d.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!",
+ * });
+ * ```
+ */
+declare function betterAgent<const TAgents extends readonly AnyAgentDefinition[], const TPlugins extends readonly Plugin[] = readonly Plugin[], const TTools extends readonly AgentToolDefinition[] = readonly AgentToolDefinition[]>(config: BetterAgentConfig<TAgents, TPlugins, TTools>): BetterAgentApp<TAgents, TPlugins> & {
+  handler: BetterAgentHandler;
+  readonly __appTypes?: {
+    readonly agents: TAgents;
+    readonly tools: TTools;
+  };
+};
+//#endregion
+export { betterAgent };
+//# sourceMappingURL=create-app.d.mts.map

package/dist/app/create-app.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-app.d.mts","names":[],"sources":["../../src/app/create-app.ts"],"mappings":";;;;;;;;;;;AAgCA;;;;;;;;;;;;;;;iBAAgB,WAAA,gCACmB,kBAAA,oCACC,MAAA,cAAoB,MAAA,kCACtB,mBAAA,cAAiC,mBAAA,GAAA,CAE/D,MAAA,EAAQ,iBAAA,CAAkB,OAAA,EAAS,QAAA,EAAU,MAAA,IAC9C,cAAA,CAAe,OAAA,EAAS,QAAA;EACvB,OAAA,EAAS,kBAAA;EAAA,SACA,UAAA;IAAA,SACI,MAAA,EAAQ,OAAA;IAAA,SACR,KAAA,EAAO,MAAA;EAAA;AAAA"}