@tequila99/githuman 0.11.0 → 0.12.0

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();
+    }
+}

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

@@ -0,0 +1,199 @@
+import { piFailureReason } from "./errors.js";
+import { terminateProcesses } from "../../services/terminal/processes.js";
+import { spawn } from 'node:child_process';
+import { randomBytes, randomUUID } from 'node:crypto';
+import { Socket } from 'node:net';
+import { fileURLToPath } from 'node:url';
+import { JsonChannel, CONTROL_VERSION, BRIDGE_TIMEOUT_MS, MAX_CONTROL_BYTES, MAX_PENDING_CALLS } from "./control.js";
+import { piLaunchArgs } from "./compatibility.js";
+import { isRecord } from "../../../shared/utils/guards.js";
+export class PiProcess {
+    #pending = new Map();
+    #nonce = randomBytes(32).toString('hex');
+    #child;
+    #channel;
+    #closed = false;
+    #rpcBuffer = Buffer.alloc(0);
+    #hello = false;
+    #ready = false;
+    onControl = () => { };
+    onEvent = () => { };
+    onFailure = () => { };
+    async start(cwd, profile, config, env = process.env) {
+        const command = env.PI_ACP_PI_COMMAND || 'pi';
+        const extension = fileURLToPath(new URL(import.meta.url.endsWith('.ts') ? './extension.ts' : './extension.js', import.meta.url));
+        const args = await piLaunchArgs(command, profile, extension);
+        if (this.#closed) {
+            throw new Error('Pi bridge closed during runtime discovery');
+        }
+        const piEnv = { ...env, GITHUMAN_PI_NONCE: this.#nonce };
+        for (const key of [
+            'GITHUMAN_AGENT_KEY',
+            'GITHUMAN_AGENT_URL',
+            'GITHUMAN_PI_PROFILE'
+        ]) {
+            delete piEnv[key];
+        }
+        const child = spawn(command, args, {
+            cwd,
+            env: piEnv,
+            stdio: ['pipe', 'pipe', 'pipe', 'pipe', 'pipe'],
+            detached: true
+        });
+        this.#child = child;
+        child.stdin.on('error', () => this.fail());
+        child.stderr.resume();
+        child.on('error', () => this.fail());
+        child.on('exit', () => this.fail());
+        const startup = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new Error('Pi bridge startup deadline exceeded'));
+                this.fail();
+            }, BRIDGE_TIMEOUT_MS);
+            this.#pending.set('startup', {
+                resolve: () => {
+                    clearTimeout(timer);
+                    resolve();
+                },
+                reject: error => {
+                    clearTimeout(timer);
+                    reject(error);
+                }
+            });
+        });
+        const requestPipe = child.stdio[3];
+        const responsePipe = child.stdio[4];
+        if (!(requestPipe instanceof Socket) || !(responsePipe instanceof Socket)) {
+            throw new Error('Pi control pipes unavailable');
+        }
+        this.#channel = new JsonChannel(requestPipe, responsePipe, frame => {
+            if (frame.nonce !== this.#nonce)
+                return this.fail();
+            if (frame.type === 'fatal') {
+                this.fail(frame.reason === 'tool_name_collision'
+                    ? 'Pi MCP tool name collision with an installed extension.'
+                    : 'Pi extension reload requires a new chat.');
+                return;
+            }
+            if (frame.type === 'hello') {
+                if (this.#hello)
+                    return this.fail();
+                this.#hello = true;
+                this.send('configure', { ...config, profile });
+            }
+            else if (frame.type === 'ready') {
+                if (!this.#hello ||
+                    this.#ready ||
+                    frame.profile !== profile ||
+                    frame.registryGeneration !== 1) {
+                    return this.fail();
+                }
+                this.#ready = true;
+                this.#pending.get('startup')?.resolve({});
+                this.#pending.delete('startup');
+            }
+            else if (this.#ready) {
+                this.onControl(frame);
+            }
+            else {
+                this.fail();
+            }
+        }, () => this.fail());
+        child.stdout.on('data', (chunk) => this.readRpc(chunk));
+        await startup;
+    }
+    send(type, fields = {}) {
+        if (!this.#channel || this.#closed) {
+            throw new Error('Pi bridge control channel unavailable');
+        }
+        this.#channel.send({
+            ...fields,
+            type,
+            nonce: this.#nonce,
+            version: CONTROL_VERSION
+        });
+    }
+    request(type, fields = {}) {
+        if (this.#closed ||
+            !this.#child?.stdin ||
+            this.#pending.size >= MAX_PENDING_CALLS) {
+            return Promise.reject(new Error('Pi RPC unavailable or pending limit exceeded'));
+        }
+        const id = randomUUID();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.#pending.delete(id);
+                reject(new Error('Pi RPC deadline exceeded'));
+                this.fail();
+            }, type === 'prompt' ? 300000 : BRIDGE_TIMEOUT_MS);
+            this.#pending.set(id, {
+                resolve: value => {
+                    clearTimeout(timer);
+                    this.#pending.delete(id);
+                    resolve(value);
+                },
+                reject: error => {
+                    clearTimeout(timer);
+                    this.#pending.delete(id);
+                    reject(error);
+                }
+            });
+            this.#child.stdin.write(JSON.stringify({ ...fields, type, id }) + '\n');
+        });
+    }
+    readRpc(chunk) {
+        if (this.#rpcBuffer.length + chunk.length > MAX_CONTROL_BYTES) {
+            return this.fail();
+        }
+        this.#rpcBuffer = Buffer.concat([this.#rpcBuffer, chunk]);
+        let index;
+        while ((index = this.#rpcBuffer.indexOf(10)) >= 0) {
+            const line = this.#rpcBuffer.subarray(0, index).toString();
+            this.#rpcBuffer = this.#rpcBuffer.subarray(index + 1);
+            let event;
+            try {
+                event = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (!isRecord(event))
+                return this.fail();
+            if (event.type === 'response') {
+                const request = this.#pending.get(String(event.id));
+                if (request) {
+                    if (event.success === true) {
+                        request.resolve(isRecord(event.data) ? event.data : {});
+                    }
+                    else {
+                        request.reject(new Error(piFailureReason(event.error)));
+                    }
+                }
+            }
+            else {
+                this.onEvent(event);
+            }
+        }
+    }
+    fail(reason) {
+        if (this.#closed)
+            return;
+        this.close(reason);
+        this.onFailure();
+    }
+    close(reason = 'Pi bridge process or control channel closed') {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        for (const pending of this.#pending.values()) {
+            pending.reject(new Error(reason));
+        }
+        this.#pending.clear();
+        const child = this.#child;
+        if (!child?.pid) {
+            this.#channel?.close();
+            return;
+        }
+        void terminateProcesses(child.pid).finally(() => this.#channel?.close());
+    }
+}