@electric-ax/agents 0.2.3 → 0.3.0

package/dist/index.d.cts

@@ -1,7 +1,8 @@
-import { AgentTool, CodingAgentType, EntityRegistry, EntityStreamDBWithActions, HandlerContext, RuntimeHandler, WakeEvent } from "@electric-ax/agents-runtime";
+import { AgentConfig, AgentTool, AvailableProvider, EntityRegistry, EntityStreamDBWithActions, HandlerContext, RuntimeHandler, WakeEvent } from "@electric-ax/agents-runtime";
 import { ChangeEvent } from "@durable-streams/state";
 import { AgentTool as AgentTool$1, StreamFn } from "@mariozechner/pi-agent-core";
 import { IncomingMessage, ServerResponse } from "node:http";
+import { ListedEntry as McpListedEntry, McpConfig, McpServerConfig, McpServerConfig as McpServerConfig$1, Registry, Registry as McpRegistry, RegistrySnapshot, RegistrySubscriber } from "@electric-ax/agents-mcp";
 import { braveSearchTool } from "@electric-ax/agents-runtime/tools";
 
 //#region src/skills/types.d.ts
@@ -40,6 +41,8 @@ interface BuiltinAgentHandlerOptions {
   serveEndpoint?: string;
   workingDirectory?: string;
   streamFn?: StreamFn;
+  publicUrl?: string;
+  runtimeName?: string;
   createElectricTools?: (context: {
     entityUrl: string;
     entityType: string;
@@ -88,6 +91,30 @@ interface BuiltinAgentsServerOptions {
   workingDirectory?: string;
   mockStreamFn?: StreamFn;
   webhookPath?: string;
+  /** Invoked when an `authorizationCode` server needs user consent. */
+  openAuthorizeUrl?: (url: string, server: string) => void;
+  /**
+   * MCP servers contributed by the embedder. Merged with `mcp.json`
+   * when `loadProjectMcpConfig` is set; on name conflict `mcp.json`
+   * wins. `authorizationCode` servers are wired to `keychainPersistence`.
+   */
+  extraMcpServers?: ReadonlyArray<McpServerConfig$1>;
+  /** Invoked when applying MCP config fails. Errors are always logged. */
+  onConfigError?: (error: unknown) => void;
+  /**
+   * Base for OAuth redirect URIs — full URI is
+   * `<base>/oauth/callback/<server-name>`. Must be stable across
+   * restarts so DCR client info stays valid. The runtime never
+   * listens at this URI; the embedder intercepts the redirect.
+   * Defaults to the runtime's own listen URL.
+   */
+  mcpOAuthRedirectBase?: string;
+  /**
+   * Load `<workingDirectory>/mcp.json` (and watch it for changes).
+   * Off by default — stdio MCP servers can spawn local commands,
+   * so the embedder must opt in.
+   */
+  loadProjectMcpConfig?: boolean;
   createElectricTools?: (context: {
     entityUrl: string;
     entityType: string;
@@ -126,8 +153,15 @@ declare class BuiltinAgentsServer {
   private bootstrap;
   private _url;
   private publicBaseUrl;
+  private _mcpRegistry;
+  private mcpWatcherCloser;
+  private mcpToolProviderName;
+  private mcpApplyInFlight;
+  private mcpStopping;
   readonly options: BuiltinAgentsServerOptions;
   constructor(options: BuiltinAgentsServerOptions);
+  /** Embedded MCP registry. `null` until `start()` has run. */
+  get mcpRegistry(): Registry | null;
   get url(): string;
   get registeredBaseUrl(): string;
   start(): Promise<string>;
@@ -159,22 +193,50 @@ declare function runBuiltinAgentsEntrypoint({
   url: string;
 }>;
 
+//#endregion
+//#region src/model-catalog.d.ts
+type BuiltinModelProvider = AvailableProvider;
+interface BuiltinModelChoice {
+  provider: BuiltinModelProvider;
+  id: string;
+  label: string;
+  value: string;
+  reasoning: boolean;
+}
+interface BuiltinModelCatalog {
+  choices: Array<BuiltinModelChoice>;
+  defaultChoice: BuiltinModelChoice;
+}
+declare const REASONING_EFFORT_VALUES: readonly ["auto", "minimal", "low", "medium", "high"];
+type BuiltinReasoningEffort = (typeof REASONING_EFFORT_VALUES)[number];
+type ExplicitReasoningEffort = Exclude<BuiltinReasoningEffort, `auto`>;
+type BuiltinAgentModelConfig = Pick<AgentConfig, `model` | `provider` | `onPayload` | `getApiKey`> & {
+  reasoningEffort?: ExplicitReasoningEffort;
+};
+declare function resolveBuiltinModelConfig(catalog: BuiltinModelCatalog, args: Readonly<Record<string, unknown>>): BuiltinAgentModelConfig;
+
 //#endregion
 //#region src/agents/horton.d.ts
 declare const HORTON_MODEL = "claude-sonnet-4-6";
-declare function generateTitle(userMessage: string, llmCall?: (prompt: string) => Promise<string>): Promise<string>;
+declare function generateTitle(userMessage: string, llmCall: (prompt: string) => Promise<string>, onFallback?: (reason: string) => void): Promise<string>;
 declare function buildHortonSystemPrompt(workingDirectory: string, opts?: {
   hasDocsSupport?: boolean;
   hasSkills?: boolean;
   docsUrl?: string;
+  modelProvider?: string;
+  modelId?: string;
 }): string;
 declare function createHortonTools(workingDirectory: string, ctx: HandlerContext, readSet: Set<string>, opts?: {
   docsSearchTool?: AgentTool$1;
+  modelConfig?: ReturnType<typeof resolveBuiltinModelConfig>;
+  modelCatalog?: BuiltinModelCatalog;
+  logPrefix?: string;
 }): Array<AgentTool$1>;
 declare function registerHorton(registry: EntityRegistry, options: {
   workingDirectory: string;
   streamFn?: StreamFn;
   skillsRegistry?: SkillsRegistry | null;
+  modelCatalog: BuiltinModelCatalog;
   docsUrl?: string;
 }): Array<string>;
 
@@ -183,43 +245,14 @@ declare function registerHorton(registry: EntityRegistry, options: {
 declare function registerWorker(registry: EntityRegistry, options: {
   workingDirectory: string;
   streamFn?: StreamFn;
+  modelCatalog: BuiltinModelCatalog;
 }): void;
 
-//#endregion
-//#region src/agents/coding-session.d.ts
-/**
- * Abstraction over the claude/codex CLI. Default implementation spawns
- * the real binary; tests can inject a fake.
- *
- * `sessionId` is undefined for the first prompt on a fresh session —
- * the runner should then let the CLI generate its own id. For every
- * subsequent prompt, pass the id so the CLI resumes that conversation.
- */
-interface CodingSessionCliRunner {
-  run(opts: {
-    agent: CodingAgentType;
-    sessionId?: string;
-    cwd: string;
-    prompt: string;
-  }): Promise<{
-    exitCode: number;
-    stdout: string;
-    stderr: string;
-  }>;
-}
-interface RegisterCodingSessionOptions {
-  /** Working directory the CLI runs in when `args.cwd` is not provided. Defaults to `process.cwd()`. */
-  defaultWorkingDirectory?: string;
-  /** Override the CLI runner (for tests or alternate backends). */
-  cliRunner?: CodingSessionCliRunner;
-}
-declare function registerCodingSession(registry: EntityRegistry, options?: RegisterCodingSessionOptions): void;
-
 //#endregion
 //#region src/tools/spawn-worker.d.ts
-declare const WORKER_TOOL_NAMES: readonly ["bash", "read", "write", "edit", "brave_search", "fetch_url", "spawn_worker"];
+declare const WORKER_TOOL_NAMES: readonly ["bash", "read", "write", "edit", "web_search", "fetch_url", "spawn_worker"];
 type WorkerToolName = (typeof WORKER_TOOL_NAMES)[number];
-declare function createSpawnWorkerTool(ctx: HandlerContext): AgentTool$1;
+declare function createSpawnWorkerTool(ctx: HandlerContext, modelConfig?: BuiltinAgentModelConfig): AgentTool$1;
 
 //#endregion
 //#region src/docs/knowledge-base.d.ts
@@ -240,4 +273,4 @@ declare function createHortonDocsSupport(workingDirectory: string, opts?: {
 }): HortonDocsSupport | null;
 
 //#endregion
-export { AgentHandlerResult, BuiltinAgentHandlerOptions, BuiltinAgentsEntrypointOptions, BuiltinAgentsEntrypointServer, BuiltinAgentsServer, BuiltinAgentsServerOptions, CodingSessionCliRunner, DEFAULT_BUILTIN_AGENT_HANDLER_PATH, HORTON_MODEL, RegisterCodingSessionOptions, RunBuiltinAgentsEntrypointOptions, WORKER_TOOL_NAMES, WorkerToolName, braveSearchTool, buildHortonSystemPrompt, createAgentHandler, createBuiltinAgentHandler, createHortonDocsSupport, createHortonTools, createSpawnWorkerTool, generateTitle, registerAgentTypes, registerBuiltinAgentTypes, registerCodingSession, registerHorton, registerWorker, resolveBuiltinAgentsEntrypointOptions, runBuiltinAgentsEntrypoint };
+export { AgentHandlerResult, BuiltinAgentHandlerOptions, BuiltinAgentsEntrypointOptions, BuiltinAgentsEntrypointServer, BuiltinAgentsServer, BuiltinAgentsServerOptions, DEFAULT_BUILTIN_AGENT_HANDLER_PATH, HORTON_MODEL, McpConfig, McpListedEntry, McpRegistry, McpServerConfig, RegistrySnapshot, RegistrySubscriber, RunBuiltinAgentsEntrypointOptions, WORKER_TOOL_NAMES, WorkerToolName, braveSearchTool, buildHortonSystemPrompt, createAgentHandler, createBuiltinAgentHandler, createHortonDocsSupport, createHortonTools, createSpawnWorkerTool, generateTitle, registerAgentTypes, registerBuiltinAgentTypes, registerHorton, registerWorker, resolveBuiltinAgentsEntrypointOptions, runBuiltinAgentsEntrypoint };

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-import { AgentTool, CodingAgentType, EntityRegistry, EntityStreamDBWithActions, HandlerContext, RuntimeHandler, WakeEvent } from "@electric-ax/agents-runtime";
+import { AgentConfig, AgentTool, AvailableProvider, EntityRegistry, EntityStreamDBWithActions, HandlerContext, RuntimeHandler, WakeEvent } from "@electric-ax/agents-runtime";
+import { ChangeEvent } from "@durable-streams/state";
 import { braveSearchTool } from "@electric-ax/agents-runtime/tools";
+import { ListedEntry as McpListedEntry, McpConfig, McpServerConfig, McpServerConfig as McpServerConfig$1, Registry, Registry as McpRegistry, RegistrySnapshot, RegistrySubscriber } from "@electric-ax/agents-mcp";
 import { IncomingMessage, ServerResponse } from "node:http";
-import { ChangeEvent } from "@durable-streams/state";
 import { AgentTool as AgentTool$1, StreamFn } from "@mariozechner/pi-agent-core";
 
 //#region src/skills/types.d.ts
@@ -40,6 +41,8 @@ interface BuiltinAgentHandlerOptions {
   serveEndpoint?: string;
   workingDirectory?: string;
   streamFn?: StreamFn;
+  publicUrl?: string;
+  runtimeName?: string;
   createElectricTools?: (context: {
     entityUrl: string;
     entityType: string;
@@ -88,6 +91,30 @@ interface BuiltinAgentsServerOptions {
   workingDirectory?: string;
   mockStreamFn?: StreamFn;
   webhookPath?: string;
+  /** Invoked when an `authorizationCode` server needs user consent. */
+  openAuthorizeUrl?: (url: string, server: string) => void;
+  /**
+   * MCP servers contributed by the embedder. Merged with `mcp.json`
+   * when `loadProjectMcpConfig` is set; on name conflict `mcp.json`
+   * wins. `authorizationCode` servers are wired to `keychainPersistence`.
+   */
+  extraMcpServers?: ReadonlyArray<McpServerConfig$1>;
+  /** Invoked when applying MCP config fails. Errors are always logged. */
+  onConfigError?: (error: unknown) => void;
+  /**
+   * Base for OAuth redirect URIs — full URI is
+   * `<base>/oauth/callback/<server-name>`. Must be stable across
+   * restarts so DCR client info stays valid. The runtime never
+   * listens at this URI; the embedder intercepts the redirect.
+   * Defaults to the runtime's own listen URL.
+   */
+  mcpOAuthRedirectBase?: string;
+  /**
+   * Load `<workingDirectory>/mcp.json` (and watch it for changes).
+   * Off by default — stdio MCP servers can spawn local commands,
+   * so the embedder must opt in.
+   */
+  loadProjectMcpConfig?: boolean;
   createElectricTools?: (context: {
     entityUrl: string;
     entityType: string;
@@ -126,8 +153,15 @@ declare class BuiltinAgentsServer {
   private bootstrap;
   private _url;
   private publicBaseUrl;
+  private _mcpRegistry;
+  private mcpWatcherCloser;
+  private mcpToolProviderName;
+  private mcpApplyInFlight;
+  private mcpStopping;
   readonly options: BuiltinAgentsServerOptions;
   constructor(options: BuiltinAgentsServerOptions);
+  /** Embedded MCP registry. `null` until `start()` has run. */
+  get mcpRegistry(): Registry | null;
   get url(): string;
   get registeredBaseUrl(): string;
   start(): Promise<string>;
@@ -159,22 +193,50 @@ declare function runBuiltinAgentsEntrypoint({
   url: string;
 }>;
 
+//#endregion
+//#region src/model-catalog.d.ts
+type BuiltinModelProvider = AvailableProvider;
+interface BuiltinModelChoice {
+  provider: BuiltinModelProvider;
+  id: string;
+  label: string;
+  value: string;
+  reasoning: boolean;
+}
+interface BuiltinModelCatalog {
+  choices: Array<BuiltinModelChoice>;
+  defaultChoice: BuiltinModelChoice;
+}
+declare const REASONING_EFFORT_VALUES: readonly ["auto", "minimal", "low", "medium", "high"];
+type BuiltinReasoningEffort = (typeof REASONING_EFFORT_VALUES)[number];
+type ExplicitReasoningEffort = Exclude<BuiltinReasoningEffort, `auto`>;
+type BuiltinAgentModelConfig = Pick<AgentConfig, `model` | `provider` | `onPayload` | `getApiKey`> & {
+  reasoningEffort?: ExplicitReasoningEffort;
+};
+declare function resolveBuiltinModelConfig(catalog: BuiltinModelCatalog, args: Readonly<Record<string, unknown>>): BuiltinAgentModelConfig;
+
 //#endregion
 //#region src/agents/horton.d.ts
 declare const HORTON_MODEL = "claude-sonnet-4-6";
-declare function generateTitle(userMessage: string, llmCall?: (prompt: string) => Promise<string>): Promise<string>;
+declare function generateTitle(userMessage: string, llmCall: (prompt: string) => Promise<string>, onFallback?: (reason: string) => void): Promise<string>;
 declare function buildHortonSystemPrompt(workingDirectory: string, opts?: {
   hasDocsSupport?: boolean;
   hasSkills?: boolean;
   docsUrl?: string;
+  modelProvider?: string;
+  modelId?: string;
 }): string;
 declare function createHortonTools(workingDirectory: string, ctx: HandlerContext, readSet: Set<string>, opts?: {
   docsSearchTool?: AgentTool$1;
+  modelConfig?: ReturnType<typeof resolveBuiltinModelConfig>;
+  modelCatalog?: BuiltinModelCatalog;
+  logPrefix?: string;
 }): Array<AgentTool$1>;
 declare function registerHorton(registry: EntityRegistry, options: {
   workingDirectory: string;
   streamFn?: StreamFn;
   skillsRegistry?: SkillsRegistry | null;
+  modelCatalog: BuiltinModelCatalog;
   docsUrl?: string;
 }): Array<string>;
 
@@ -183,43 +245,14 @@ declare function registerHorton(registry: EntityRegistry, options: {
 declare function registerWorker(registry: EntityRegistry, options: {
   workingDirectory: string;
   streamFn?: StreamFn;
+  modelCatalog: BuiltinModelCatalog;
 }): void;
 
-//#endregion
-//#region src/agents/coding-session.d.ts
-/**
- * Abstraction over the claude/codex CLI. Default implementation spawns
- * the real binary; tests can inject a fake.
- *
- * `sessionId` is undefined for the first prompt on a fresh session —
- * the runner should then let the CLI generate its own id. For every
- * subsequent prompt, pass the id so the CLI resumes that conversation.
- */
-interface CodingSessionCliRunner {
-  run(opts: {
-    agent: CodingAgentType;
-    sessionId?: string;
-    cwd: string;
-    prompt: string;
-  }): Promise<{
-    exitCode: number;
-    stdout: string;
-    stderr: string;
-  }>;
-}
-interface RegisterCodingSessionOptions {
-  /** Working directory the CLI runs in when `args.cwd` is not provided. Defaults to `process.cwd()`. */
-  defaultWorkingDirectory?: string;
-  /** Override the CLI runner (for tests or alternate backends). */
-  cliRunner?: CodingSessionCliRunner;
-}
-declare function registerCodingSession(registry: EntityRegistry, options?: RegisterCodingSessionOptions): void;
-
 //#endregion
 //#region src/tools/spawn-worker.d.ts
-declare const WORKER_TOOL_NAMES: readonly ["bash", "read", "write", "edit", "brave_search", "fetch_url", "spawn_worker"];
+declare const WORKER_TOOL_NAMES: readonly ["bash", "read", "write", "edit", "web_search", "fetch_url", "spawn_worker"];
 type WorkerToolName = (typeof WORKER_TOOL_NAMES)[number];
-declare function createSpawnWorkerTool(ctx: HandlerContext): AgentTool$1;
+declare function createSpawnWorkerTool(ctx: HandlerContext, modelConfig?: BuiltinAgentModelConfig): AgentTool$1;
 
 //#endregion
 //#region src/docs/knowledge-base.d.ts
@@ -240,4 +273,4 @@ declare function createHortonDocsSupport(workingDirectory: string, opts?: {
 }): HortonDocsSupport | null;
 
 //#endregion
-export { AgentHandlerResult, BuiltinAgentHandlerOptions, BuiltinAgentsEntrypointOptions, BuiltinAgentsEntrypointServer, BuiltinAgentsServer, BuiltinAgentsServerOptions, CodingSessionCliRunner, DEFAULT_BUILTIN_AGENT_HANDLER_PATH, HORTON_MODEL, RegisterCodingSessionOptions, RunBuiltinAgentsEntrypointOptions, WORKER_TOOL_NAMES, WorkerToolName, braveSearchTool, buildHortonSystemPrompt, createAgentHandler, createBuiltinAgentHandler, createHortonDocsSupport, createHortonTools, createSpawnWorkerTool, generateTitle, registerAgentTypes, registerBuiltinAgentTypes, registerCodingSession, registerHorton, registerWorker, resolveBuiltinAgentsEntrypointOptions, runBuiltinAgentsEntrypoint };
+export { AgentHandlerResult, BuiltinAgentHandlerOptions, BuiltinAgentsEntrypointOptions, BuiltinAgentsEntrypointServer, BuiltinAgentsServer, BuiltinAgentsServerOptions, DEFAULT_BUILTIN_AGENT_HANDLER_PATH, HORTON_MODEL, McpConfig, McpListedEntry, McpRegistry, McpServerConfig, RegistrySnapshot, RegistrySubscriber, RunBuiltinAgentsEntrypointOptions, WORKER_TOOL_NAMES, WorkerToolName, braveSearchTool, buildHortonSystemPrompt, createAgentHandler, createBuiltinAgentHandler, createHortonDocsSupport, createHortonTools, createSpawnWorkerTool, generateTitle, registerAgentTypes, registerBuiltinAgentTypes, registerHorton, registerWorker, resolveBuiltinAgentsEntrypointOptions, runBuiltinAgentsEntrypoint };