@cursor/july 0.1.1

package/dist/internal/mcp-endpoint.js

@@ -0,0 +1,355 @@
+/**
+ * Per-agent MCP surface: every mounted agent is also a Model Context
+ * Protocol server over streamable HTTP at `<base>/v1/mcp`, so other agents
+ * (peer MCP connections) and ordinary MCP clients can delegate work to it.
+ *
+ * The endpoint is stateless (a fresh `McpServer` + transport per POST, JSON
+ * response mode): session identity travels in tool arguments, not in MCP
+ * transport session headers, so any number of hosts can sit in front of it.
+ *
+ * Tools:
+ * - `ask` — start (or continue, via `sessionId`) a conversation with this
+ *   agent; runs a model turn in the agent's own context and returns the
+ *   reply. Bounded wait: long turns return `status: "running"`.
+ * - `check` — wait for / poll a running session started by `ask`.
+ * - `call_tool` — call one of the agent's deterministic server tools
+ *   directly (no model turn). Registered only when server tools exist.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { z } from "zod";
+import { samePrincipal } from "./auth.js";
+import { SessionBusyError, ToolInputError, ToolNotDirectlyCallableError, UnknownSessionError, UnknownToolError, } from "./session-engine.js";
+/** Channel id recorded on sessions created through the MCP surface. */
+export const MCP_CHANNEL_ID = "mcp";
+/** Mount path of the MCP surface, relative to the agent base. */
+export const MCP_ENDPOINT_PATH = "/v1/mcp";
+/**
+ * Bounded waits stay below the MCP client default request timeout (60s) so
+ * a long model turn degrades to `status: "running"` instead of a client
+ * timeout that loses the session id.
+ */
+const MAX_WAIT_SECONDS = 55;
+const DEFAULT_WAIT_SECONDS = 50;
+/**
+ * Serve one stateless streamable-HTTP MCP request: a fresh server +
+ * transport per POST, JSON response mode, spec-compliant 405 on other
+ * methods. Shared by the per-agent MCP endpoint and the Cursor account
+ * bridge so the subtle transport/error plumbing exists once.
+ */
+export function handleStatelessMcpRequest(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const logger = (_a = args.logger) !== null && _a !== void 0 ? _a : (() => { });
+        if (args.request.method !== "POST") {
+            // Stateless server: no server-initiated SSE stream (GET) and no
+            // transport sessions to delete (DELETE). 405 per the MCP spec;
+            // clients treat it as "streaming unsupported" and carry on.
+            return new Response(JSON.stringify({
+                jsonrpc: "2.0",
+                error: { code: -32000, message: "Method not allowed." },
+                id: null,
+            }), {
+                status: 405,
+                headers: { "content-type": "application/json", allow: "POST" },
+            });
+        }
+        const server = args.buildServer();
+        const transport = new WebStandardStreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+            enableJsonResponse: true,
+        });
+        try {
+            yield server.connect(transport);
+            // JSON-response mode materializes the full body before resolving,
+            // so closing in `finally` never truncates a streamed response.
+            return yield transport.handleRequest(args.request);
+        }
+        catch (error) {
+            logger(`[agent-serve] ${args.label} request failed: ${describeError(error)}`);
+            return new Response(JSON.stringify({
+                jsonrpc: "2.0",
+                error: { code: -32603, message: "Internal server error." },
+                id: null,
+            }), { status: 500, headers: { "content-type": "application/json" } });
+        }
+        finally {
+            void server.close().catch(() => { });
+        }
+    });
+}
+/** Tool names the MCP surface exposes for `project` (info projection). */
+export function mcpEndpointToolNames(project) {
+    const names = ["ask", "check"];
+    if (project.agent.tools.some((tool) => tool.execution === "server")) {
+        names.push("call_tool");
+    }
+    return names;
+}
+export function createAgentMcpEndpoint(args) {
+    const { engine, logger } = args;
+    return {
+        handle(request, auth) {
+            return handleStatelessMcpRequest(Object.assign({ request, buildServer: () => buildAgentMcpServer(engine, auth), label: "mcp endpoint" }, (logger === undefined ? {} : { logger })));
+        },
+    };
+}
+// ============================================================================
+// Server construction (per request; tools close over the caller principal)
+// ============================================================================
+function buildAgentMcpServer(engine, auth) {
+    const project = engine.project;
+    const agent = project.agent;
+    const server = new McpServer({ name: project.name, version: "0.1.0" }, { instructions: buildInstructions(project) });
+    server.registerTool("ask", {
+        description: buildAskDescription(project),
+        inputSchema: {
+            message: z.string().describe("The message or task for this agent."),
+            sessionId: z
+                .string()
+                .optional()
+                .describe("Existing session to follow up on (from a previous ask). Omit to start a fresh session with fresh context."),
+            waitSeconds: z
+                .number()
+                .min(0)
+                .max(MAX_WAIT_SECONDS)
+                .optional()
+                .describe(`How long to wait for the turn to finish before returning status "running" (default ${DEFAULT_WAIT_SECONDS}).`),
+        },
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ message, sessionId, waitSeconds }) {
+        try {
+            const targetSessionId = yield (sessionId === undefined
+                ? startSession(engine, auth, message)
+                : followUpSession(engine, auth, sessionId, message));
+            const payload = yield waitForReply(engine, targetSessionId, waitSeconds !== null && waitSeconds !== void 0 ? waitSeconds : DEFAULT_WAIT_SECONDS);
+            return toToolResult(payload);
+        }
+        catch (error) {
+            return errorResult(describeError(error));
+        }
+    }));
+    server.registerTool("check", {
+        description: 'Wait for (or poll) a session started with ask. Returns the final reply once the turn completes, or status "running" to keep waiting. Use waitSeconds: 0 for a non-blocking poll.',
+        inputSchema: {
+            sessionId: z.string().describe("Session id returned by ask."),
+            waitSeconds: z
+                .number()
+                .min(0)
+                .max(MAX_WAIT_SECONDS)
+                .optional()
+                .describe(`How long to wait for the running turn before returning status "running" (default ${DEFAULT_WAIT_SECONDS}).`),
+        },
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ sessionId, waitSeconds }) {
+        try {
+            yield requireOwnedSession(engine, auth, sessionId);
+            const payload = yield waitForReply(engine, sessionId, waitSeconds !== null && waitSeconds !== void 0 ? waitSeconds : DEFAULT_WAIT_SECONDS);
+            return toToolResult(payload);
+        }
+        catch (error) {
+            return errorResult(describeError(error));
+        }
+    }));
+    const serverTools = agent.tools.filter((tool) => tool.execution === "server");
+    if (serverTools.length > 0) {
+        server.registerTool("call_tool", {
+            description: `Call one of this agent's deterministic server tools directly (no model turn decides anything). Available tools: ${serverTools
+                .map((tool) => tool.name)
+                .join(", ")}.`,
+            inputSchema: {
+                toolName: z.string().describe("Name of the server tool to call."),
+                input: z
+                    .record(z.unknown())
+                    .optional()
+                    .describe("Tool input, validated against the tool's schema."),
+                sessionId: z
+                    .string()
+                    .optional()
+                    .describe("Run the tool inside an existing session (recorded on its event stream). Omit for an ephemeral scratch workspace."),
+            },
+        }, (_a) => __awaiter(this, [_a], void 0, function* ({ toolName, input, sessionId }) {
+            try {
+                if (sessionId !== undefined) {
+                    yield requireOwnedSession(engine, auth, sessionId);
+                }
+                const outcome = yield engine.callTool(toolName, input !== null && input !== void 0 ? input : {}, Object.assign({ auth }, (sessionId === undefined ? {} : { sessionId })));
+                return Object.assign({ content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(Object.assign({ toolName: outcome.toolName, isError: outcome.isError, result: outcome.result, durationMs: outcome.durationMs }, (outcome.errorMessage === undefined
+                                ? {}
+                                : { errorMessage: outcome.errorMessage }))),
+                        },
+                    ] }, (outcome.isError ? { isError: true } : {}));
+            }
+            catch (error) {
+                if (error instanceof UnknownToolError) {
+                    return errorResult(`${error.message}. Available tools: ${error.availableToolNames.join(", ") || "(none)"}.`);
+                }
+                if (error instanceof ToolNotDirectlyCallableError ||
+                    error instanceof ToolInputError ||
+                    error instanceof SessionBusyError ||
+                    error instanceof UnknownSessionError) {
+                    return errorResult(error.message);
+                }
+                return errorResult(describeError(error));
+            }
+        }));
+    }
+    return server;
+}
+function buildInstructions(project) {
+    const agent = project.agent;
+    const parts = [
+        `This MCP server fronts the Cursor agent "${project.name}".`,
+        ...(agent.description === undefined ? [] : [agent.description]),
+        'Delegate a task with the ask tool: each call without a sessionId starts a fresh session (fresh context); pass the returned sessionId to continue the same conversation. When ask returns status "running", call check with that sessionId to keep waiting for the reply.',
+    ];
+    return parts.join(" ");
+}
+function buildAskDescription(project) {
+    const description = project.agent.description;
+    const purpose = description === undefined || description.trim() === ""
+        ? `the "${project.name}" agent`
+        : `the "${project.name}" agent — ${description.trim()}`;
+    return `Send a message to ${purpose}. Runs a full model turn in that agent's own context and returns its reply. Omit sessionId to start a fresh session; pass it to follow up. Long turns return status "running" — call check with the sessionId to keep waiting.`;
+}
+// ============================================================================
+// Session helpers
+// ============================================================================
+function startSession(engine, auth, message) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const session = yield engine.send(MCP_CHANNEL_ID, message, { auth });
+        return session.id;
+    });
+}
+function followUpSession(engine, auth, sessionId, message) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const record = yield requireOwnedSession(engine, auth, sessionId);
+        if (record.mode === "task") {
+            throw new Error(`Session ${sessionId} is a fire-and-forget task session; it does not accept follow-ups.`);
+        }
+        if (record.continuationKey === null) {
+            throw new Error(`Session ${sessionId} is not addressable for follow-ups (no active continuation).`);
+        }
+        // Send as the session owner after the ownership gate above, mirroring the
+        // HTTP follow-up route (machine callers address sessions by id; the HTTP
+        // continuation token is not rotated).
+        yield engine.send(record.channelId, message, {
+            auth: record.auth,
+            continuationToken: record.continuationKey,
+        });
+        return sessionId;
+    });
+}
+function requireOwnedSession(engine, auth, sessionId) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const record = yield engine.sessions.get(sessionId);
+        if (record === undefined) {
+            throw new UnknownSessionError(sessionId);
+        }
+        if (!samePrincipal(record.auth, auth)) {
+            throw new Error(`Session ${sessionId} belongs to a different principal; use the credentials that created it.`);
+        }
+        return record;
+    });
+}
+function waitForReply(engine, sessionId, waitSeconds) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const waitMs = Math.max(0, Math.min(waitSeconds, MAX_WAIT_SECONDS)) * 1000;
+        const outcome = yield raceTimeout(engine.waitForCompletion(sessionId), waitMs);
+        if (outcome === undefined) {
+            return {
+                status: "running",
+                sessionId,
+                note: `The turn is still running. Call check with { "sessionId": "${sessionId}" } to keep waiting.`,
+            };
+        }
+        return toReplyPayload(engine, sessionId, outcome);
+    });
+}
+function toReplyPayload(engine, sessionId, outcome) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        if (outcome.status === "finished") {
+            let reply = outcome.result;
+            if (reply === undefined || reply === "") {
+                // The engine's in-memory outcome is gone after a host restart; fall
+                // back to the durable event log for the last completed turn.
+                reply = yield latestReplyFromEvents(engine, sessionId);
+            }
+            return Object.assign({ status: "completed", sessionId }, (reply === undefined ? {} : { reply }));
+        }
+        if (outcome.status === "cancelled") {
+            return {
+                status: "cancelled",
+                sessionId,
+                errorMessage: (_a = outcome.errorMessage) !== null && _a !== void 0 ? _a : "The turn was cancelled.",
+            };
+        }
+        return {
+            status: "error",
+            sessionId,
+            errorMessage: (_b = outcome.errorMessage) !== null && _b !== void 0 ? _b : "The turn failed.",
+        };
+    });
+}
+function latestReplyFromEvents(engine, sessionId) {
+    return __awaiter(this, void 0, void 0, function* () {
+        let events;
+        try {
+            events = yield engine.listEvents(sessionId);
+        }
+        catch (_a) {
+            return undefined;
+        }
+        for (let i = events.length - 1; i >= 0; i--) {
+            const event = events[i];
+            if (event === undefined) {
+                continue;
+            }
+            if (event.type === "turn.completed" && event.data.result !== undefined) {
+                return event.data.result;
+            }
+            if (event.type === "message.completed" && event.data.text !== "") {
+                return event.data.text;
+            }
+        }
+        return undefined;
+    });
+}
+function toToolResult(payload) {
+    return Object.assign({ content: [{ type: "text", text: JSON.stringify(payload) }] }, (payload.status === "error" ? { isError: true } : {}));
+}
+function errorResult(message) {
+    return {
+        content: [{ type: "text", text: message }],
+        isError: true,
+    };
+}
+/** Resolve to the promise value, or undefined once `ms` elapses first. */
+function raceTimeout(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            resolve(undefined);
+        }, ms);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error instanceof Error ? error : new Error(String(error)));
+        });
+    });
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/internal/mcp-host.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Host-side MCP clients for authored `agent/mcp-connections/*`.
+ *
+ * Every connection is always available in three places:
+ * - the Cursor agent, via SDK `mcpServers` (local harness or cloud)
+ * - the agent-serve host, for in-process server tools through
+ *   {@link HostMcpRegistry} on {@link ToolContext.host}.mcp
+ * - channel / webhook route handlers through
+ *   {@link HostMcpRegistry} on {@link ChannelHandlerArgs.host}.mcp
+ */
+import type { DiscoveredConnection, HostMcpCallResult, HostMcpRegistry, HostMcpToolInfo } from "../types.js";
+export declare class McpHost implements HostMcpRegistry {
+    private readonly byName;
+    private readonly clients;
+    constructor(connections: DiscoveredConnection[]);
+    /**
+     * Register a connection after construction (serve-time resolved peers).
+     * Clients open lazily on first use, so adding before first call is safe.
+     */
+    addConnection(connection: DiscoveredConnection): void;
+    names(): string[];
+    listTools(connectionName: string): Promise<HostMcpToolInfo[]>;
+    callTool(connectionName: string, toolName: string, args?: Record<string, unknown>): Promise<HostMcpCallResult>;
+    close(): Promise<void>;
+    private getClient;
+    private connect;
+}
+//# sourceMappingURL=mcp-host.d.ts.map

