@pasko70/pibo 1.16.6 → 2.0.0

package/dist/tools/mcp-bridge.js

@@ -0,0 +1,511 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import { createServer } from "node:http";
+import { Server as McpProtocolServer } from "@modelcontextprotocol/sdk/server/index.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, isInitializeRequest, } from "@modelcontextprotocol/sdk/types.js";
+import { Value } from "typebox/value";
+import { PiboToolCredentialError, PiboToolCredentialRegistry, } from "./credential-registry.js";
+const DEFAULT_MAX_REQUEST_BYTES = 2 * 1024 * 1024;
+const DEFAULT_LARGE_RESULT_THRESHOLD_BYTES = 128 * 1024;
+const DEFAULT_PREVIEW_BYTES = 4 * 1024;
+export class PiboToolMcpBridgeAuthorizationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "PiboToolMcpBridgeAuthorizationError";
+        this.code = code;
+    }
+}
+function readBearerToken(request) {
+    const header = request.headers.authorization;
+    const value = Array.isArray(header) ? header[0] : header;
+    if (!value)
+        return undefined;
+    const match = /^Bearer\s+([^\s]+)$/i.exec(value.trim());
+    return match?.[1];
+}
+async function readJsonBody(request, maxBytes) {
+    const chunks = [];
+    let byteLength = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        byteLength += buffer.byteLength;
+        if (byteLength > maxBytes)
+            throw new Error(`MCP request exceeds ${maxBytes} bytes.`);
+        chunks.push(buffer);
+    }
+    if (chunks.length === 0)
+        return undefined;
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+function sendJson(response, statusCode, body, headers = {}) {
+    if (response.headersSent || response.writableEnded)
+        return;
+    response.writeHead(statusCode, {
+        "content-type": "application/json; charset=utf-8",
+        "cache-control": "no-store",
+        ...headers,
+    });
+    response.end(JSON.stringify(body));
+}
+function jsonRpcError(code, message) {
+    return {
+        jsonrpc: "2.0",
+        id: null,
+        error: { code, message },
+    };
+}
+function toJsonValue(value) {
+    if (value === undefined)
+        return undefined;
+    try {
+        return JSON.parse(JSON.stringify(value));
+    }
+    catch {
+        return undefined;
+    }
+}
+function toStructuredObject(value) {
+    if (value === undefined)
+        return undefined;
+    if (value && typeof value === "object" && !Array.isArray(value))
+        return value;
+    return { value };
+}
+function textPreview(value, maxBytes) {
+    if (Buffer.byteLength(value, "utf8") <= maxBytes)
+        return value;
+    let preview = value.slice(0, maxBytes);
+    while (Buffer.byteLength(preview, "utf8") > maxBytes)
+        preview = preview.slice(0, -1);
+    return `${preview}\n…`;
+}
+function piboToolToMcpTool(tool) {
+    const inputSchema = tool.inputSchema;
+    return {
+        name: tool.name,
+        title: tool.title,
+        description: tool.description,
+        inputSchema,
+        ...(tool.outputSchema ? { outputSchema: tool.outputSchema } : {}),
+        ...(tool.annotations
+            ? {
+                annotations: {
+                    title: tool.title,
+                    ...(tool.annotations.readOnly !== undefined ? { readOnlyHint: tool.annotations.readOnly } : {}),
+                    ...(tool.annotations.destructive !== undefined ? { destructiveHint: tool.annotations.destructive } : {}),
+                    ...(tool.annotations.idempotent !== undefined ? { idempotentHint: tool.annotations.idempotent } : {}),
+                    ...(tool.annotations.openWorld !== undefined ? { openWorldHint: tool.annotations.openWorld } : {}),
+                },
+            }
+            : {}),
+    };
+}
+async function storeLargeContent(options) {
+    return await options.writer.write({
+        piboSessionId: options.scope.piboSessionId,
+        toolName: options.tool.name,
+        toolCallId: options.toolCallId,
+        contentType: options.contentType,
+        value: options.value,
+    });
+}
+async function convertContent(items, options) {
+    const content = [];
+    const payloadRefs = [];
+    for (const item of items) {
+        if (item.type === "text") {
+            const byteLength = Buffer.byteLength(item.text, "utf8");
+            if (options.writer && byteLength > options.threshold) {
+                const stored = await storeLargeContent({
+                    writer: options.writer,
+                    scope: options.scope,
+                    tool: options.tool,
+                    toolCallId: options.toolCallId,
+                    contentType: "text/plain; charset=utf-8",
+                    value: item.text,
+                });
+                payloadRefs.push(stored.ref);
+                content.push({
+                    type: "text",
+                    text: `${stored.preview ?? textPreview(item.text, options.previewBytes)}\n[Large result stored as ${stored.ref}; ${stored.byteLength} bytes]`,
+                });
+            }
+            else {
+                content.push({ type: "text", text: item.text });
+            }
+            continue;
+        }
+        if (item.payloadRef && item.data === undefined) {
+            payloadRefs.push(item.payloadRef);
+            content.push({ type: "text", text: item.alt ?? `Image payload stored as ${item.payloadRef}` });
+            continue;
+        }
+        if (item.data === undefined) {
+            content.push({ type: "text", text: item.alt ?? "Image result omitted." });
+            continue;
+        }
+        const bytes = Buffer.from(item.data, "base64");
+        if (options.writer && bytes.byteLength > options.threshold) {
+            const stored = await storeLargeContent({
+                writer: options.writer,
+                scope: options.scope,
+                tool: options.tool,
+                toolCallId: options.toolCallId,
+                contentType: item.mimeType,
+                value: bytes,
+            });
+            payloadRefs.push(stored.ref);
+            content.push({ type: "text", text: item.alt ?? `Image stored as ${stored.ref}; ${stored.byteLength} bytes` });
+        }
+        else {
+            content.push({ type: "image", data: item.data, mimeType: item.mimeType });
+        }
+    }
+    return { content, payloadRefs };
+}
+async function piboResultToMcp(result, options) {
+    const converted = await convertContent(result.content, options);
+    const payloadRefs = [...new Set([...(result.payloadRefs ?? []), ...converted.payloadRefs])];
+    let structuredContent = result.structuredContent ?? toJsonValue(result.details);
+    if (structuredContent !== undefined && options.writer) {
+        const encoded = JSON.stringify(structuredContent);
+        if (Buffer.byteLength(encoded, "utf8") > options.threshold) {
+            const stored = await storeLargeContent({
+                writer: options.writer,
+                scope: options.scope,
+                tool: options.tool,
+                toolCallId: options.toolCallId,
+                contentType: "application/json",
+                value: encoded,
+            });
+            payloadRefs.push(stored.ref);
+            structuredContent = undefined;
+            converted.content.push({
+                type: "text",
+                text: `[Structured result stored as ${stored.ref}; ${stored.byteLength} bytes]`,
+            });
+        }
+    }
+    if (converted.content.length === 0)
+        converted.content.push({ type: "text", text: result.isError ? "Tool failed." : "Tool completed." });
+    return {
+        content: converted.content,
+        ...(toStructuredObject(structuredContent) ? { structuredContent: toStructuredObject(structuredContent) } : {}),
+        ...(result.isError !== undefined ? { isError: result.isError } : {}),
+        _meta: {
+            piboSessionId: options.scope.piboSessionId,
+            runtimeInstanceId: options.scope.runtimeInstanceId,
+            adapterId: options.scope.adapterId,
+            sessionGeneration: options.scope.sessionGeneration,
+            toolCallId: options.toolCallId,
+            ...(payloadRefs.length ? { payloadRefs } : {}),
+            ...(result.metadata ? { metadata: result.metadata } : {}),
+        },
+    };
+}
+function progressMessage(update) {
+    if (update.message)
+        return update.message;
+    const text = update.content.find((item) => item.type === "text");
+    return text?.type === "text" ? text.text : undefined;
+}
+export class PiboToolMcpBridge {
+    credentials;
+    options;
+    requestScope = new AsyncLocalStorage();
+    mcpSessions = new Map();
+    closingSessions = new Set();
+    server;
+    address;
+    constructor(options) {
+        if (options.host !== undefined && options.host !== "127.0.0.1" && options.host !== "::1") {
+            throw new Error("Pibo tool MCP bridge must bind to a loopback address.");
+        }
+        this.credentials = options.credentialRegistry ?? new PiboToolCredentialRegistry();
+        this.options = {
+            ...options,
+            host: options.host ?? "127.0.0.1",
+            port: options.port ?? 0,
+            maxRequestBytes: options.maxRequestBytes ?? DEFAULT_MAX_REQUEST_BYTES,
+            largeResultThresholdBytes: options.largeResultThresholdBytes ?? DEFAULT_LARGE_RESULT_THRESHOLD_BYTES,
+            previewBytes: options.previewBytes ?? DEFAULT_PREVIEW_BYTES,
+            serverName: options.serverName ?? "pibo-session-tools",
+            serverVersion: options.serverVersion ?? "1",
+        };
+    }
+    async start() {
+        if (this.address)
+            return { ...this.address };
+        const server = createServer((request, response) => {
+            void this.handleRequest(request, response).catch((error) => {
+                sendJson(response, 500, jsonRpcError(-32603, error instanceof Error ? error.message : String(error)));
+            });
+        });
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(this.options.port, this.options.host, () => {
+                server.off("error", reject);
+                resolve();
+            });
+        });
+        const address = server.address();
+        if (!address || typeof address === "string") {
+            server.close();
+            throw new Error("Pibo tool MCP bridge failed to resolve its loopback address.");
+        }
+        this.server = server;
+        this.address = {
+            host: this.options.host,
+            port: address.port,
+            url: `http://${this.options.host === "::1" ? "[::1]" : this.options.host}:${address.port}/mcp`,
+        };
+        return { ...this.address };
+    }
+    getAddress() {
+        return this.address ? { ...this.address } : undefined;
+    }
+    issueCredential(scope, ttlMs) {
+        return this.credentials.issue(scope, ttlMs);
+    }
+    closeCredentialSessions(credentialId) {
+        return this.closeMatchingSessions((session) => session.credentialId === credentialId);
+    }
+    closeSessionGeneration(piboSessionId, sessionGeneration) {
+        return this.closeMatchingSessions((session) => (session.piboSessionId === piboSessionId
+            && session.sessionGeneration === sessionGeneration));
+    }
+    async stop() {
+        this.closeMatchingSessions(() => true);
+        await Promise.allSettled([...this.closingSessions]);
+        const server = this.server;
+        this.server = undefined;
+        this.address = undefined;
+        if (!server)
+            return;
+        await new Promise((resolve, reject) => {
+            server.close((error) => error ? reject(error) : resolve());
+            server.closeAllConnections();
+        });
+    }
+    closeMatchingSessions(predicate) {
+        let closed = 0;
+        for (const session of new Set(this.mcpSessions.values())) {
+            if (session.closing || !predicate(session))
+                continue;
+            session.closing = true;
+            if (session.sessionId)
+                this.mcpSessions.delete(session.sessionId);
+            const closing = Promise.allSettled([
+                session.transport.close(),
+                session.protocolServer.close(),
+            ]).finally(() => this.closingSessions.delete(closing));
+            this.closingSessions.add(closing);
+            closed += 1;
+        }
+        return closed;
+    }
+    async authenticate(request) {
+        const token = readBearerToken(request);
+        if (!token)
+            throw new PiboToolCredentialError("credential_invalid", "Bearer credential is required.");
+        const scope = this.credentials.authenticate(token);
+        if (this.options.isSessionGenerationActive && !await this.options.isSessionGenerationActive(scope)) {
+            throw new PiboToolMcpBridgeAuthorizationError("session_generation_inactive", "The Pibo runtime session generation for this tool credential is no longer active.");
+        }
+        return scope;
+    }
+    async resolveAllowedTools(scope) {
+        const selected = new Set(scope.allowedToolNames);
+        const tools = await this.options.resolveTools(scope);
+        return new Map(tools
+            .filter((tool) => selected.has(tool.name) && tool.portable !== false)
+            .map((tool) => [tool.name, tool]));
+    }
+    currentRequestScope() {
+        const scope = this.requestScope.getStore();
+        if (!scope)
+            throw new PiboToolMcpBridgeAuthorizationError("session_generation_inactive", "MCP request has no active Pibo credential scope.");
+        return scope;
+    }
+    configureProtocolServer(protocolServer) {
+        protocolServer.setRequestHandler(ListToolsRequestSchema, async () => {
+            const scope = this.currentRequestScope();
+            const tools = await this.resolveAllowedTools(scope);
+            return { tools: [...tools.values()].map(piboToolToMcpTool) };
+        });
+        protocolServer.setRequestHandler(CallToolRequestSchema, async (call, extra) => {
+            return await this.executeToolCall(call, extra);
+        });
+    }
+    async executeToolCall(call, extra) {
+        const scope = this.currentRequestScope();
+        const tools = await this.resolveAllowedTools(scope);
+        const tool = tools.get(call.params.name);
+        if (!scope.allowedToolNames.includes(call.params.name)) {
+            return {
+                content: [{ type: "text", text: `Tool "${call.params.name}" is outside this session credential's selected tool set.` }],
+                isError: true,
+            };
+        }
+        if (!tool) {
+            return {
+                content: [{ type: "text", text: `Tool "${call.params.name}" is unavailable or not portable for this runtime session.` }],
+                isError: true,
+            };
+        }
+        const input = call.params.arguments ?? {};
+        if (!Value.Check(tool.inputSchema, input)) {
+            const errors = [...Value.Errors(tool.inputSchema, input)].slice(0, 5).map((error) => {
+                const location = error.path
+                    ?? error.instancePath
+                    ?? "/";
+                return `${location || "/"}: ${error.message}`;
+            });
+            return {
+                content: [{ type: "text", text: `Invalid arguments for ${tool.name}: ${errors.join("; ")}` }],
+                isError: true,
+            };
+        }
+        const preparedInput = tool.prepareInput ? tool.prepareInput(input) : input;
+        const toolCallId = String(extra.requestId);
+        const executionDefaults = this.options.resolveExecutionContext
+            ? await this.options.resolveExecutionContext(scope)
+            : {};
+        const pendingProgress = [];
+        let updateSequence = 0;
+        const onUpdate = extra._meta?.progressToken === undefined
+            ? undefined
+            : (update) => {
+                updateSequence += 1;
+                pendingProgress.push(extra.sendNotification({
+                    method: "notifications/progress",
+                    params: {
+                        progressToken: extra._meta.progressToken,
+                        progress: update.progress ?? updateSequence,
+                        ...(update.total !== undefined ? { total: update.total } : {}),
+                        ...(progressMessage(update) ? { message: progressMessage(update) } : {}),
+                    },
+                }).catch(() => { }));
+            };
+        try {
+            const result = await tool.execute(toolCallId, preparedInput, extra.signal, onUpdate, {
+                ...executionDefaults,
+                piboSessionId: scope.piboSessionId,
+                piboRoomId: scope.piboRoomId,
+                profileName: scope.profileName,
+                cwd: scope.cwd,
+                runtimeInstanceId: scope.runtimeInstanceId,
+                adapterId: scope.adapterId,
+                sessionGeneration: scope.sessionGeneration,
+            });
+            await Promise.allSettled(pendingProgress);
+            if (tool.outputSchema && (result.structuredContent === undefined
+                || !Value.Check(tool.outputSchema, result.structuredContent))) {
+                throw new Error(`Tool "${tool.name}" returned structuredContent that does not match its output schema.`);
+            }
+            return await piboResultToMcp(result, {
+                scope,
+                tool,
+                toolCallId,
+                writer: this.options.payloadWriter,
+                threshold: this.options.largeResultThresholdBytes,
+                previewBytes: this.options.previewBytes,
+            });
+        }
+        catch (error) {
+            await Promise.allSettled(pendingProgress);
+            return {
+                content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
+                isError: true,
+                _meta: {
+                    piboSessionId: scope.piboSessionId,
+                    runtimeInstanceId: scope.runtimeInstanceId,
+                    adapterId: scope.adapterId,
+                    sessionGeneration: scope.sessionGeneration,
+                    toolCallId,
+                },
+            };
+        }
+    }
+    async createMcpSession(scope) {
+        const protocolServer = new McpProtocolServer({ name: this.options.serverName, version: this.options.serverVersion }, { capabilities: { tools: {} } });
+        let session;
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: randomUUID,
+            onsessioninitialized: (sessionId) => {
+                session.sessionId = sessionId;
+                this.mcpSessions.set(sessionId, session);
+            },
+            onsessionclosed: (sessionId) => {
+                this.mcpSessions.delete(sessionId);
+            },
+        });
+        session = {
+            credentialId: scope.credentialId,
+            piboSessionId: scope.piboSessionId,
+            sessionGeneration: scope.sessionGeneration,
+            protocolServer,
+            transport,
+        };
+        this.configureProtocolServer(protocolServer);
+        await protocolServer.connect(transport);
+        return session;
+    }
+    requestSessionId(request) {
+        const header = request.headers["mcp-session-id"];
+        return (Array.isArray(header) ? header[0] : header)?.trim() || undefined;
+    }
+    async handleRequest(request, response) {
+        if (request.url !== "/mcp") {
+            sendJson(response, 404, jsonRpcError(-32601, "Not found."));
+            return;
+        }
+        if (!request.method || !["POST", "GET", "DELETE"].includes(request.method)) {
+            sendJson(response, 405, jsonRpcError(-32600, "Unsupported MCP HTTP method."), { allow: "POST, GET, DELETE" });
+            return;
+        }
+        let scope;
+        try {
+            scope = await this.authenticate(request);
+        }
+        catch (error) {
+            const status = error instanceof PiboToolMcpBridgeAuthorizationError ? 403 : 401;
+            sendJson(response, status, jsonRpcError(-32001, error instanceof Error ? error.message : "Unauthorized."), {
+                "www-authenticate": "Bearer",
+            });
+            return;
+        }
+        let body;
+        if (request.method === "POST") {
+            try {
+                body = await readJsonBody(request, this.options.maxRequestBytes);
+            }
+            catch (error) {
+                sendJson(response, 400, jsonRpcError(-32700, error instanceof Error ? error.message : "Invalid JSON."));
+                return;
+            }
+        }
+        const sessionId = this.requestSessionId(request);
+        let session = sessionId ? this.mcpSessions.get(sessionId) : undefined;
+        if (sessionId && !session) {
+            sendJson(response, 404, jsonRpcError(-32001, "Unknown or closed MCP session."));
+            return;
+        }
+        if (session && session.credentialId !== scope.credentialId) {
+            sendJson(response, 403, jsonRpcError(-32001, "MCP session belongs to a different Pibo tool credential."));
+            return;
+        }
+        if (!session) {
+            if (request.method !== "POST" || !isInitializeRequest(body)) {
+                sendJson(response, 400, jsonRpcError(-32600, "An initialize request is required before using the MCP session."));
+                return;
+            }
+            session = await this.createMcpSession(scope);
+        }
+        await this.requestScope.run(scope, async () => {
+            await session.transport.handleRequest(request, response, body);
+        });
+    }
+}

