@mquan/portal 0.0.1

package/dist/src/mcp.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import * as z from "zod/v4";
+import { callRpc } from "./rpc/client.js";
+import { resolvePortalPaths } from "./runtime/paths.js";
+import { PORTAL_VERSION } from "./version.js";
+import { isEntrypoint } from "./entrypoint.js";
+export function createPortalMcpServer(identity, rpcCall) {
+    const server = new McpServer({ name: "portal", version: PORTAL_VERSION });
+    const authenticated = (params = {}) => ({
+        ...params,
+        sessionId: identity.sessionId,
+        token: identity.token,
+    });
+    server.registerTool("portal.sessions", {
+        description: "List cached current and historical local Codex and Claude sessions in this workspace. Set refresh only when newly created local history is required; remote agents are listed by portal.peers.",
+        inputSchema: {
+            refresh: z.boolean().optional().describe("Refresh local transcript history before listing; defaults false and may be slow"),
+        },
+        annotations: { readOnlyHint: true },
+    }, async (input) => result(() => rpcCall("agent.sessions", authenticated(input))));
+    server.registerTool("portal.peers", {
+        description: "Discover live, unauthenticated remote agents connected to this managed session's Portal server.",
+        inputSchema: {
+            query: z.string().min(1).max(256).optional(),
+            capability: z.enum(["message", "task"]).optional(),
+            limit: z.number().int().min(1).max(100).optional(),
+        },
+        annotations: { readOnlyHint: true },
+    }, async (input) => result(() => rpcCall("agent.peers", authenticated(input))));
+    server.registerTool("portal.recall", {
+        description: "Search indexed peer-session context without knowing which session contains it.",
+        inputSchema: {
+            query: z.string().min(1).describe("Natural-language or exact context query"),
+            providers: z.array(z.enum(["codex", "claude"])).optional(),
+            limit: z.number().int().min(1).max(50).optional(),
+            refresh: z.boolean().optional().describe("Refresh changed transcripts before recall; defaults true"),
+        },
+        annotations: { readOnlyHint: true },
+    }, async (input) => result(() => rpcCall("agent.recall", authenticated(input))));
+    server.registerTool("portal.delegate", {
+        description: "Offer an asynchronous task to one live remote agent. Returns after the remote Portal durably receives the offer; progress and results arrive as automatic turns.",
+        inputSchema: {
+            target: z.string().min(1).describe("Exact remote agent name or route ID from portal.peers"),
+            objective: z.string().min(1).max(4_096),
+            context: z.string().min(1).max(16_384).optional(),
+            expectedResult: z.string().min(1).max(2_048).optional(),
+            ttlSeconds: z.number().int().min(30).max(86_400).optional(),
+        },
+        annotations: { readOnlyHint: false, idempotentHint: false },
+    }, async (input) => result(() => rpcCall("agent.delegate", authenticated(input))));
+    server.registerTool("portal.task.update", {
+        description: "Send an acceptance, progress update, question, answer, result, decline, or failure for a remote Portal task.",
+        inputSchema: {
+            taskId: z.string().min(1),
+            action: z.enum(["accepted", "declined", "running", "progress", "question", "answer", "completed", "failed"]),
+            message: z.string().min(1).optional(),
+            reason: z.string().min(1).optional(),
+            question: z.string().min(1).optional(),
+            answer: z.string().min(1).optional(),
+            result: z.string().min(1).optional(),
+            error: z.string().min(1).optional(),
+            artifactReferences: z.array(z.string().min(1)).max(16).optional(),
+        },
+        annotations: { readOnlyHint: false, idempotentHint: false },
+    }, async (input) => result(() => rpcCall("agent.task.update", authenticated(input))));
+    server.registerTool("portal.send", {
+        description: "Send an attributed message to a local session or a live remote agent. Targets returned by portal.peers are supported directly; remote delivery becomes an asynchronous task offer whose progress and result return as automatic turns.",
+        inputSchema: {
+            target: z.string().min(1).optional().describe("Local session reference, or remote agent name, route ID, or session ID from portal.peers"),
+            message: z.string().min(1),
+            idempotencyKey: z.string().min(1).optional(),
+            replyTo: z.string().min(1).optional(),
+        },
+        annotations: { readOnlyHint: false, idempotentHint: false },
+    }, async ({ message, ...input }) => result(() => rpcCall("agent.send", authenticated({ ...input, body: message }))));
+    server.registerTool("portal.inbox", {
+        description: "Claim durable peer messages. On the next call, acknowledge message IDs only after processing them.",
+        inputSchema: {
+            acknowledge: z.array(z.string().min(1)).max(100).optional(),
+        },
+        annotations: { readOnlyHint: false },
+    }, async (input) => result(() => rpcCall("agent.inbox", authenticated(input))));
+    return server;
+}
+async function result(operation) {
+    try {
+        const value = await operation();
+        return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+    }
+    catch (error) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
+        };
+    }
+}
+export async function runMcp(environment = process.env) {
+    const sessionId = environment.PORTAL_SESSION_ID;
+    const token = environment.PORTAL_SESSION_TOKEN;
+    if (!sessionId || !token) {
+        throw new Error("Portal MCP requires PORTAL_SESSION_ID and PORTAL_SESSION_TOKEN");
+    }
+    const socketPath = environment.PORTAL_SOCKET_PATH ?? resolvePortalPaths(environment).socketPath;
+    const rpcCall = (method, params) => callRpc({ socketPath, timeoutMs: method === "agent.send" ? 15 * 60_000 : 30_000 }, method, params);
+    await rpcCall("agent.connect", { sessionId, token });
+    const server = createPortalMcpServer({ sessionId, token }, rpcCall);
+    const transport = new StdioServerTransport();
+    let heartbeat;
+    await server.connect(transport);
+    const previousClose = transport.onclose;
+    transport.onclose = () => {
+        if (heartbeat !== undefined)
+            clearInterval(heartbeat);
+        void rpcCall("agent.disconnect", { sessionId, token }).catch(() => undefined);
+        previousClose?.();
+    };
+    heartbeat = setInterval(() => {
+        void rpcCall("agent.connect", { sessionId, token }).catch((error) => {
+            console.error(`Portal heartbeat failed: ${error instanceof Error ? error.message : String(error)}`);
+        });
+    }, 45_000);
+    heartbeat.unref();
+}
+if (isEntrypoint(import.meta.url, process.argv[1])) {
+    await runMcp().catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    });
+}
+//# sourceMappingURL=mcp.js.map

