@electric-ax/agents 0.2.4 → 0.4.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, DispatchPolicy, EntityRegistry, EntityStreamDBWithActions, HandlerContext, HeadersProvider, PullWakeRunnerConfig, 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,10 @@ interface BuiltinAgentHandlerOptions {
   serveEndpoint?: string;
   workingDirectory?: string;
   streamFn?: StreamFn;
+  publicUrl?: string;
+  runtimeName?: string;
+  serverHeaders?: HeadersProvider;
+  defaultDispatchPolicyForType?: (typeName: string) => DispatchPolicy | undefined;
   createElectricTools?: (context: {
     entityUrl: string;
     entityType: string;
@@ -82,12 +87,44 @@ declare const registerAgentTypes: typeof registerBuiltinAgentTypes;
 //#region src/server.d.ts
 interface BuiltinAgentsServerOptions {
   agentServerUrl: string;
-  baseUrl?: string;
-  port: number;
-  host?: string;
   workingDirectory?: string;
   mockStreamFn?: StreamFn;
-  webhookPath?: string;
+  /** Pull-wake runner configuration for built-in agents. */
+  pullWake: {
+    runnerId: string;
+    ownerUserId?: string;
+    label?: string;
+    registerRunner?: boolean;
+    headers?: PullWakeRunnerConfig[`headers`];
+    claimHeaders?: PullWakeRunnerConfig[`claimHeaders`];
+    claimTokenHeader?: PullWakeRunnerConfig[`claimTokenHeader`];
+    heartbeatIntervalMs?: PullWakeRunnerConfig[`heartbeatIntervalMs`];
+    leaseMs?: PullWakeRunnerConfig[`leaseMs`];
+  };
+  /** 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;
@@ -122,17 +159,20 @@ interface BuiltinAgentsServerOptions {
   }) => Array<AgentTool> | Promise<Array<AgentTool>>;
 }
 declare class BuiltinAgentsServer {
-  private server;
   private bootstrap;
-  private _url;
-  private publicBaseUrl;
+  private _mcpRegistry;
+  private mcpWatcherCloser;
+  private mcpToolProviderName;
+  private mcpApplyInFlight;
+  private mcpStopping;
+  private pullWakeRunner;
   readonly options: BuiltinAgentsServerOptions;
   constructor(options: BuiltinAgentsServerOptions);
-  get url(): string;
-  get registeredBaseUrl(): string;
+  /** Embedded MCP registry. `null` until `start()` has run. */
+  get mcpRegistry(): Registry | null;
   start(): Promise<string>;
   stop(): Promise<void>;
-  private handleRequest;
+  private registerPullWakeRunner;
 }
 
 //#endregion
@@ -159,22 +199,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 +251,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 +279,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,8 +1,9 @@
-import { AgentTool, CodingAgentType, EntityRegistry, EntityStreamDBWithActions, HandlerContext, RuntimeHandler, WakeEvent } from "@electric-ax/agents-runtime";
-import { braveSearchTool } from "@electric-ax/agents-runtime/tools";
-import { IncomingMessage, ServerResponse } from "node:http";
+import { AgentConfig, AgentTool, AvailableProvider, DispatchPolicy, EntityRegistry, EntityStreamDBWithActions, HandlerContext, HeadersProvider, PullWakeRunnerConfig, 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 { AgentTool as AgentTool$1, StreamFn } from "@mariozechner/pi-agent-core";
+import { IncomingMessage, ServerResponse } from "node:http";
 
 //#region src/skills/types.d.ts
 interface SkillMeta {
@@ -40,6 +41,10 @@ interface BuiltinAgentHandlerOptions {
   serveEndpoint?: string;
   workingDirectory?: string;
   streamFn?: StreamFn;
+  publicUrl?: string;
+  runtimeName?: string;
+  serverHeaders?: HeadersProvider;
+  defaultDispatchPolicyForType?: (typeName: string) => DispatchPolicy | undefined;
   createElectricTools?: (context: {
     entityUrl: string;
     entityType: string;
@@ -82,12 +87,44 @@ declare const registerAgentTypes: typeof registerBuiltinAgentTypes;
 //#region src/server.d.ts
 interface BuiltinAgentsServerOptions {
   agentServerUrl: string;
-  baseUrl?: string;
-  port: number;
-  host?: string;
   workingDirectory?: string;
   mockStreamFn?: StreamFn;
-  webhookPath?: string;
+  /** Pull-wake runner configuration for built-in agents. */
+  pullWake: {
+    runnerId: string;
+    ownerUserId?: string;
+    label?: string;
+    registerRunner?: boolean;
+    headers?: PullWakeRunnerConfig[`headers`];
+    claimHeaders?: PullWakeRunnerConfig[`claimHeaders`];
+    claimTokenHeader?: PullWakeRunnerConfig[`claimTokenHeader`];
+    heartbeatIntervalMs?: PullWakeRunnerConfig[`heartbeatIntervalMs`];
+    leaseMs?: PullWakeRunnerConfig[`leaseMs`];
+  };
+  /** 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;
@@ -122,17 +159,20 @@ interface BuiltinAgentsServerOptions {
   }) => Array<AgentTool> | Promise<Array<AgentTool>>;
 }
 declare class BuiltinAgentsServer {
-  private server;
   private bootstrap;
-  private _url;
-  private publicBaseUrl;
+  private _mcpRegistry;
+  private mcpWatcherCloser;
+  private mcpToolProviderName;
+  private mcpApplyInFlight;
+  private mcpStopping;
+  private pullWakeRunner;
   readonly options: BuiltinAgentsServerOptions;
   constructor(options: BuiltinAgentsServerOptions);
-  get url(): string;
-  get registeredBaseUrl(): string;
+  /** Embedded MCP registry. `null` until `start()` has run. */
+  get mcpRegistry(): Registry | null;
   start(): Promise<string>;
   stop(): Promise<void>;
-  private handleRequest;
+  private registerPullWakeRunner;
 }
 
 //#endregion
@@ -159,22 +199,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 +251,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 +279,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 };