jeopi-cli 16.2.14 → 16.2.17

package/dist/types/mcp/tool-bridge.d.ts

@@ -0,0 +1,95 @@
+/**
+ * MCP to CustomTool bridge.
+ *
+ * Converts MCP tool definitions to CustomTool format for the agent.
+ */
+import type { AgentToolUpdateCallback } from "jeopi-agent-core";
+import type { TSchema } from "jeopi-ai";
+import type { SourceMeta } from "../capability/types";
+import type { CustomTool, CustomToolContext, CustomToolResult, RenderResultOptions } from "../extensibility/custom-tools/types";
+import type { Theme } from "../modes/theme/theme";
+import type { OutputMeta } from "../tools/output-meta";
+import type { MCPContent, MCPServerConnection, MCPToolDefinition } from "./types";
+/** Reconnect callback: tears down stale connection, returns new one or null. */
+export type MCPReconnect = () => Promise<MCPServerConnection | null>;
+export declare function isRetriableConnectionError(error: unknown): boolean;
+/** Details included in MCP tool results for rendering */
+export interface MCPToolDetails {
+    /** Server name */
+    serverName: string;
+    /** Original MCP tool name */
+    mcpToolName: string;
+    /** Whether the call resulted in an error */
+    isError?: boolean;
+    /** Raw content from MCP response */
+    rawContent?: MCPContent[];
+    /** Provider ID (e.g., "claude", "mcp-json") */
+    provider?: string;
+    /** Provider display name (e.g., "Claude Code", "MCP Config") */
+    providerName?: string;
+    /** Structured output metadata (set by the spill wrapper when output is truncated to an artifact). */
+    meta?: OutputMeta;
+}
+export declare function createMCPToolName(serverName: string, toolName: string): string;
+/**
+ * Parse an MCP tool name back to server and tool components.
+ *
+ * Note: This returns the normalized tool name (with server prefix stripped).
+ * The original MCP tool name may have had the server name as a prefix.
+ */
+export declare function parseMCPToolName(name: string): {
+    serverName: string;
+    toolName: string;
+} | null;
+/**
+ * CustomTool wrapping an MCP tool with an active connection.
+ */
+export declare class MCPTool implements CustomTool<TSchema, MCPToolDetails> {
+    private connection;
+    private readonly tool;
+    private readonly reconnect?;
+    readonly name: string;
+    readonly label: string;
+    readonly description: string;
+    readonly parameters: TSchema;
+    /** Original MCP tool name (before normalization) */
+    readonly mcpToolName: string;
+    /** Server name */
+    readonly mcpServerName: string;
+    readonly approval: "write";
+    /** Render completed MCP calls with the result header replacing the pending call header. */
+    readonly mergeCallAndResult = true;
+    /** Create MCPTool instances for all tools from an MCP server connection */
+    static fromTools(connection: MCPServerConnection, tools: MCPToolDefinition[], reconnect?: MCPReconnect): MCPTool[];
+    constructor(connection: MCPServerConnection, tool: MCPToolDefinition, reconnect?: MCPReconnect | undefined);
+    renderCall(args: unknown, _options: RenderResultOptions, theme: Theme): import("jeopi-tui").Component;
+    renderResult(result: CustomToolResult<MCPToolDetails>, options: RenderResultOptions, theme: Theme, args?: unknown): import("jeopi-tui").Component;
+    execute(_toolCallId: string, params: unknown, _onUpdate: AgentToolUpdateCallback<MCPToolDetails> | undefined, _ctx: CustomToolContext, signal?: AbortSignal): Promise<CustomToolResult<MCPToolDetails>>;
+}
+/**
+ * CustomTool wrapping an MCP tool with deferred connection resolution.
+ */
+export declare class DeferredMCPTool implements CustomTool<TSchema, MCPToolDetails> {
+    #private;
+    private readonly serverName;
+    private readonly tool;
+    private readonly getConnection;
+    private readonly reconnect?;
+    readonly name: string;
+    readonly label: string;
+    readonly description: string;
+    readonly parameters: TSchema;
+    /** Original MCP tool name (before normalization) */
+    readonly mcpToolName: string;
+    /** Server name */
+    readonly mcpServerName: string;
+    readonly approval: "write";
+    /** Render completed MCP calls with the result header replacing the pending call header. */
+    readonly mergeCallAndResult = true;
+    /** Create DeferredMCPTool instances for all tools from an MCP server */
+    static fromTools(serverName: string, tools: MCPToolDefinition[], getConnection: () => Promise<MCPServerConnection>, source?: SourceMeta, reconnect?: MCPReconnect): DeferredMCPTool[];
+    constructor(serverName: string, tool: MCPToolDefinition, getConnection: () => Promise<MCPServerConnection>, source?: SourceMeta, reconnect?: MCPReconnect | undefined);
+    renderCall(args: unknown, _options: RenderResultOptions, theme: Theme): import("jeopi-tui").Component;
+    renderResult(result: CustomToolResult<MCPToolDetails>, options: RenderResultOptions, theme: Theme, args?: unknown): import("jeopi-tui").Component;
+    execute(_toolCallId: string, params: unknown, _onUpdate: AgentToolUpdateCallback<MCPToolDetails> | undefined, _ctx: CustomToolContext, signal?: AbortSignal): Promise<CustomToolResult<MCPToolDetails>>;
+}