package/dist/internal/mcp-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-host.d.ts","sourceRoot":"","sources":["../../src/internal/mcp-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EACV,oBAAoB,EACpB,iBAAiB,EACjB,eAAe,EACf,eAAe,EAEhB,MAAM,aAAa,CAAC;AAOrB,qBAAa,OAAQ,YAAW,eAAe;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2C;IAClE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgD;IAExE,YAAY,WAAW,EAAE,oBAAoB,EAAE,EAI9C;IAED;;;OAGG;IACH,aAAa,CAAC,UAAU,EAAE,oBAAoB,GAAG,IAAI,CAEpD;IAED,KAAK,IAAI,MAAM,EAAE,CAEhB;IAEK,SAAS,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAYlE;IAEK,QAAQ,CACZ,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACjC,OAAO,CAAC,iBAAiB,CAAC,CAO5B;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAU3B;IAED,OAAO,CAAC,SAAS;YAYH,OAAO;CAUtB"}

package/dist/internal/mcp-host.js

@@ -0,0 +1,162 @@
+/**
+ * Host-side MCP clients for authored `agent/mcp-connections/*`.
+ *
+ * Every connection is always available in three places:
+ * - the Cursor agent, via SDK `mcpServers` (local harness or cloud)
+ * - the agent-serve host, for in-process server tools through
+ *   {@link HostMcpRegistry} on {@link ToolContext.host}.mcp
+ * - channel / webhook route handlers through
+ *   {@link HostMcpRegistry} on {@link ChannelHandlerArgs.host}.mcp
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+export class McpHost {
+    constructor(connections) {
+        this.byName = new Map();
+        this.clients = new Map();
+        for (const connection of connections) {
+            this.byName.set(connection.name, connection);
+        }
+    }
+    /**
+     * Register a connection after construction (serve-time resolved peers).
+     * Clients open lazily on first use, so adding before first call is safe.
+     */
+    addConnection(connection) {
+        this.byName.set(connection.name, connection);
+    }
+    names() {
+        return [...this.byName.keys()].sort();
+    }
+    listTools(connectionName) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { client } = yield this.getClient(connectionName);
+            const listed = yield client.listTools();
+            return listed.tools.map((tool) => (Object.assign(Object.assign({ name: tool.name }, (tool.description === undefined
+                ? {}
+                : { description: tool.description })), (tool.inputSchema === undefined
+                ? {}
+                : { inputSchema: tool.inputSchema }))));
+        });
+    }
+    callTool(connectionName_1, toolName_1) {
+        return __awaiter(this, arguments, void 0, function* (connectionName, toolName, args = {}) {
+            const { client } = yield this.getClient(connectionName);
+            const result = yield client.callTool({
+                name: toolName,
+                arguments: args,
+            });
+            return normalizeCallResult(result);
+        });
+    }
+    close() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const opened = yield Promise.allSettled([...this.clients.values()]);
+            this.clients.clear();
+            yield Promise.allSettled(opened.map((settled) => __awaiter(this, void 0, void 0, function* () {
+                if (settled.status === "fulfilled") {
+                    yield settled.value.close();
+                }
+            })));
+        });
+    }
+    getClient(name) {
+        let pending = this.clients.get(name);
+        if (pending === undefined) {
+            pending = this.connect(name).catch((error) => {
+                this.clients.delete(name);
+                throw error;
+            });
+            this.clients.set(name, pending);
+        }
+        return pending;
+    }
+    connect(name) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const connection = this.byName.get(name);
+            if (connection === undefined) {
+                const known = this.names().join(", ") || "(none)";
+                throw new Error(`Unknown MCP connection "${name}". Authored MCP connections: ${known}.`);
+            }
+            return openConnection(connection);
+        });
+    }
+}
+function openConnection(connection) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const client = new Client({
+            name: "agent-serve",
+            version: "0.1.0",
+        });
+        const transport = createTransport(connection);
+        yield client.connect(transport);
+        return {
+            client,
+            close: () => __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                try {
+                    yield client.close();
+                }
+                catch (_b) {
+                    // Best-effort teardown.
+                }
+                try {
+                    yield (_a = transport.close) === null || _a === void 0 ? void 0 : _a.call(transport);
+                }
+                catch (_c) {
+                    // Best-effort teardown.
+                }
+            }),
+        };
+    });
+}
+function createTransport(connection) {
+    var _a;
+    const transport = connection.transport;
+    if ("agent" in transport) {
+        // Peers are resolved to concrete URLs by the serve host before any call
+        // (SessionEngine.setResolvedConnections); reaching here means the
+        // connection is being used outside a running server.
+        throw new Error(`MCP connection "${connection.name}" targets peer agent "${transport.agent}" and has not been resolved; peer MCP connections are only callable on a running serve host.`);
+    }
+    if ("cursorAccount" in transport) {
+        // Same contract as peers: the serve host resolves the account bridge URL
+        // before any call (SessionEngine.setResolvedConnections).
+        throw new Error(`MCP connection "${connection.name}" exposes the Cursor account's connectors and has not been resolved; Cursor account MCP connections are only callable on a running serve host.`);
+    }
+    if ("command" in transport) {
+        return new StdioClientTransport(Object.assign(Object.assign(Object.assign({ command: transport.command }, (transport.args === undefined ? {} : { args: transport.args })), { env: Object.assign(Object.assign({}, Object.fromEntries(Object.entries(process.env).filter((entry) => entry[1] !== undefined))), ((_a = transport.env) !== null && _a !== void 0 ? _a : {})) }), (transport.cwd === undefined ? {} : { cwd: transport.cwd })));
+    }
+    const url = new URL(transport.url);
+    const requestInit = transport.headers === undefined
+        ? undefined
+        : { headers: transport.headers };
+    if (transport.type === "sse") {
+        return new SSEClientTransport(url, Object.assign({}, (requestInit === undefined ? {} : { requestInit })));
+    }
+    return new StreamableHTTPClientTransport(url, Object.assign({}, (requestInit === undefined ? {} : { requestInit })));
+}
+function normalizeCallResult(result) {
+    if (typeof result !== "object" || result === null) {
+        return {
+            content: [{ type: "text", text: String(result) }],
+        };
+    }
+    const record = result;
+    return Object.assign(Object.assign({ content: Array.isArray(record.content)
+            ? record.content
+            : [{ type: "text", text: JSON.stringify(result) }] }, (record.isError === undefined ? {} : { isError: record.isError })), (record.structuredContent === undefined
+        ? {}
+        : { structuredContent: record.structuredContent }));
+}

