@tequila99/githuman 0.11.2 → 0.13.0

package/dist/server/adapters/pi-acp/control.js

@@ -0,0 +1,76 @@
+import { isRecord } from "../../../shared/utils/guards.js";
+// Large artifact pages can expand when escaped as JSON.
+export const MAX_CONTROL_BYTES = 16 * 1024 * 1024;
+// Bound permissions and outstanding RPC calls for one session.
+export const MAX_PENDING_CALLS = 64;
+// Startup must not leave a partial context alive indefinitely.
+export const BRIDGE_TIMEOUT_MS = 30000;
+// Version both peers together when the control contract changes.
+export const CONTROL_VERSION = 1;
+export class JsonChannel {
+    #buffer = Buffer.alloc(0);
+    #closed = false;
+    input;
+    output;
+    failed;
+    constructor(input, output, receive, failed) {
+        this.input = input;
+        this.output = output;
+        this.failed = failed;
+        input.on('data', (chunk) => {
+            if (this.#closed)
+                return;
+            if (this.#buffer.length + chunk.length > MAX_CONTROL_BYTES) {
+                return this.close(true);
+            }
+            this.#buffer = Buffer.concat([this.#buffer, chunk]);
+            let index;
+            while ((index = this.#buffer.indexOf(10)) >= 0) {
+                const line = this.#buffer.subarray(0, index);
+                this.#buffer = this.#buffer.subarray(index + 1);
+                try {
+                    const frame = JSON.parse(line.toString());
+                    if (!isRecord(frame) ||
+                        typeof frame.type !== 'string' ||
+                        typeof frame.nonce !== 'string' ||
+                        frame.version !== CONTROL_VERSION) {
+                        throw new Error('Invalid control frame');
+                    }
+                    receive({
+                        ...frame,
+                        type: frame.type,
+                        nonce: frame.nonce,
+                        version: CONTROL_VERSION
+                    });
+                }
+                catch {
+                    this.close(true);
+                    return;
+                }
+            }
+        });
+        input.on('end', () => this.close(true));
+        input.on('error', () => this.close(true));
+        output.on('error', () => this.close(true));
+    }
+    send(frame) {
+        if (this.#closed)
+            throw new Error('Pi control channel is closed');
+        const line = JSON.stringify(frame) + '\n';
+        if (Buffer.byteLength(line) > MAX_CONTROL_BYTES ||
+            this.output.writableLength > MAX_CONTROL_BYTES) {
+            throw new Error('Pi control output exceeds the limit');
+        }
+        this.output.write(line);
+    }
+    close(failure = false) {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#buffer = Buffer.alloc(0);
+        this.input.destroy();
+        this.output.destroy();
+        if (failure)
+            this.failed();
+    }
+}

package/dist/server/adapters/pi-acp/errors.js

@@ -0,0 +1,17 @@
+export function piFailureReason(message) {
+    if (typeof message !== 'string')
+        return 'Pi model request failed.';
+    if (/api.?key|unauthori[sz]ed|authenticat|\b40[13]\b/i.test(message)) {
+        return 'Pi model authorization failed. Check the installed pi configuration.';
+    }
+    if (/no model|model.*not found|model.*not available/i.test(message)) {
+        return 'Pi has no usable configured model. Check the installed pi configuration.';
+    }
+    if (/fetch|connect|ECONN|ENOTFOUND|network/i.test(message)) {
+        return 'Pi model connection failed. Check the installed pi endpoint.';
+    }
+    if (/rate.?limit|quota|\b429\b/i.test(message)) {
+        return 'Pi model provider limit was reached.';
+    }
+    return 'Pi model request failed. Check the installed pi configuration.';
+}

package/dist/server/adapters/pi-acp/extension.js

@@ -0,0 +1,255 @@
+/// <reference lib="es2024.promise" />
+import { Socket } from 'node:net';
+import { addAbortListener } from 'node:events';
+import { JsonChannel, CONTROL_VERSION, BRIDGE_TIMEOUT_MS, MAX_PENDING_CALLS } from "./control.js";
+import { isRecord } from "../../../shared/utils/guards.js";
+// Bound late-result tracking without retaining call arguments or results.
+const MAX_RETIRED_CALLS = 10000;
+export default async function extension(pi) {
+    const nonce = process.env.GITHUMAN_PI_NONCE ?? '';
+    delete process.env.GITHUMAN_PI_NONCE;
+    if (!nonce ||
+        typeof pi.registerTool !== 'function' ||
+        typeof pi.getAllTools !== 'function') {
+        throw new Error('Pi bridge extension capabilities are unavailable');
+    }
+    await initializePiExtension(pi, {
+        nonce,
+        input: new Socket({ fd: 4, readable: true, writable: false }),
+        output: new Socket({ fd: 3, readable: false, writable: true }),
+        exit: () => process.exit(1)
+    });
+}
+export async function initializePiExtension(pi, options) {
+    const { nonce } = options;
+    const pending = new Map();
+    const retired = new Set();
+    let generation = 0;
+    let configured = false;
+    let profile = '';
+    let instructions = '';
+    let names = new Set();
+    let registerTools;
+    let ready = false;
+    const configuration = Promise.withResolvers();
+    const shutdown = () => {
+        for (const request of pending.values()) {
+            request.reject(new Error('Pi bridge control channel closed'));
+        }
+        pending.clear();
+        return options.exit();
+    };
+    const channel = new JsonChannel(options.input, options.output, frame => {
+        if (frame.nonce !== nonce)
+            shutdown();
+        if (frame.type === 'configure') {
+            if (configured ||
+                !Array.isArray(frame.tools) ||
+                !['validator', 'chat'].includes(String(frame.profile)) ||
+                typeof frame.instructions !== 'string') {
+                shutdown();
+            }
+            configured = true;
+            profile = String(frame.profile);
+            instructions = frame.instructions;
+            const tools = frame.tools.filter(isRegistryTool);
+            if (tools.some(tool => !isRecord(tool) ||
+                typeof tool.name !== 'string' ||
+                typeof tool.description !== 'string' ||
+                !isRecord(tool.inputSchema))) {
+                shutdown();
+            }
+            names = new Set(tools.map(tool => tool.name));
+            if (names.size !== tools.length)
+                shutdown();
+            registerTools = () => {
+                for (const tool of tools) {
+                    pi.registerTool({
+                        name: tool.name,
+                        label: tool.name,
+                        description: tool.description,
+                        parameters: tool.inputSchema,
+                        execute: async (id, toolInput, signal) => {
+                            if (!generation ||
+                                pending.size >= MAX_PENDING_CALLS ||
+                                signal?.aborted) {
+                                throw new Error('Pi bridge call is not active');
+                            }
+                            const callGeneration = generation;
+                            const key = `${callGeneration}:${id}`;
+                            if (pending.has(key) || retired.has(key)) {
+                                throw new Error('Duplicate pi bridge call ID');
+                            }
+                            const response = Promise.withResolvers();
+                            let abortListener;
+                            let settled = false;
+                            const timer = setTimeout(() => reject(new Error('Pi bridge tool deadline exceeded')), BRIDGE_TIMEOUT_MS);
+                            const cleanup = () => {
+                                clearTimeout(timer);
+                                abortListener?.[Symbol.dispose]();
+                                pending.delete(key);
+                            };
+                            function reject(error) {
+                                if (settled)
+                                    return;
+                                settled = true;
+                                // A timed-out or cancelled call can still receive one backend response.
+                                retired.add(key);
+                                if (retired.size > MAX_RETIRED_CALLS) {
+                                    retired.delete(retired.values().next().value);
+                                }
+                                cleanup();
+                                response.reject(error);
+                            }
+                            pending.set(key, {
+                                resolve: value => {
+                                    if (settled)
+                                        return;
+                                    settled = true;
+                                    cleanup();
+                                    response.resolve(value);
+                                },
+                                reject
+                            });
+                            let result;
+                            try {
+                                try {
+                                    if (signal) {
+                                        abortListener = addAbortListener(signal, () => reject(new Error('Pi bridge call cancelled')));
+                                    }
+                                    send('call', {
+                                        id,
+                                        generation: callGeneration,
+                                        name: tool.name,
+                                        arguments: toolInput
+                                    });
+                                }
+                                catch (error) {
+                                    settled = true;
+                                    cleanup();
+                                    response.reject(error);
+                                }
+                                result = await response.promise;
+                            }
+                            finally {
+                                cleanup();
+                            }
+                            if (generation !== callGeneration ||
+                                signal?.aborted ||
+                                !isRecord(result) ||
+                                !Array.isArray(result.content)) {
+                                throw new Error('Pi bridge returned a stale or malformed result');
+                            }
+                            if (result.isError === true) {
+                                throw new Error(result.content
+                                    .filter(isRecord)
+                                    .map(block => block.type === 'text' ? String(block.text) : '')
+                                    .join('\n') || 'MCP tool failed');
+                            }
+                            const content = result.content.filter(isRecord).map(block => {
+                                if (block.type === 'text' || block.type === 'image') {
+                                    return block;
+                                }
+                                if (block.type === 'resource' &&
+                                    isRecord(block.resource) &&
+                                    typeof block.resource.text === 'string') {
+                                    return { type: 'text', text: block.resource.text };
+                                }
+                                return { type: 'text', text: JSON.stringify(block) };
+                            });
+                            return {
+                                content,
+                                details: { structuredContent: result.structuredContent }
+                            };
+                        }
+                    });
+                }
+            };
+            configuration.resolve();
+        }
+        else if (frame.type === 'begin') {
+            if (!configured ||
+                !Number.isSafeInteger(frame.generation) ||
+                Number(frame.generation) <= generation) {
+                shutdown();
+            }
+            generation = Number(frame.generation);
+            send('begun', { generation });
+        }
+        else if (frame.type === 'cancel') {
+            generation = 0;
+            for (const request of pending.values()) {
+                request.reject(new Error('Pi bridge call cancelled'));
+            }
+            pending.clear();
+        }
+        else if (frame.type === 'result') {
+            if (typeof frame.id !== 'string' ||
+                !Number.isSafeInteger(frame.generation)) {
+                shutdown();
+            }
+            const key = `${String(frame.generation)}:${frame.id}`;
+            // Only calls already rejected locally may have a harmless late result.
+            if (retired.delete(key))
+                return;
+            if (frame.generation !== generation)
+                shutdown();
+            const request = pending.get(key);
+            if (!request)
+                shutdown();
+            request.resolve(frame.result);
+        }
+        else {
+            shutdown();
+        }
+    }, shutdown);
+    function send(type, fields = {}) {
+        channel.send({ ...fields, type, nonce, version: CONTROL_VERSION });
+    }
+    const timer = setTimeout(shutdown, BRIDGE_TIMEOUT_MS);
+    try {
+        send('hello');
+        await configuration.promise;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    pi.on('session_start', () => {
+        if (ready) {
+            send('fatal', { reason: 'reload' });
+            shutdown();
+        }
+        ready = true;
+        const all = pi.getAllTools().map(tool => tool.name);
+        if ([...names].some(name => all.includes(name))) {
+            send('fatal', { reason: 'tool_name_collision' });
+            shutdown();
+        }
+        registerTools?.();
+        if (profile === 'validator')
+            pi.setActiveTools([...names]);
+        send('ready', { profile, registryGeneration: 1 });
+    });
+    // Only validator installs a native/custom tool guard. MCP approval lives in execute.
+    if (profile === 'validator') {
+        pi.on('tool_call', event => names.has(String(event.toolName))
+            ? undefined
+            : {
+                block: true,
+                reason: 'Validator denies tools outside its immutable MCP registry.'
+            });
+    }
+    pi.on('before_agent_start', event => ({
+        systemPrompt: `${String(event.systemPrompt)}\n\n${instructions}`
+    }));
+    pi.on('session_shutdown', shutdown);
+}
+function isRegistryTool(value) {
+    return (isRecord(value) &&
+        typeof value.name === 'string' &&
+        typeof value.description === 'string' &&
+        typeof value.server === 'string' &&
+        typeof value.originalName === 'string' &&
+        isRecord(value.inputSchema) &&
+        value.inputSchema.type === 'object');
+}

package/dist/server/adapters/pi-acp/launch.js

@@ -0,0 +1,16 @@
+import { fileURLToPath } from 'node:url';
+export function localPiLaunch() {
+    const entry = import.meta.url.endsWith('.ts')
+        ? '../../../cli/index.ts'
+        : '../../../cli/index.js';
+    return {
+        command: process.execPath,
+        args: [fileURLToPath(new URL(entry, import.meta.url)), 'pi-acp', '--stdio']
+    };
+}
+export function isLocalPiLaunch(preset) {
+    const trusted = localPiLaunch();
+    return (preset.command === trusted.command &&
+        preset.args.length === trusted.args.length &&
+        preset.args.every((arg, index) => arg === trusted.args[index]));
+}

package/dist/server/adapters/pi-acp/mcp.js

@@ -0,0 +1,153 @@
+import { terminateProcesses } from "../../services/terminal/processes.js";
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { AjvJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/ajv-provider.js';
+import { isRecord } from "../../../shared/utils/guards.js";
+import { BRIDGE_TIMEOUT_MS } from "./control.js";
+// Bound discovery across pages and servers before exposing any tools.
+const MAX_TOOLS = 512;
+// Repeated or excessive cursors cannot keep session/new pending.
+const MAX_PAGES = 32;
+// pi's built-in tool names must never resolve to MCP backends.
+const BUILTIN_NAMES = new Set([
+    'read',
+    'write',
+    'edit',
+    'bash',
+    'powershell',
+    'grep',
+    'find',
+    'ls',
+    'tool_search',
+    'codemode'
+]);
+function isValidMcpName(name) {
+    return /^[a-zA-Z0-9_-]+$/.test(name);
+}
+export class McpRegistry {
+    #entries = new Map();
+    #clients = [];
+    #transports = [];
+    #instructions = [];
+    #closed = false;
+    onFailure = () => { };
+    get tools() {
+        return structuredClone([...this.#entries.values()].map(entry => entry.descriptor));
+    }
+    get instructions() {
+        return this.#instructions.join('\n\n');
+    }
+    async connect(servers) {
+        if (servers.length > 8)
+            throw new Error('Too many pi MCP servers');
+        const names = new Set();
+        const schemas = new AjvJsonSchemaValidator();
+        try {
+            for (const server of servers) {
+                if ('type' in server ||
+                    !isValidMcpName(server.name) ||
+                    names.has(server.name)) {
+                    throw new Error('Pi bridge requires unique server-owned stdio MCP descriptors');
+                }
+                names.add(server.name);
+                const env = {};
+                for (const entry of server.env) {
+                    if (Object.hasOwn(env, entry.name)) {
+                        throw new Error('Duplicate MCP environment variable');
+                    }
+                    env[entry.name] = entry.value;
+                }
+                const transport = new StdioClientTransport({
+                    command: server.command,
+                    args: [...server.args],
+                    env,
+                    maxBufferSize: 16 * 1024 * 1024,
+                    stderr: 'pipe'
+                });
+                this.#transports.push(transport);
+                const client = new Client({ name: 'githuman-pi-bridge', version: '1' });
+                this.#clients.push(client);
+                // oxlint-disable-next-line unicorn/prefer-add-event-listener -- MCP Client exposes onclose as a callback property.
+                client.onclose = () => {
+                    if (!this.#closed)
+                        this.onFailure();
+                };
+                transport.stderr?.on('data', () => { });
+                await client.connect(transport, { timeout: BRIDGE_TIMEOUT_MS });
+                const instructions = client.getInstructions();
+                if (instructions)
+                    this.#instructions.push(instructions);
+                const cursors = new Set();
+                let cursor;
+                for (let page = 0;; page++) {
+                    if (page >= MAX_PAGES) {
+                        throw new Error('MCP tools/list page limit exceeded');
+                    }
+                    const response = await client.listTools(cursor ? { cursor } : {}, {
+                        timeout: BRIDGE_TIMEOUT_MS
+                    });
+                    for (const tool of response.tools) {
+                        const name = `mcp__${server.name}__${tool.name}`;
+                        if (!isValidMcpName(tool.name) ||
+                            name.length > 128 ||
+                            BUILTIN_NAMES.has(tool.name) ||
+                            this.#entries.has(name) ||
+                            this.#entries.size >= MAX_TOOLS) {
+                            throw new Error('MCP tool name collision or registry limit exceeded');
+                        }
+                        const descriptor = structuredClone({
+                            name,
+                            description: tool.description ?? tool.name,
+                            inputSchema: tool.inputSchema,
+                            server: server.name,
+                            originalName: tool.name
+                        });
+                        this.#entries.set(name, {
+                            descriptor,
+                            client,
+                            validate: schemas.getValidator(descriptor.inputSchema)
+                        });
+                    }
+                    cursor = response.nextCursor;
+                    if (!cursor)
+                        break;
+                    if (cursors.has(cursor)) {
+                        throw new Error('MCP tools/list repeated a cursor');
+                    }
+                    cursors.add(cursor);
+                }
+            }
+        }
+        catch (error) {
+            await this.close();
+            throw error;
+        }
+    }
+    snapshot(name, input) {
+        const entry = this.#entries.get(name);
+        if (!entry || !isRecord(input)) {
+            throw new Error('Unknown MCP tool or invalid arguments');
+        }
+        const args = JSON.parse(JSON.stringify(input));
+        if (!isRecord(args) || !entry.validate(args).valid) {
+            throw new Error('MCP arguments do not match the registered schema');
+        }
+        return { descriptor: structuredClone(entry.descriptor), arguments: args };
+    }
+    async call(name, args, signal) {
+        const entry = this.#entries.get(name);
+        if (!entry || this.#closed || signal.aborted) {
+            throw new Error('MCP call is no longer active');
+        }
+        return entry.client.callTool({ name: entry.descriptor.originalName, arguments: args }, undefined, { signal, timeout: BRIDGE_TIMEOUT_MS });
+    }
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        await Promise.allSettled(this.#transports.map(transport => transport.pid ? terminateProcesses(transport.pid) : Promise.resolve()));
+        await Promise.allSettled(this.#clients.map(client => client.close()));
+        await Promise.allSettled(this.#transports.map(transport => transport.close()));
+        this.#entries.clear();
+    }
+}