dsh-agy-cli 0.0.0-stage → 0.12.1

package/lib/mcp/bridge.js

@@ -0,0 +1,295 @@
+/**
+ * The runtime half of the MCP bridge.
+ *
+ * `agy-registration.ts` owns the AGY config-file side (write on activate,
+ * remove on dispose); this module owns the live half: the projected tool set,
+ * the loopback HTTP endpoint on the host's `webServer` carrier, and the
+ * `tools/call` round-trip back into the DSH tool pipeline.
+ *
+ * One deliberate asymmetry: listing tools is dynamic (the DSH registry can
+ * change between turns), while execution always goes through
+ * `tools.execute()` so the host's guard chain and approval service see every
+ * call. The call carries the owning session's live Agent, resolved through
+ * `sessionController.resolveAgent()`, because the DSH approval service denies
+ * any call that has no agent to route through.
+ */
+import { randomUUID } from 'node:crypto';
+import { mountMcpEndpoint } from './endpoint.js';
+import { agyConfigRoot, agySettingsRoot, registerAgyMcpServer, unregisterAgyMcpServer, AGY_MCP_SERVER_NAME, } from './agy-registration.js';
+import { projectDshTools, validateToolArguments, NEVER_PROJECTED_TOOLS, } from './tool-projection.js';
+const INSTRUCTIONS = [
+    'These tools are executed by the DSH host, not by this environment.',
+    'Call a tool by its name; the DSH host validates arguments, applies its own',
+    'permission policy, and returns the result. A result with isError=true means',
+    'the host refused or failed the call — report it instead of retrying blindly.',
+].join(' ');
+function textOf(block) {
+    if (typeof block !== 'object' || block === null)
+        return undefined;
+    const record = block;
+    if (record.type !== 'text' || typeof record.text !== 'string')
+        return undefined;
+    return record.text;
+}
+function resultToCallResult(result) {
+    if (result.isError) {
+        const message = typeof result.error?.message === 'string' ? result.error.message : 'tool execution failed';
+        const detail = Array.isArray(result.content)
+            ? result.content.map(textOf).filter((part) => part !== undefined).join('\n')
+            : '';
+        return { content: [{ type: 'text', text: detail.length > 0 ? `${message}\n${detail}` : message }], isError: true };
+    }
+    const blocks = [];
+    if (Array.isArray(result.content)) {
+        for (const block of result.content) {
+            const text = textOf(block);
+            blocks.push({ type: 'text', text: text ?? JSON.stringify(block) });
+        }
+    }
+    if (blocks.length === 0) {
+        blocks.push({ type: 'text', text: result.value === undefined ? '' : JSON.stringify(result.value) });
+    }
+    return { content: blocks, isError: false };
+}
+/**
+ * Bring the bridge up. Every failure mode resolves to `active: false` with a
+ * reason instead of throwing, so the provider can fall back to the prompt
+ * contract path when the carrier or the tool registry is not available.
+ */
+export async function startDshMcpBridge(options) {
+    const inactive = (reason) => {
+        options.logger?.(`dsh mcp bridge inactive: ${reason}`);
+        return {
+            active: false,
+            inactiveReason: reason,
+            endpoint: undefined,
+            url: undefined,
+            setSession: () => { },
+            dispose: async () => { },
+        };
+    };
+    if (options.webServer === undefined || typeof options.webServer.register !== 'function') {
+        return inactive('host webServer service is unavailable');
+    }
+    if (typeof options.tools?.schemas !== 'function' || typeof options.tools?.execute !== 'function') {
+        return inactive('host tools service is unavailable');
+    }
+    let endpoint;
+    try {
+        // Project lazily on every `tools/list`: the bridge starts during plugin
+        // load, but the file, shell, and web tools only join `ctx.tools` once the
+        // agent presets and the remaining services finish mounting. Snapshotting
+        // here froze a host that had 18 tools and never exposed the rest.
+        if (projectDshTools(options.tools, {
+            ...(options.toolAllowlist === undefined ? {} : { allowlist: options.toolAllowlist }),
+        }).tools.length === 0) {
+            return inactive('host tools service exposed no tools');
+        }
+        endpoint = mountMcpEndpoint(options.webServer, {
+            serverName: AGY_MCP_SERVER_NAME,
+            serverVersion: options.serverVersion,
+            instructions: INSTRUCTIONS,
+            listTools: async (sessionHandle) => {
+                const agent = await agentOf(options, sessionHandle);
+                const projection = projectVisibleTools(options, agent);
+                const dropped = projection.excluded.filter(name => !NEVER_PROJECTED_TOOLS.has(name));
+                options.logger?.(`dsh mcp bridge: listTools session="${sessionHandle}" agent=${agent === undefined ? 'none' : 'resolved'} tools=${projection.tools.length}${dropped.length === 0 ? '' : ` dropped=${dropped.join(',')}`}`);
+                return projection.tools;
+            },
+            callTool: (sessionHandle, name, args) => executeDshTool(options, sessionHandle, name, args),
+            ...(options.logger === undefined ? {} : { logger: options.logger }),
+        });
+    }
+    catch (error) {
+        return inactive(`endpoint mount failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (endpoint.url === undefined) {
+        endpoint.dispose();
+        return inactive('host webServer has not reported a listening port');
+    }
+    try {
+        await registerAgyMcpServer({
+            url: endpoint.url,
+            token: endpoint.token,
+            // No tool list travels here on purpose: the allow rule this bridge
+            // needs is the server-wide wildcard `mcp(dsh/*)`, so a DSH tool that
+            // appears later is covered the moment it shows up in `tools/list`
+            // without rewriting the AGY settings file. The per-turn projection in
+            // `listTools` is the scoped one that matters.
+        }, {
+            ...(options.agyConfigRoot === undefined ? {} : { configRoot: options.agyConfigRoot }),
+            ...(options.agySettingsRoot === undefined ? {} : { settingsRoot: options.agySettingsRoot }),
+            ...(options.logger === undefined ? {} : { logger: options.logger }),
+        });
+    }
+    catch (error) {
+        endpoint.dispose();
+        return inactive(`AGY mcp_config.json update failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return {
+        active: true,
+        inactiveReason: undefined,
+        endpoint,
+        url: endpoint.url,
+        setSession: handle => endpoint.setSession(handle),
+        dispose: async () => {
+            endpoint.dispose();
+            await unregisterAgyMcpServer({
+                ...(options.agyConfigRoot === undefined ? {} : { configRoot: options.agyConfigRoot }),
+                ...(options.agySettingsRoot === undefined ? {} : { settingsRoot: options.agySettingsRoot }),
+                ...(options.logger === undefined ? {} : { logger: options.logger }),
+            }).catch(() => { });
+        },
+    };
+}
+/**
+ * Resolve the live Agent for the session this bridge currently serves.
+ *
+ * The adapter re-points the endpoint at the DSH session before every AGY turn
+ * (see the `setSession` call in the provider), and that handle survives across
+ * turns, so a direct lookup is enough. Getting the Agent matters twice over: the
+ * approval service denies any execution with no agent to route through, and the
+ * tool registry answers a *scoped* query with the agent-plane tools (file and
+ * shell) that its global view does not contain.
+ *
+ * A failure to resolve is reported through the bridge logger instead of being
+ * swallowed: "the session has no agent" and "the lookup threw" look identical
+ * from the outside, and that ambiguity is what made this bug cost a restart.
+ */
+async function agentOf(options, sessionHandle) {
+    // The lookup reads a Cordis service that a sibling bundle mounts later;
+    // cordis throws on property access while it is not mounted. Degrade to the
+    // static controller instead of failing every MCP request with a 500.
+    let controller;
+    try {
+        controller = options.sessionControllerLookup?.();
+    }
+    catch {
+        controller = undefined;
+    }
+    controller ??= options.sessionController;
+    if (controller === undefined) {
+        options.logger?.('dsh mcp bridge: the host sessionController service is unavailable');
+        return undefined;
+    }
+    if (sessionHandle.length === 0)
+        return undefined;
+    const resolved = await controller.resolveAgent(sessionHandle).catch((error) => {
+        const rejection = subagentRejectionIn(error);
+        options.logger?.(rejection === undefined
+            ? `dsh mcp bridge: resolveAgent("${sessionHandle}") threw ${String(error)}`
+            : `dsh mcp bridge: session "${sessionHandle}" is owned by subagent routing (${rejection}); the host refuses an agent handle for a child session by design, so this turn sees the global tool view`);
+        return undefined;
+    });
+    const agent = agentIn(resolved);
+    if (agent === undefined) {
+        options.logger?.(`dsh mcp bridge: no agent resolved for session "${sessionHandle}"`);
+    }
+    return agent;
+}
+/**
+ * Read the host's subagent-ownership rejection out of a thrown value.
+ *
+ * `sessionController.resolveAgent()` answers `RemoteError('session/agent-busy')`
+ * with `reason: 'use subagent delivery for this child session'` for any session
+ * whose header carries `origin: 'subagent'` — the host deliberately refuses to
+ * hand out an agent handle for a child session. That is a designed boundary, not
+ * a bridge defect, so the log says so instead of leaving a bare
+ * "no agent resolved" line that reads like a bug every time a subagent runs.
+ */
+function subagentRejectionIn(error) {
+    if (typeof error !== 'object' || error === null)
+        return undefined;
+    const record = error;
+    const details = typeof record.details === 'object' && record.details !== null
+        ? record.details
+        : undefined;
+    const reason = typeof details?.reason === 'string' ? details.reason : undefined;
+    if (reason !== undefined && /subagent delivery/i.test(reason))
+        return reason;
+    const code = typeof record.code === 'string' ? record.code : undefined;
+    const message = typeof record.message === 'string' ? record.message : undefined;
+    if (code === 'session/agent-busy' || (message !== undefined && /subagent routing/i.test(message))) {
+        return message ?? code ?? 'session/agent-busy';
+    }
+    return undefined;
+}
+function agentIn(resolved) {
+    if (resolved === undefined || resolved === null)
+        return undefined;
+    // The host's controller already unwraps: `sessionController.resolveAgent()`
+    // returns the Agent itself (it throws `ApiSessionAgentResult.error` instead of
+    // handing back a wrapper). Older and mocked shapes carry `{ agent }`, so accept
+    // both — but never mistake a thrown-error wrapper for a live agent.
+    if (typeof resolved === 'object') {
+        const record = resolved;
+        if ('agent' in record)
+            return record.agent;
+        // A rejection wrapper is not an agent; the host normally throws instead of
+        // returning one, but an older build may hand it back as a value.
+        if ('error' in record)
+            return undefined;
+    }
+    return resolved;
+}
+async function executeDshTool(options, sessionHandle, name, args) {
+    // Bridge-level gates first, independent of agent resolution: a tool the
+    // projection layer refuses to show must never execute through this bridge.
+    // Without this, a session whose agent could not be resolved (subagent
+    // routing, controller not mounted) degenerates to the global view, and a
+    // never-projected or allowlisted-out name would reach `tools.execute`
+    // directly — bypassing the promise tool-projection.ts makes.
+    if (NEVER_PROJECTED_TOOLS.has(name)) {
+        return { content: [{ type: 'text', text: `unknown tool "${name}"` }], isError: true };
+    }
+    if (options.toolAllowlist !== undefined && options.toolAllowlist.length > 0
+        && !options.toolAllowlist.includes(name)) {
+        return { content: [{ type: 'text', text: `unknown tool "${name}"` }], isError: true };
+    }
+    // No resolvable agent means fail closed, never silently open: the call still
+    // goes through `tools.execute()` so the host guard chain sees it, but the host
+    // itself decides what an unscoped call may do.
+    const agent = await agentOf(options, sessionHandle);
+    const projected = projectVisibleTools(options, agent).tools;
+    const descriptor = projected.find(entry => entry.name === name);
+    if (descriptor === undefined) {
+        // Only assert "unknown tool" when the projection is the one AGY was shown.
+        // With no resolvable agent the scoped list degenerates to the global view,
+        // so a legitimate file tool can be missing from it; that call still has to
+        // reach the host, which denies it on its own terms instead of us inventing a
+        // rejection for a tool we merely failed to see.
+        if (agent !== undefined) {
+            return { content: [{ type: 'text', text: `unknown tool "${name}"` }], isError: true };
+        }
+    }
+    else {
+        const problems = validateToolArguments(descriptor.inputSchema, args);
+        if (problems.length > 0) {
+            // Wording mirrors the host's own rejection so AGY sees one consistent
+            // failure shape whether the bridge or DSH catches the call.
+            return { content: [{ type: 'text', text: `invalid arguments: ${problems.join('; ')}` }], isError: true };
+        }
+    }
+    const controller = new AbortController();
+    const result = await options.tools.execute({
+        callId: randomUUID(),
+        name,
+        arguments: args,
+        ...(agent === undefined ? {} : { agent }),
+        signal: controller.signal,
+    });
+    return resultToCallResult(result);
+}
+/**
+ * The same projection `tools/list` advertises, used to pre-check a call.
+ * A registry failure yields an empty list, which reads as "unknown tool" —
+ * the correct fail-closed direction for a bridge that cannot see what it runs.
+ */
+function projectVisibleTools(options, agent) {
+    return projectDshTools(options.tools, {
+        ...(options.toolAllowlist === undefined ? {} : { allowlist: options.toolAllowlist }),
+        scope: agent,
+    });
+}
+export { AGY_MCP_SERVER_NAME, agyConfigRoot, agySettingsRoot };
+//# sourceMappingURL=bridge.js.map

package/lib/mcp/endpoint.d.ts

@@ -0,0 +1,41 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type McpCallResult, type McpToolDescriptor } from './protocol.js';
+/** The host's HTTP carrier service (`ctx.webServer`). */
+export interface DshWebServerLike {
+    /** The listening port; `undefined` before the carrier finishes listening. */
+    readonly port?: number;
+    readonly host?: string;
+    register(route: DshWebRoute): () => void;
+}
+export interface DshWebRoute {
+    readonly kind: 'exact' | 'prefix';
+    readonly path: string;
+    readonly handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+}
+export interface McpEndpointOptions {
+    readonly serverName: string;
+    readonly serverVersion: string;
+    readonly instructions: string;
+    readonly listTools: (sessionId: string) => Promise<readonly McpToolDescriptor[]>;
+    readonly callTool: (sessionId: string, name: string, args: Record<string, unknown>) => Promise<McpCallResult>;
+    readonly logger?: (message: string) => void;
+}
+export interface McpEndpoint {
+    /** Full loopback URL including the secret path segment, or undefined if the
+     *  carrier has not reported a port yet. */
+    readonly url: string | undefined;
+    /** Bearer token AGY must send. */
+    readonly token: string;
+    /** Point the endpoint at the DSH session the next AGY turn belongs to. */
+    readonly setSession: (sessionId: string) => void;
+    readonly dispose: () => void;
+}
+/** Loopback-only, shared with the settings panel routes. */
+export declare function isLoopback(address: string | undefined): boolean;
+/**
+ * Claim one MCP route on the host carrier. The returned `dispose` releases the
+ * route; callers must invoke it from an effect so a plugin reload cannot leak
+ * the registration.
+ */
+export declare function mountMcpEndpoint(webServer: DshWebServerLike, options: McpEndpointOptions): McpEndpoint;
+//# sourceMappingURL=endpoint.d.ts.map

package/lib/mcp/endpoint.js

@@ -0,0 +1,142 @@
+/**
+ * The MCP endpoint AGY connects to.
+ *
+ * Mounted on the host's existing HTTP carrier (`ctx.webServer`) rather than a
+ * private `node:http` listener: the carrier already owns the loopback bind, the
+ * port and the TLS story, and route registration is scoped to the plugin fiber
+ * so disabling the plugin removes the endpoint.
+ *
+ * Security model, in one place:
+ * - the route is claimed under a random path segment, so the URL itself is not
+ *   guessable;
+ * - every request must carry the random bearer token minted at mount time;
+ * - only `127.0.0.1`/`::1` peers are served, so a forwarded or reverse-proxied
+ *   port cannot reach the endpoint even if the token leaks;
+ * - only POST is served;
+ * - DSH tool execution still passes the normal tool pipeline, so the host's own
+ *   approval and guard rules decide what actually runs.
+ */
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { encodeMcpFrame, McpServerSession, } from './protocol.js';
+const MAX_BODY_BYTES = 4 * 1024 * 1024;
+/** Loopback-only, shared with the settings panel routes. */
+export function isLoopback(address) {
+    if (address === undefined)
+        return false;
+    return address === '127.0.0.1'
+        || address === '::1'
+        || address === '::ffff:127.0.0.1';
+}
+function constantTimeEquals(left, right) {
+    const a = Buffer.from(left, 'utf8');
+    const b = Buffer.from(right, 'utf8');
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
+async function readBody(req) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of req) {
+        const buffer = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk;
+        total += buffer.length;
+        if (total > MAX_BODY_BYTES)
+            throw new Error('MCP request body exceeds the bounded limit');
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+function send(res, status, body, contentType) {
+    res.writeHead(status, {
+        'content-type': contentType,
+        'content-length': Buffer.byteLength(body, 'utf8'),
+        'cache-control': 'no-store',
+    });
+    res.end(body);
+}
+/**
+ * Claim one MCP route on the host carrier. The returned `dispose` releases the
+ * route; callers must invoke it from an effect so a plugin reload cannot leak
+ * the registration.
+ */
+export function mountMcpEndpoint(webServer, options) {
+    const token = randomBytes(32).toString('hex');
+    const routeSegment = randomBytes(16).toString('hex');
+    const path = `/api/dsh-agy-cli/mcp/${routeSegment}`;
+    // The AGY conversation this bridge currently serves. AGY sends its own
+    // session id when it has one; otherwise the transport handle is this value,
+    // which the adapter re-points at the DSH session before each AGY turn.
+    let sessionHandle = randomBytes(16).toString('hex');
+    const session = new McpServerSession({
+        serverName: options.serverName,
+        serverVersion: options.serverVersion,
+        instructions: options.instructions,
+        listTools: sessionHandle => options.listTools(sessionHandle),
+        callTool: (sessionHandle, name, args) => options.callTool(sessionHandle, name, args),
+    });
+    const handler = async (req, res) => {
+        try {
+            if (!isLoopback(req.socket?.remoteAddress)) {
+                send(res, 403, 'forbidden', 'text/plain; charset=utf-8');
+                return;
+            }
+            if (req.method !== 'POST') {
+                res.writeHead(405, { allow: 'POST', 'content-length': 0 });
+                res.end();
+                return;
+            }
+            const authorization = req.headers.authorization ?? '';
+            const presented = authorization.startsWith('Bearer ') ? authorization.slice(7) : '';
+            if (!constantTimeEquals(presented, token)) {
+                send(res, 401, 'unauthorized', 'text/plain; charset=utf-8');
+                return;
+            }
+            // Snapshot the session handle before any await: setSession() re-points
+            // the closure variable when the next AGY turn starts, and a request
+            // suspended inside readBody must not wake up holding another session's
+            // agent scope.
+            const requestedSession = sessionHandle;
+            const body = await readBody(req);
+            if (body.trim().length === 0) {
+                send(res, 400, 'empty request body', 'text/plain; charset=utf-8');
+                return;
+            }
+            const response = await session.handleMessage(body, requestedSession);
+            if (response === undefined) {
+                // Notification: MCP expects 202 with no body.
+                res.writeHead(202, { 'content-length': 0 });
+                res.end();
+                return;
+            }
+            send(res, 200, encodeMcpFrame(response), 'application/json; charset=utf-8');
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            options.logger?.(`mcp endpoint error: ${message}`);
+            if (!res.headersSent) {
+                send(res, 500, message, 'text/plain; charset=utf-8');
+            }
+            else {
+                res.end();
+            }
+        }
+    };
+    const release = webServer.register({ kind: 'exact', path, handler });
+    // Read the port lazily: the carrier reports it only after its own listen
+    // callback, which may be later than this registration.
+    const port = webServer.port;
+    // A wildcard or IPv6 bind still reaches the bridge over loopback; a literal
+    // `::` in the URL is not connectable, so every non-IPv4 bind normalizes.
+    const host = webServer.host === '0.0.0.0' || webServer.host === '::' || (webServer.host ?? '').includes(':')
+        ? '127.0.0.1'
+        : (webServer.host ?? '127.0.0.1');
+    return {
+        url: typeof port === 'number' && port > 0 ? `http://${host}:${port}${path}` : undefined,
+        token,
+        dispose: release,
+        setSession: (handle) => {
+            sessionHandle = handle;
+        },
+    };
+}
+//# sourceMappingURL=endpoint.js.map

package/lib/mcp/protocol.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Minimal MCP (Model Context Protocol) server-side JSON-RPC layer.
+ *
+ * DSH ships `@modelcontextprotocol/core`, but that package exports only Zod
+ * schemas — it has no `Server` class and no transport. The framing and the
+ * three methods AGY actually needs are implemented here, deliberately small:
+ * a session-based server (one session per AGY conversation) over newline
+ * delimited JSON-RPC 2.0.
+ *
+ * Wire compatibility notes learned from AGY 1.3.2:
+ * - the negotiated protocol version is echoed back from the client, because
+ *   AGY rejects a server that answers with a version it did not offer;
+ * - a JSON-RPC *notification* (no `id`) must never be answered;
+ * - tool failures travel as a normal `tools/call` result with `isError: true`
+ *   so the model can react to them instead of seeing a transport error.
+ */
+export declare const MCP_PROTOCOL_VERSION = "2025-06-18";
+export declare const MCP_SUPPORTED_PROTOCOL_VERSIONS: readonly ["2025-06-18", "2025-03-26", "2024-11-05"];
+export declare const MCP_ERROR_CODES: Readonly<{
+    parseError: -32700;
+    invalidRequest: -32600;
+    methodNotFound: -32601;
+    invalidParams: -32602;
+    internalError: -32603;
+}>;
+export interface McpTextContent {
+    readonly type: 'text';
+    readonly text: string;
+}
+export interface McpToolDescriptor {
+    readonly name: string;
+    readonly description: string;
+    /** JSON Schema for the tool arguments; already sanitized by the caller. */
+    readonly inputSchema: Record<string, unknown>;
+}
+export interface McpCallResult {
+    readonly content: readonly McpTextContent[];
+    readonly isError: boolean;
+}
+export interface McpJsonRpcError {
+    readonly code: number;
+    readonly message: string;
+    readonly data?: unknown;
+}
+export interface McpJsonRpcResponse {
+    readonly jsonrpc: '2.0';
+    /** `null` when the request had no recoverable id (JSON-RPC 2.0 spec). */
+    readonly id: string | number | null;
+    readonly result?: unknown;
+    readonly error?: McpJsonRpcError;
+}
+export interface McpInitializeResult {
+    readonly protocolVersion: string;
+    readonly capabilities: Record<string, unknown>;
+    readonly serverInfo: {
+        readonly name: string;
+        readonly version: string;
+    };
+    readonly instructions: string;
+}
+export interface McpServerHandlers {
+    readonly serverName: string;
+    readonly serverVersion: string;
+    readonly instructions: string;
+    /** Tools exposed for one session; re-read on every `tools/list`. */
+    listTools(sessionId: string): Promise<readonly McpToolDescriptor[]>;
+    /** Execute one tool call for a session. Rejections become `isError` results. */
+    callTool(sessionId: string, name: string, args: Record<string, unknown>): Promise<McpCallResult>;
+}
+/** Pick the highest protocol version both sides understand. */
+export declare function negotiateProtocolVersion(requested: unknown): string;
+/**
+ * One MCP server instance. It is transport agnostic: `handleMessage` takes one
+ * decoded JSON-RPC message and returns the response to write back, or
+ * `undefined` for notifications.
+ */
+export declare class McpServerSession {
+    private readonly handlers;
+    private initialized;
+    private clientInfo;
+    private sessionHandle;
+    constructor(handlers: McpServerHandlers);
+    get isInitialized(): boolean;
+    get client(): {
+        name?: string;
+        version?: string;
+    } | undefined;
+    handleMessage(raw: string, sessionHandle?: string): Promise<McpJsonRpcResponse | undefined>;
+    private dispatch;
+    private initialize;
+    private callTool;
+    /**
+     * Resolve which AGY conversation a request belongs to. The transport-level
+     * handle (the secret path segment) wins, because it is what the endpoint
+     * minted for this bridge; `_meta.sessionId` is the client's own hint and is
+     * used only when the transport supplies nothing.
+     */
+    private resolveSession;
+}
+export declare class McpRpcError extends Error {
+    readonly code: number;
+    readonly data: unknown;
+    constructor(code: number, message: string, data?: unknown);
+}
+/** Serialize one response as a single newline-terminated JSON-RPC frame. */
+export declare function encodeMcpFrame(response: McpJsonRpcResponse): string;
+//# sourceMappingURL=protocol.d.ts.map