package/dist/internal/net.d.ts

@@ -0,0 +1,5 @@
+/** True for IPv4/IPv6 loopback addresses (including IPv4-mapped IPv6). */
+export declare function isLoopbackAddress(address: string): boolean;
+/** True when a parsed URL hostname refers to loopback (localhost / 127.x / ::1). */
+export declare function isLoopbackHostname(hostname: string): boolean;
+//# sourceMappingURL=net.d.ts.map

package/dist/internal/net.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"net.d.ts","sourceRoot":"","sources":["../../src/internal/net.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAQ1D;AAED,oFAAoF;AACpF,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAkB5D"}

package/dist/internal/net.js

@@ -0,0 +1,30 @@
+/** True for IPv4/IPv6 loopback addresses (including IPv4-mapped IPv6). */
+export function isLoopbackAddress(address) {
+    const normalized = address.startsWith("::ffff:")
+        ? address.slice("::ffff:".length)
+        : address;
+    if (normalized === "::1" || normalized === "localhost") {
+        return true;
+    }
+    return normalized.startsWith("127.");
+}
+/** True when a parsed URL hostname refers to loopback (localhost / 127.x / ::1). */
+export function isLoopbackHostname(hostname) {
+    const normalized = hostname.toLowerCase();
+    if (normalized === "localhost" || normalized === "::1") {
+        return true;
+    }
+    if (normalized.startsWith("[") && normalized.endsWith("]")) {
+        const inner = normalized.slice(1, -1);
+        return inner === "::1";
+    }
+    const ipv4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(normalized);
+    if (ipv4 === null) {
+        return false;
+    }
+    const octets = ipv4.slice(1, 5).map((part) => Number(part));
+    if (octets.some((octet) => octet > 255)) {
+        return false;
+    }
+    return octets[0] === 127;
+}