package/dist/src/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../../src/mcp.ts"],"names":[],"mappings":"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"}

package/dist/src/network/client.d.ts

@@ -0,0 +1,67 @@
+import { type AgentPresence, type AgentRegister, type AgentRenew, type ClientMessage, type Envelope, type EnvelopeAcknowledge, type EnvelopeAcknowledged, type NetworkTransport, type ServerHello, type ServerMessage } from "./protocol.js";
+export interface WebSocketLike {
+    readonly readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: "open", listener: () => void, options?: {
+        once?: boolean;
+    }): void;
+    addEventListener(type: "message", listener: (event: {
+        data: unknown;
+    }) => void): void;
+    addEventListener(type: "error", listener: () => void, options?: {
+        once?: boolean;
+    }): void;
+    addEventListener(type: "close", listener: () => void, options?: {
+        once?: boolean;
+    }): void;
+}
+export type RemoteClientState = "connecting" | "connected" | "reconnecting" | "closed";
+export interface RemoteNetworkClientOptions {
+    clientId: string;
+    installationId: string;
+    connectTimeoutMs?: number;
+    requestTimeoutMs?: number;
+    reconnect?: boolean;
+    reconnectDelayMs?: number;
+    maximumReconnectDelayMs?: number;
+    webSocketFactory?: (url: string) => WebSocketLike;
+    now?: () => Date;
+    requestIdFactory?: () => string;
+}
+type RegisterInput = Omit<AgentRegister, "protocolVersion" | "type" | "requestId">;
+type RenewInput = Omit<AgentRenew, "protocolVersion" | "type" | "requestId">;
+type DiscoverInput = {
+    query?: string;
+    capability?: "message" | "task";
+    limit?: number;
+};
+/**
+ * Reusable client transport for the Portal relay protocol.
+ *
+ * A connection is usable only after the versioned hello exchange succeeds.
+ * Requests in flight when a socket drops are rejected (never silently
+ * replayed); later requests wait for the reconnect handshake.
+ */
+export declare class RemoteNetworkClient implements NetworkTransport {
+    #private;
+    readonly url: string;
+    private constructor();
+    static connect(url: string, options: RemoteNetworkClientOptions): Promise<RemoteNetworkClient>;
+    get state(): RemoteClientState;
+    get serverHello(): ServerHello | null;
+    onMessage(handler: (message: ServerMessage) => void | Promise<void>): () => void;
+    onEnvelope(handler: (envelope: Envelope) => void | Promise<void>): () => void;
+    onStateChange(handler: (state: RemoteClientState) => void): () => void;
+    onError(handler: (error: Error) => void): () => void;
+    register(input: RegisterInput): Promise<AgentPresence>;
+    renew(input: RenewInput): Promise<AgentPresence>;
+    unregister(routeId: string): Promise<void>;
+    discover(input?: DiscoverInput): Promise<AgentPresence[]>;
+    sendEnvelope(envelope: Envelope): Promise<EnvelopeAcknowledged>;
+    acknowledge(input: Omit<EnvelopeAcknowledge, "protocolVersion" | "type" | "requestId">): Promise<void>;
+    send(message: ClientMessage): Promise<void>;
+    close(): Promise<void>;
+}
+export declare function normalizeRemoteServerUrl(input: string): string;
+export {};