package/dist/tools/payload-writer.js

@@ -0,0 +1,17 @@
+/** Adapt the shared durable PayloadStore for large portable tool results. */
+export function createPiboToolPayloadWriter(store) {
+    return {
+        write(input) {
+            const payload = store.writePayload({
+                value: input.value,
+                contentType: input.contentType,
+                retentionClass: "tool_result",
+            });
+            return {
+                ref: payload.id,
+                byteLength: payload.byteSize,
+                ...(payload.previewText ? { preview: payload.previewText } : {}),
+            };
+        },
+    };
+}

package/dist/tools/runtime/tool.js

@@ -1,5 +1,6 @@
-import { StringEnum, Type } from "@earendil-works/pi-ai";
-import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { piboStringEnum } from "../schema.js";
+import { definePiboTool } from "../contract.js";
 export function createRuntimeToolProfile() {
     return {
         name: "runtime",
@@ -93,24 +94,24 @@ function formatRuntimeResult(result) {
     return lines.join("\n");
 }
 export function createRuntimeToolDefinition(controller) {
-    return defineTool({
+    return definePiboTool({
         name: "runtime",
-        label: "Runtime",
+        title: "Runtime",
         description: "Run Python/Node code in persistent sessions. Use this instead of bash for Python/Node execution except trivial one-line shell checks.",
         promptSnippet: "Use runtime for Python/Node execution, especially longer snippets (~20+ lines), uncertain code, or objects/state to inspect. Prefer runtime over bash for Python/Node except trivial one-line shell checks. Auto-starts on exec; print values you need. Runtime keeps variables and processes alive between calls; reuse sessionId to inspect or continue from that state after partial failures. This saves output tokens and keeps your mental model tied to live state. Use read for file contents; use bash for shell commands and package installs.",
         executionMode: "parallel",
-        parameters: Type.Object({
-            action: StringEnum(["exec", "inspect", "vars", "interrupt", "list"], { description: "Runtime action to perform." }),
-            runtime: Type.Optional(StringEnum(["python", "node"], { description: "Runtime kind; default python." })),
+        inputSchema: Type.Object({
+            action: piboStringEnum(["exec", "inspect", "vars", "interrupt", "list"], { description: "Runtime action to perform." }),
+            runtime: Type.Optional(piboStringEnum(["python", "node"], { description: "Runtime kind; default python." })),
             name: Type.Optional(Type.String({ description: "Optional human-readable runtime name." })),
             target: Type.Optional(Type.Any({ description: "Auto-start target options such as { type: 'local', cwd, executable, args, env }." })),
             sessionId: Type.Optional(Type.String({ description: "Existing runtime session id; omit to use auto runtime." })),
             code: Type.Optional(Type.String({ description: "Code to execute for exec." })),
             timeoutMs: Type.Optional(Type.Number({ description: "Action timeout in milliseconds." })),
-            mode: Type.Optional(StringEnum(["exec", "eval", "auto"], { description: "For exec: execution mode. Use eval when you need an expression result." })),
+            mode: Type.Optional(piboStringEnum(["exec", "eval", "auto"], { description: "For exec: execution mode. Use eval when you need an expression result." })),
             closeOnSuccess: Type.Optional(Type.Boolean({ description: "For exec: close the runtime only if execution succeeds." })),
             expression: Type.Optional(Type.String({ description: "Expression to inspect." })),
-            what: Type.Optional(StringEnum(["summary", "signature", "members", "source", "doc", "all"], { description: "Inspection detail to return." })),
+            what: Type.Optional(piboStringEnum(["summary", "signature", "members", "source", "doc", "all"], { description: "Inspection detail to return." })),
             maxBytes: Type.Optional(Type.Number({ description: "Maximum bytes for summaries or inspect fields." })),
             includePrivate: Type.Optional(Type.Boolean({ description: "For vars: include private names." })),
             maxItems: Type.Optional(Type.Number({ description: "For vars: maximum variables to return." })),

package/dist/tools/schema.js

@@ -0,0 +1,9 @@
+import { Type } from "typebox";
+/** JSON-Schema string enum helper that does not depend on a harness SDK. */
+export function piboStringEnum(values, options = {}) {
+    return Type.Unsafe({
+        type: "string",
+        enum: [...values],
+        ...options,
+    });
+}