package/dist/internal/peer-connections.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Peer MCP connections: `defineConnection({ agent: "<slug>" })` addresses
+ * another agent mounted on the same serve host. Discovery keeps the
+ * transport symbolic (the target slug); the server resolves it to that
+ * agent's MCP endpoint (`/<slug>/v1/mcp`) once mounts and the listen
+ * address are known.
+ *
+ * Local-runtime turns (and host-side `ctx.host.mcp` calls) use the loopback
+ * server URL. Cloud-runtime turns run on a VM that cannot reach loopback,
+ * so they use the serve `publicUrl` when configured — and omit the peer
+ * (with a startup warning) when it is not.
+ */
+import { type AgentProject } from "../types.js";
+import type { EngineResolvedConnection } from "./session-engine.js";
+/** A validated peer reference: MCP connection name → target mount slug. */
+export interface PeerConnectionRef {
+    /** Connection (MCP server) name — the filename under `agent/mcp-connections/`. */
+    name: string;
+    /** Slug of the peer agent mount this connection targets. */
+    targetSlug: string;
+}
+/**
+ * Validate every peer MCP connection across `mounts` and return them grouped by
+ * the referencing mount's slug. Throws on references to unknown slugs and on
+ * self-references (an agent asking itself recurses forever).
+ */
+export declare function collectPeerConnections(mounts: Array<{
+    slug: string;
+    project: AgentProject;
+}>): Map<string, PeerConnectionRef[]>;
+/**
+ * Resolve validated peer refs to concrete MCP URLs once the server is
+ * listening. `serverUrl` is the loopback base (`http://127.0.0.1:<port>`);
+ * `publicUrl` (when configured) is the externally reachable base used for
+ * cloud-runtime turns. When the host requires a bearer token, it is attached
+ * so peer calls pass the target agent's auth chain.
+ */
+export declare function resolvePeerConnections(args: {
+    refs: PeerConnectionRef[];
+    serverUrl: string;
+    publicUrl?: string;
+    authToken?: string;
+}): EngineResolvedConnection[];
+//# sourceMappingURL=peer-connections.d.ts.map

package/dist/internal/peer-connections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-connections.d.ts","sourceRoot":"","sources":["../../src/internal/peer-connections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,KAAK,YAAY,EAA6B,MAAM,aAAa,CAAC;AAE3E,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAEpE,2EAA2E;AAC3E,MAAM,WAAW,iBAAiB;IAChC,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CAAC,GACrD,GAAG,CAAC,MAAM,EAAE,iBAAiB,EAAE,CAAC,CA+BlC;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,IAAI,EAAE,iBAAiB,EAAE,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,wBAAwB,EAAE,CAkB7B"}