package/dist/types/mcp/tool-cache.d.ts

@@ -0,0 +1,8 @@
+import type { AgentStorage } from "../session/agent-storage";
+import type { MCPServerConfig, MCPToolDefinition } from "./types";
+export declare class MCPToolCache {
+    private storage;
+    constructor(storage: AgentStorage);
+    get(serverName: string, config: MCPServerConfig): Promise<MCPToolDefinition[] | null>;
+    set(serverName: string, config: MCPServerConfig, tools: MCPToolDefinition[]): Promise<void>;
+}

package/dist/types/mcp/transports/http.d.ts

@@ -0,0 +1,45 @@
+import type { MCPHttpServerConfig, MCPRequestOptions, MCPSseServerConfig, MCPTransport } from "../../mcp/types";
+/**
+ * Best-effort startup deadline for the optional Streamable HTTP GET SSE listener.
+ *
+ * Returns `0` (disabled) when the operator has explicitly disabled MCP client-side
+ * timeouts via `timeout: 0` or `JEOPI_MCP_TIMEOUT_MS=0`, mirroring the rest of the
+ * MCP timeout surface. Otherwise caps the wait at one second and scales below
+ * short request timeouts so connect-time never exceeds the request budget.
+ */
+export declare function resolveSSEConnectTimeoutMs(configTimeout?: number): number;
+/**
+ * HTTP transport for MCP servers.
+ * Uses POST for requests, supports SSE responses.
+ */
+export declare class HttpTransport implements MCPTransport {
+    #private;
+    private config;
+    onClose?: () => void;
+    onError?: (error: Error) => void;
+    onNotification?: (method: string, params: unknown) => void;
+    onRequest?: (method: string, params: unknown) => Promise<unknown>;
+    /** Called on 401/403 to attempt token refresh. Returns updated headers or null. */
+    onAuthError?: () => Promise<Record<string, string> | null>;
+    constructor(config: MCPHttpServerConfig | MCPSseServerConfig);
+    get connected(): boolean;
+    get url(): string;
+    /**
+     * Mark transport as connected.
+     * HTTP doesn't need persistent connection, but we track state.
+     */
+    connect(): Promise<void>;
+    /**
+     * Start SSE listener for server-initiated messages.
+     * Resolves once the SSE connection is established (or fails/unsupported).
+     * Message reading continues in the background.
+     */
+    startSSEListener(): Promise<void>;
+    request<T = unknown>(method: string, params?: Record<string, unknown>, options?: MCPRequestOptions): Promise<T>;
+    notify(method: string, params?: Record<string, unknown>): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * Create and connect an HTTP transport.
+ */
+export declare function createHttpTransport(config: MCPHttpServerConfig | MCPSseServerConfig): Promise<HttpTransport>;

package/dist/types/mcp/transports/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * MCP transport exports.
+ */
+export * from "./http";
+export * from "./sse";
+export * from "./stdio";

package/dist/types/mcp/transports/sse.d.ts

@@ -0,0 +1,20 @@
+import type { MCPRequestOptions, MCPSseServerConfig, MCPTransport } from "../../mcp/types";
+/** Legacy MCP HTTP+SSE transport from protocol revision 2024-11-05. */
+export declare class LegacySseTransport implements MCPTransport {
+    #private;
+    onClose?: () => void;
+    onError?: (error: Error) => void;
+    onNotification?: (method: string, params: unknown) => void;
+    onRequest?: (method: string, params: unknown) => Promise<unknown>;
+    /** Called on 401/403 to attempt token refresh. Returns updated headers or null. */
+    onAuthError?: () => Promise<Record<string, string> | null>;
+    constructor(config: MCPSseServerConfig);
+    get connected(): boolean;
+    get url(): string;
+    connect(): Promise<void>;
+    request<T = unknown>(method: string, params?: Record<string, unknown>, options?: MCPRequestOptions): Promise<T>;
+    notify(method: string, params?: Record<string, unknown>): Promise<void>;
+    close(): Promise<void>;
+}
+/** Create and connect a legacy HTTP+SSE transport. */
+export declare function createSseTransport(config: MCPSseServerConfig): Promise<LegacySseTransport>;

package/dist/types/mcp/transports/stdio.d.ts

@@ -0,0 +1,108 @@
+/**
+ * MCP stdio transport.
+ *
+ * Implements JSON-RPC 2.0 over subprocess stdin/stdout.
+ * Messages are newline-delimited JSON.
+ */
+import type { MCPRequestOptions, MCPStdioServerConfig, MCPTransport } from "../../mcp/types";
+/** Subprocess argv and platform-derived spawn flags for an MCP stdio server. */
+export interface StdioSpawnCommand {
+    cmd: string[];
+    /**
+     * Hide the Windows console window for the direct child.
+     *
+     * Windows uses this only when the OMP host has no console to share. When
+     * the host is running inside a terminal, `windowsHide: true` maps to
+     * `CREATE_NO_WINDOW`, which strips that inheritable console from hidden
+     * `cmd.exe` / PowerShell wrapper chains. Their console grandchildren then
+     * allocate fresh visible conhost windows during startup or reconnects
+     * (#3567).
+     */
+    windowsHide?: boolean;
+    /**
+     * Run the subprocess in its own session.
+     *
+     * POSIX: `true`. Detach → `setsid`, so the MCP process tree has no
+     * controlling terminal and terminal job-control signals (Ctrl+Z SIGTSTP,
+     * background-read SIGTTIN) cannot stop stdio servers such as
+     * `chrome-devtools-mcp` and leave our read loop blocked on silent pipes.
+     *
+     * Windows: `false`. There is no SIGTSTP/SIGTTIN to escape, and Windows
+     * wrapper chains must stay in the OMP console session so nested console
+     * grandchildren keep stdout routed through our pipe (#3544).
+     */
+    detached: boolean;
+}
+/** Inputs used to resolve platform-specific stdio spawn behavior. */
+export interface ResolveStdioSpawnOptions {
+    cwd: string;
+    env: Record<string, string | undefined>;
+    hostHasInheritableConsole?: boolean;
+    platform?: NodeJS.Platform;
+}
+/**
+ * Resolve the subprocess argv used to launch an MCP stdio server.
+ *
+ * On Windows, our PATH/PATHEXT walk may return `null` for a bare command
+ * (e.g. `npx`) — `Bun.env.PATH` empty under a restricted parent process,
+ * UNC/network mounts that reject `fs.access`, locked-down shells. The
+ * legacy fallback handed `Bun.spawn` the bare name, but `CreateProcess`
+ * only appends `.exe` for extensionless names — `.cmd`/`.bat` are never
+ * tried, so `npx` (which exists only as `npx.cmd` on Windows) crashes the
+ * subprocess immediately. When the resolver can't pin the command down,
+ * route through `cmd.exe /d /s /c` so Windows's own PATHEXT lookup runs.
+ */
+export declare function resolveStdioSpawnCommand(config: MCPStdioServerConfig, options: ResolveStdioSpawnOptions): Promise<StdioSpawnCommand>;
+/** Minimal write surface of `Subprocess.stdin` we need for framed sends. */
+interface FrameSink {
+    write(chunk: string): unknown;
+    flush(): unknown;
+}
+/**
+ * Write a newline-delimited JSON-RPC frame to the subprocess's stdin sink,
+ * swallowing both synchronous throws and asynchronous rejections so the caller
+ * can decide how to react.
+ *
+ * Bun's `FileSink.write()`/`flush()` can fail two ways once the read end of the
+ * pipe has been closed by a subprocess that exited between read-loop ticks:
+ *   - a synchronous throw (most reliably observed on Windows), and
+ *   - a *rejected Promise* returned from `write()`/`flush()`, i.e. the EPIPE is
+ *     surfaced asynchronously (note the `processTicksAndRejections` frame in the
+ *     stack traces on #1710 and the follow-up report).
+ *
+ * A sibling `async` method's `try/catch` only catches the synchronous case; an
+ * un-awaited rejected Promise escapes as a fatal unhandled rejection. So we both
+ * catch the throw and neutralize any returned promise's rejection.
+ *
+ * Returns `true` when the frame was accepted synchronously, `false` when the
+ * sink threw — callers signal transport closure on `false`. An asynchronous
+ * failure cannot be reflected in the return value; it is neutralized here and
+ * the dead transport is detected by the read loop / request timeout instead.
+ */
+export declare function writeFrame(stdin: FrameSink, frame: string): boolean;
+/**
+ * Stdio transport for MCP servers.
+ * Spawns a subprocess and communicates via stdin/stdout.
+ */
+export declare class StdioTransport implements MCPTransport {
+    #private;
+    private config;
+    onClose?: () => void;
+    onError?: (error: Error) => void;
+    onNotification?: (method: string, params: unknown) => void;
+    onRequest?: (method: string, params: unknown) => Promise<unknown>;
+    constructor(config: MCPStdioServerConfig);
+    get connected(): boolean;
+    /**
+     * Start the subprocess and begin reading.
+     */
+    connect(): Promise<void>;
+    request<T = unknown>(method: string, params?: Record<string, unknown>, options?: MCPRequestOptions): Promise<T>;
+    notify(method: string, params?: Record<string, unknown>): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * Create and connect a stdio transport.
+ */
+export declare function createStdioTransport(config: MCPStdioServerConfig): Promise<StdioTransport>;
+export {};

package/dist/types/mcp/transports/stdio.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/mcp/types.d.ts

@@ -0,0 +1,340 @@
+/**
+ * MCP (Model Context Protocol) type definitions.
+ *
+ * Based on MCP specification 2025-03-26:
+ * https://modelcontextprotocol.io/specification/2025-03-26/
+ */
+import type { SourceMeta } from "../capability/types";
+export interface JsonRpcRequest {
+    jsonrpc: "2.0";
+    id: string | number;
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface JsonRpcNotification {
+    jsonrpc: "2.0";
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface JsonRpcResponse {
+    jsonrpc: "2.0";
+    id: string | number;
+    result?: unknown;
+    error?: JsonRpcError;
+}
+export interface JsonRpcError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+export type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcResponse;
+/** Authentication configuration for MCP servers */
+export interface MCPAuthConfig {
+    /** Authentication type */
+    type: "oauth" | "apikey";
+    /** Credential ID for OAuth (references agent.db) */
+    credentialId?: string;
+    /** Token endpoint URL — persisted for proactive token refresh */
+    tokenUrl?: string;
+    /** Client ID — persisted for token refresh */
+    clientId?: string;
+    /** Client secret — persisted for token refresh */
+    clientSecret?: string;
+    /** MCP resource URI — persisted for OAuth resource indicators during refresh */
+    resource?: string;
+}
+/** Base server config with shared options */
+interface MCPServerConfigBase {
+    /** Whether this server is enabled (default: true) */
+    enabled?: boolean;
+    /** MCP request timeout in milliseconds (default: 30000, 0 to disable) */
+    timeout?: number;
+    /** Authentication configuration (optional) */
+    auth?: MCPAuthConfig;
+    /** OAuth configuration for servers requiring explicit client credentials */
+    oauth?: {
+        clientId?: string;
+        clientSecret?: string;
+        redirectUri?: string;
+        callbackPort?: number;
+        callbackPath?: string;
+        /** `prompt` param for the authorization request (default "consent"; "" to omit) */
+        prompt?: string;
+    };
+}
+/** Stdio server configuration */
+export interface MCPStdioServerConfig extends MCPServerConfigBase {
+    type?: "stdio";
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+}
+/** HTTP server configuration (Streamable HTTP transport) */
+export interface MCPHttpServerConfig extends MCPServerConfigBase {
+    type: "http";
+    url: string;
+    headers?: Record<string, string>;
+}
+/** SSE server configuration (deprecated, use HTTP) */
+export interface MCPSseServerConfig extends MCPServerConfigBase {
+    type: "sse";
+    url: string;
+    headers?: Record<string, string>;
+}
+export type MCPServerConfig = MCPStdioServerConfig | MCPHttpServerConfig | MCPSseServerConfig;
+export declare const MCP_CONFIG_SCHEMA_URL = "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json";
+/** Root mcp.json/.mcp.json file structure */
+export interface MCPConfigFile {
+    $schema?: string;
+    mcpServers?: Record<string, MCPServerConfig>;
+    /** Names to hide regardless of any source `enabled` flag. Highest precedence. */
+    disabledServers?: string[];
+    /** Names to force-enable when a non-writable source reports `enabled: false`. */
+    enabledServers?: string[];
+}
+/** MCP implementation info */
+export interface MCPImplementation {
+    name: string;
+    version: string;
+}
+/** MCP client capabilities */
+export interface MCPClientCapabilities {
+    roots?: {
+        listChanged?: boolean;
+    };
+    sampling?: Record<string, never>;
+    experimental?: Record<string, unknown>;
+}
+/** MCP server capabilities */
+export interface MCPServerCapabilities {
+    tools?: {
+        listChanged?: boolean;
+    };
+    resources?: {
+        subscribe?: boolean;
+        listChanged?: boolean;
+    };
+    prompts?: {
+        listChanged?: boolean;
+    };
+    logging?: Record<string, never>;
+    experimental?: Record<string, unknown>;
+}
+/** Initialize request params */
+export interface MCPInitializeParams {
+    protocolVersion: string;
+    capabilities: MCPClientCapabilities;
+    clientInfo: MCPImplementation;
+}
+/** Initialize response result */
+export interface MCPInitializeResult {
+    protocolVersion: string;
+    capabilities: MCPServerCapabilities;
+    serverInfo: MCPImplementation;
+    instructions?: string;
+}
+/** MCP tool definition */
+export interface MCPToolDefinition {
+    name: string;
+    description?: string;
+    inputSchema: {
+        type: "object";
+        properties?: Record<string, unknown>;
+        required?: string[];
+        [key: string]: unknown;
+    };
+}
+/** tools/list response */
+export interface MCPToolsListResult {
+    tools: MCPToolDefinition[];
+    nextCursor?: string;
+}
+/** tools/call params */
+export interface MCPToolCallParams {
+    name: string;
+    arguments?: Record<string, unknown>;
+}
+/** Content types in tool results */
+export interface MCPTextContent {
+    type: "text";
+    text: string;
+}
+export interface MCPImageContent {
+    type: "image";
+    data: string;
+    mimeType: string;
+}
+export interface MCPResourceContent {
+    type: "resource";
+    resource: {
+        uri: string;
+        mimeType?: string;
+        text?: string;
+        blob?: string;
+    };
+}
+export type MCPContent = MCPTextContent | MCPImageContent | MCPResourceContent;
+/** tools/call response */
+export interface MCPToolCallResult {
+    content: MCPContent[];
+    isError?: boolean;
+}
+export interface MCPRequestOptions {
+    /** Abort signal (e.g. Escape-to-interrupt) */
+    signal?: AbortSignal;
+}
+/** Transport interface - abstracts stdio/http */
+export interface MCPTransport {
+    /** Send a request and wait for response */
+    request<T = unknown>(method: string, params?: Record<string, unknown>, options?: MCPRequestOptions): Promise<T>;
+    /** Send a notification (no response expected) */
+    notify(method: string, params?: Record<string, unknown>): Promise<void>;
+    /** Close the transport */
+    close(): Promise<void>;
+    /** Whether the transport is connected */
+    readonly connected: boolean;
+    /** Event handlers */
+    onClose?: () => void;
+    onError?: (error: Error) => void;
+    onNotification?: (method: string, params: unknown) => void;
+    /** Handler for server-to-client requests (e.g. roots/list). Returns result or throws a JsonRpcError. */
+    onRequest?: (method: string, params: unknown) => Promise<unknown>;
+}
+/** Transport factory function */
+export type TransportFactory = (config: MCPServerConfig) => Promise<MCPTransport>;
+/** Connected MCP server state */
+export interface MCPServerConnection {
+    /** Server name from config */
+    name: string;
+    /** Original config */
+    config: MCPServerConfig;
+    /** Transport instance */
+    transport: MCPTransport;
+    /** Server info from initialize */
+    serverInfo: MCPImplementation;
+    /** Server capabilities */
+    capabilities: MCPServerCapabilities;
+    /** Cached tools (populated on demand) */
+    tools?: MCPToolDefinition[];
+    /** Source metadata (for display) */
+    _source?: SourceMeta;
+    /** Cached resources (populated on demand) */
+    resources?: MCPResource[];
+    /** Cached resource templates (populated on demand) */
+    resourceTemplates?: MCPResourceTemplate[];
+    /** Server instructions from initialize */
+    instructions?: string;
+    /** Cached prompts (populated on demand) */
+    prompts?: MCPPrompt[];
+}
+/** MCP tool with server context */
+export interface MCPToolWithServer {
+    server: MCPServerConnection;
+    tool: MCPToolDefinition;
+}
+/** Annotations for resources, templates, and content blocks */
+export interface MCPAnnotations {
+    audience?: ("user" | "assistant")[];
+    priority?: number;
+    lastModified?: string;
+}
+/** A concrete resource exposed by an MCP server */
+export interface MCPResource {
+    uri: string;
+    name: string;
+    title?: string;
+    description?: string;
+    mimeType?: string;
+    size?: number;
+    annotations?: MCPAnnotations;
+}
+/** A parameterized resource template (RFC 6570 URI template) */
+export interface MCPResourceTemplate {
+    uriTemplate: string;
+    name: string;
+    title?: string;
+    description?: string;
+    mimeType?: string;
+    annotations?: MCPAnnotations;
+}
+/** Result of resources/list */
+export interface MCPResourcesListResult {
+    resources: MCPResource[];
+    nextCursor?: string;
+}
+/** Result of resources/templates/list */
+export interface MCPResourceTemplatesListResult {
+    resourceTemplates: MCPResourceTemplate[];
+    nextCursor?: string;
+}
+/** A single content item from resources/read */
+export interface MCPResourceContentItem {
+    uri: string;
+    mimeType?: string;
+    text?: string;
+    blob?: string;
+}
+/** Result of resources/read */
+export interface MCPResourceReadResult {
+    contents: MCPResourceContentItem[];
+}
+/** Params for resources/read */
+export interface MCPResourceReadParams {
+    uri: string;
+}
+/** Params for resources/subscribe and resources/unsubscribe */
+export interface MCPResourceSubscribeParams {
+    uri: string;
+}
+/** An argument definition for an MCP prompt */
+export interface MCPPromptArgument {
+    name: string;
+    description?: string;
+    required?: boolean;
+}
+/** A prompt definition exposed by an MCP server */
+export interface MCPPrompt {
+    name: string;
+    title?: string;
+    description?: string;
+    arguments?: MCPPromptArgument[];
+}
+/** Result of prompts/list */
+export interface MCPPromptsListResult {
+    prompts: MCPPrompt[];
+    nextCursor?: string;
+}
+/** Audio content in prompt messages */
+export interface MCPAudioContent {
+    type: "audio";
+    data: string;
+    mimeType: string;
+}
+/** Content type union for prompt messages */
+export type MCPPromptContent = MCPTextContent | MCPImageContent | MCPAudioContent | MCPResourceContent;
+/** A single message in a prompt result */
+export interface MCPPromptMessage {
+    role: "user" | "assistant";
+    content: MCPPromptContent | MCPPromptContent[];
+}
+/** Params for prompts/get */
+export interface MCPGetPromptParams {
+    name: string;
+    arguments?: Record<string, string>;
+}
+/** Result of prompts/get */
+export interface MCPGetPromptResult {
+    description?: string;
+    messages: MCPPromptMessage[];
+}
+/** MCP server notification method names */
+export declare const MCPNotificationMethods: {
+    readonly TOOLS_LIST_CHANGED: "notifications/tools/list_changed";
+    readonly RESOURCES_LIST_CHANGED: "notifications/resources/list_changed";
+    readonly RESOURCES_UPDATED: "notifications/resources/updated";
+    readonly PROMPTS_LIST_CHANGED: "notifications/prompts/list_changed";
+};
+/** Extract a JsonRpcError from a thrown value. Preserves `.code` and `.message` from Error instances or plain objects. */
+export declare function toJsonRpcError(error: unknown): JsonRpcError;
+export {};

package/dist/types/memories/index.d.ts

@@ -0,0 +1,54 @@
+import type { ModelRegistry } from "../config/model-registry";
+import type { Settings } from "../config/settings";
+import type { MemoryBackendSaveInput, MemoryBackendSaveResult } from "../memory-backend/types";
+import type { AgentSession } from "../session/agent-session";
+/**
+ * Start the background memory startup pipeline.
+ *
+ * Skips for ephemeral sessions, subagent sessions, disabled settings, or DB failures.
+ */
+export declare function startMemoryStartupTask(options: {
+    session: AgentSession;
+    settings: Settings;
+    modelRegistry: ModelRegistry;
+    agentDir: string;
+    taskDepth: number;
+}): void;
+interface MemoryInstructionSession {
+    sessionManager: Pick<AgentSession["sessionManager"], "getSessionFile">;
+}
+/**
+ * Drop the per-session memory instruction snapshot after explicit memory state
+ * changes that must affect the active conversation immediately, such as
+ * `/memory clear`.
+ */
+export declare function clearMemoryToolDeveloperInstructionsCache(session: MemoryInstructionSession | undefined): void;
+/**
+ * Refresh the active session's consolidated-memory snapshot after startup maintenance.
+ *
+ * Startup may finish after the first prompt build and write `memory_summary.md`;
+ * the active session should see that summary. It must not reread `learned.md`,
+ * because a `learn` call racing with startup belongs to the next session's
+ * memory prompt, not the active prompt-cache prefix.
+ */
+export declare function refreshMemoryToolDeveloperInstructionsCacheAfterStartup(session: MemoryInstructionSession, agentDir: string, settings: Settings): Promise<void>;
+/**
+ * Build memory usage instructions for prompt injection.
+ */
+export declare function buildMemoryToolDeveloperInstructions(agentDir: string, settings: Settings, session?: MemoryInstructionSession): Promise<string | undefined>;
+/**
+ * Clear all persisted memory state and generated artifacts.
+ */
+export declare function clearMemoryData(agentDir: string, cwd: string): Promise<void>;
+/**
+ * Force-enqueue global consolidation maintenance work.
+ */
+export declare function enqueueMemoryConsolidation(agentDir: string, cwd: string, sourceUpdatedAt?: number): void;
+export declare function getMemoryRoot(agentDir: string, cwd: string): string;
+/**
+ * Append one lesson to the project's `learned.md` (newest-first, deduped,
+ * capped, secret-redacted, injection-neutralized). The file backs the `learn`
+ * tool when `memory.backend` is `local`.
+ */
+export declare function saveLearnedLesson(agentDir: string, cwd: string, input: MemoryBackendSaveInput): Promise<MemoryBackendSaveResult>;
+export {};