@tequila99/githuman 0.11.2 → 0.12.0

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

@@ -0,0 +1,409 @@
+import { piFailureReason } from "./errors.js";
+import { promptToPiMessage } from "./vendor/prompt.js";
+import { randomUUID } from 'node:crypto';
+import { McpRegistry } from "./mcp.js";
+import { PiProcess } from "./process.js";
+import { BRIDGE_TIMEOUT_MS, MAX_PENDING_CALLS } from "./control.js";
+import { ARTIFACT_TASK_INSTRUCTIONS } from "../../../shared/artifact-tools/instructions.js";
+import { isRecord } from "../../../shared/utils/guards.js";
+export class PiSession {
+    id = randomUUID();
+    registry = new McpRegistry();
+    process = new PiProcess();
+    #generation = 0;
+    #turn;
+    #seen = new Set();
+    #pending = 0;
+    #ready = false;
+    #closed = false;
+    #cancelled = false;
+    #stopReason = 'end_turn';
+    #agentStarted = false;
+    #thinking = [];
+    #completion;
+    #begun;
+    #models = [];
+    #state = {};
+    profile;
+    callbacks;
+    constructor(profile, callbacks) {
+        this.profile = profile;
+        this.callbacks = callbacks;
+        const failure = () => {
+            const wasReady = this.#ready;
+            this.close();
+            if (wasReady)
+                callbacks.failure();
+        };
+        this.process.onFailure = failure;
+        this.registry.onFailure = failure;
+        this.process.onControl = frame => {
+            if (frame.type === 'begun' &&
+                frame.generation === this.#generation &&
+                this.#begun) {
+                this.#begun();
+                this.#begun = undefined;
+            }
+            else if (frame.type === 'call') {
+                void this.call(frame).catch(failure);
+            }
+            else {
+                failure();
+            }
+        };
+        this.process.onEvent = event => {
+            void this.event(event).catch(failure);
+        };
+    }
+    async start(cwd, servers) {
+        try {
+            await this.registry.connect(servers);
+            if (this.#closed)
+                throw new Error('Pi bridge closed during discovery');
+            await this.process.start(cwd, this.profile, {
+                tools: this.registry.tools,
+                instructions: `${this.registry.instructions}\n\n${ARTIFACT_TASK_INSTRUCTIONS}`
+            });
+            this.#state = await this.process.request('get_state');
+            if (!isRecord(this.#state.model)) {
+                throw new Error('Pi bridge requires a configured model and authorization in the installed pi');
+            }
+            const available = await this.process.request('get_available_models');
+            if (!Array.isArray(available.models)) {
+                throw new Error('Pi runtime did not return its model catalog');
+            }
+            this.#models = available.models.filter(isRecord).flatMap(model => typeof model.id === 'string' && typeof model.provider === 'string'
+                ? [
+                    {
+                        id: model.id,
+                        provider: model.provider,
+                        name: typeof model.name === 'string' ? model.name : model.id
+                    }
+                ]
+                : []);
+            await this.refreshThinking();
+            this.#ready = true;
+        }
+        catch (error) {
+            this.close();
+            throw error;
+        }
+    }
+    assertSession(id) {
+        if (!this.#ready || this.#closed || id !== this.id) {
+            throw new Error('Unknown or unavailable pi session');
+        }
+    }
+    get config() {
+        const model = this.#state.model;
+        const options = [
+            {
+                type: 'select',
+                id: 'thought_level',
+                category: 'thought_level',
+                name: 'Thinking',
+                currentValue: String(this.#state.thinkingLevel),
+                options: this.#thinking.map(value => ({ value, name: value }))
+            }
+        ];
+        if (!isRecord(model) || !this.#models.length)
+            return options;
+        return [
+            ...options,
+            {
+                type: 'select',
+                id: 'model',
+                category: 'model',
+                name: 'Model',
+                currentValue: `${String(model.provider)}/${String(model.id)}`,
+                options: this.#models.map(value => ({
+                    value: `${value.provider}/${value.id}`,
+                    name: value.name
+                }))
+            }
+        ];
+    }
+    async setConfig(id, value) {
+        if (this.#turn) {
+            throw new Error('Pi setting is unavailable');
+        }
+        if (id === 'thought_level' && this.#thinking.includes(value)) {
+            await this.process.request('set_thinking_level', { level: value });
+            this.#state = await this.process.request('get_state');
+            return;
+        }
+        if (id !== 'model')
+            throw new Error('Unknown pi setting');
+        const model = this.#models.find(candidate => `${candidate.provider}/${candidate.id}` === value);
+        if (!model)
+            throw new Error('Unknown pi model');
+        await this.process.request('set_model', {
+            provider: model.provider,
+            modelId: model.id
+        });
+        this.#state = await this.process.request('get_state');
+        await this.refreshThinking();
+    }
+    async refreshThinking() {
+        const thinking = await this.process.request('get_available_thinking_levels');
+        if (!Array.isArray(thinking.levels) ||
+            !thinking.levels.every(value => typeof value === 'string')) {
+            throw new Error('Pi thinking levels unavailable');
+        }
+        this.#thinking = thinking.levels;
+    }
+    async prompt(blocks) {
+        if (this.#turn || !this.#ready || this.#closed) {
+            throw new Error('Pi session is not ready for a prompt');
+        }
+        const { message, images } = promptToPiMessage(blocks);
+        if (this.profile === 'validator' && message.trimStart().startsWith('/')) {
+            throw new Error('Validator slash commands are unavailable');
+        }
+        if (/^\s*\/reload(?:\s|$)/.test(message)) {
+            throw new Error('Pi bridge reload requires a new chat');
+        }
+        const turn = new AbortController();
+        this.#turn = turn;
+        this.#generation++;
+        this.#cancelled = false;
+        this.#agentStarted = false;
+        this.#stopReason = 'end_turn';
+        this.#seen.clear();
+        try {
+            await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    this.#begun = undefined;
+                    reject(new Error('Pi turn control acknowledgement timed out'));
+                }, BRIDGE_TIMEOUT_MS);
+                this.#begun = () => {
+                    clearTimeout(timer);
+                    resolve();
+                };
+                this.process.send('begin', { generation: this.#generation });
+            });
+            if (turn.signal.aborted)
+                return { stopReason: 'cancelled' };
+            const completion = new Promise((resolve, reject) => {
+                this.#completion = { resolve, reject };
+            });
+            completion.catch(() => { });
+            const deadline = setTimeout(() => {
+                this.#completion?.reject(new Error('Pi turn deadline exceeded'));
+                this.close();
+            }, 300000);
+            try {
+                await this.process.request('prompt', { message, images });
+                if (message.trimStart().startsWith('/') && !this.#agentStarted) {
+                    this.#completion?.resolve();
+                }
+                await completion;
+            }
+            finally {
+                clearTimeout(deadline);
+                this.#completion = undefined;
+            }
+            return {
+                stopReason: this.#cancelled ? 'cancelled' : this.#stopReason
+            };
+        }
+        catch (error) {
+            if (this.#cancelled)
+                return { stopReason: 'cancelled' };
+            throw error;
+        }
+        finally {
+            turn.abort();
+            this.#turn = undefined;
+            this.#seen.clear();
+        }
+    }
+    async cancel() {
+        if (!this.#turn)
+            return;
+        this.#cancelled = true;
+        this.#turn.abort();
+        this.process.send('cancel', { generation: this.#generation });
+        await this.process.request('abort');
+    }
+    async call(frame) {
+        const turn = this.#turn;
+        if (!turn ||
+            turn.signal.aborted ||
+            frame.generation !== this.#generation ||
+            typeof frame.id !== 'string' ||
+            typeof frame.name !== 'string' ||
+            this.#seen.has(frame.id) ||
+            this.#seen.size >= 10000 ||
+            this.#pending >= MAX_PENDING_CALLS) {
+            throw new Error('Invalid, repeated or stale pi call');
+        }
+        this.#seen.add(frame.id);
+        this.#pending++;
+        const generation = this.#generation;
+        const id = frame.id;
+        let result;
+        try {
+            const snapshot = this.registry.snapshot(frame.name, frame.arguments);
+            const signal = AbortSignal.any([
+                turn.signal,
+                AbortSignal.timeout(BRIDGE_TIMEOUT_MS)
+            ]);
+            const permissionRequest = this.callbacks.permission({
+                sessionId: this.id,
+                toolCall: {
+                    toolCallId: id,
+                    title: snapshot.descriptor.name,
+                    name: snapshot.descriptor.name,
+                    kind: 'execute',
+                    rawInput: structuredClone(snapshot.arguments),
+                    _meta: {
+                        githumanPi: {
+                            server: snapshot.descriptor.server,
+                            tool: snapshot.descriptor.originalName,
+                            registryGeneration: 1
+                        }
+                    }
+                },
+                options: [
+                    { optionId: 'allow_once', name: 'Allow once', kind: 'allow_once' },
+                    {
+                        optionId: 'reject_once',
+                        name: 'Reject once',
+                        kind: 'reject_once'
+                    }
+                ]
+            }, signal);
+            let abortPermission;
+            let permission;
+            try {
+                permission = await Promise.race([
+                    permissionRequest,
+                    new Promise((_resolve, reject) => {
+                        abortPermission = () => reject(new Error('Pi permission deadline exceeded or call cancelled'));
+                        if (signal.aborted) {
+                            abortPermission();
+                        }
+                        else {
+                            signal.addEventListener('abort', abortPermission, { once: true });
+                        }
+                    })
+                ]);
+            }
+            finally {
+                if (abortPermission) {
+                    signal.removeEventListener('abort', abortPermission);
+                }
+            }
+            if (signal.aborted ||
+                turn !== this.#turn ||
+                generation !== this.#generation ||
+                permission.outcome.outcome !== 'selected' ||
+                permission.outcome.optionId !== 'allow_once') {
+                throw new Error('Pi MCP permission denied or cancelled');
+            }
+            result = await this.registry.call(frame.name, snapshot.arguments, signal);
+        }
+        catch {
+            result = {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Pi MCP call failed, was denied, or was cancelled.'
+                    }
+                ]
+            };
+        }
+        finally {
+            this.#pending--;
+        }
+        if (!this.#closed &&
+            turn === this.#turn &&
+            !turn.signal.aborted &&
+            generation === this.#generation) {
+            this.process.send('result', { id, generation, result });
+        }
+    }
+    async event(event) {
+        if (!this.#turn)
+            return;
+        if (event.type === 'agent_start')
+            this.#agentStarted = true;
+        if (event.type === 'message_end' && isRecord(event.message)) {
+            if (event.message.stopReason === 'length')
+                this.#stopReason = 'max_tokens';
+            if (event.message.stopReason === 'refusal')
+                this.#stopReason = 'refusal';
+        }
+        if (event.type === 'agent_end') {
+            this.#completion?.resolve();
+            return;
+        }
+        if (event.type === 'message_end' &&
+            isRecord(event.message) &&
+            event.message.stopReason === 'error') {
+            this.#completion?.reject(new Error(piFailureReason(event.message.errorMessage)));
+            return;
+        }
+        if (this.#turn.signal.aborted)
+            return;
+        let update;
+        if (event.type === 'message_update' &&
+            isRecord(event.assistantMessageEvent)) {
+            const delta = event.assistantMessageEvent;
+            if ((delta.type === 'text_delta' || delta.type === 'thinking_delta') &&
+                typeof delta.delta === 'string') {
+                update = {
+                    sessionUpdate: delta.type === 'text_delta'
+                        ? 'agent_message_chunk'
+                        : 'agent_thought_chunk',
+                    content: { type: 'text', text: delta.delta }
+                };
+            }
+        }
+        else if (event.type === 'tool_execution_start' &&
+            typeof event.toolCallId === 'string') {
+            update = {
+                sessionUpdate: 'tool_call',
+                toolCallId: event.toolCallId,
+                title: String(event.toolName),
+                name: String(event.toolName),
+                rawInput: event.args,
+                status: 'in_progress',
+                kind: 'execute'
+            };
+        }
+        else if (event.type === 'tool_execution_end' &&
+            typeof event.toolCallId === 'string') {
+            const result = event.result;
+            const content = isRecord(result) && Array.isArray(result.content)
+                ? result.content.filter(isRecord).flatMap(block => block.type === 'text' && typeof block.text === 'string'
+                    ? [
+                        {
+                            type: 'content',
+                            content: { type: 'text', text: block.text }
+                        }
+                    ]
+                    : [])
+                : [];
+            update = {
+                sessionUpdate: 'tool_call_update',
+                toolCallId: event.toolCallId,
+                status: event.isError ? 'failed' : 'completed',
+                content
+            };
+        }
+        if (update)
+            await this.callbacks.update(this.id, update);
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#turn?.abort();
+        this.#completion?.reject(new Error('Pi session closed'));
+        this.process.close();
+        void this.registry.close();
+    }
+}

package/dist/server/adapters/pi-acp/vendor/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sergii Kozak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/server/adapters/pi-acp/vendor/README.md

@@ -0,0 +1,29 @@
+# pi-acp provenance
+
+Baseline: published MIT pi-acp@0.0.34 tarball, compared to upstream commit
+04d0a15d6bb42bb65cce5c9caedcdcb2cdcb6905 before reuse.
+
+Tarball: https://registry.npmjs.org/pi-acp/-/pi-acp-0.0.34.tgz
+SHA-256: 4b3bf6bc71bed2b7f43dd7fcfa1906e464828e471740da593107e4f1608f2650
+SHA-512 (npm integrity): MrCp37UbpUzkTkzTIMJQf1RYrT+kr4fgGDGFoLmBN26UupuCZp0XxVIY+7XYsMo3yDnzDeZUJ0jPyM3Si6Bkkg==
+Published bundle SHA-256: 324aeb8bba1228937e16b1326fb3e014e2a625b2dea549dbcd49b006cd5df6a2
+
+The tarball source map has 17 sources. Four differ from the git commit:
+acp/agent.ts, acp/session.ts, acp/pi-sessions.ts, acp/translate/prompt.ts.
+The published tarball is the selected baseline, including prompt.ts.
+
+| Layer                                           | Local difference                                                       |
+| ----------------------------------------------- | ---------------------------------------------------------------------- |
+| prompt.ts                                       | Formatting and comment conventions; imported from published source map |
+| ACP agent/session                               | New SDK 1.5 builder API; one session; no restore/history handlers      |
+| RPC process                                     | New bounded transport; no session files; no Windows launchers          |
+| MCP/control/permissions                         | New GitHuman-owned registry, extension and ACP gate                    |
+| Upstream history, session store, slash commands | Excluded                                                               |
+
+Keep LICENSE with the redistributed prompt conversion code. Runtime npx and
+pi SDK dependencies are not required. Maintainers compare upstream changes
+when supported pi versions or upstream security fixes change. Reconsider the
+SDK-runtime ADR if the fork can no longer be reviewed as a bounded change.
+
+macOS verification was explicitly skipped by the user because no host was
+available. Linux tests do not establish macOS support.

package/dist/server/adapters/pi-acp/vendor/prompt.js

@@ -0,0 +1,56 @@
+export function promptToPiMessage(blocks) {
+    let message = '';
+    const images = [];
+    for (const b of blocks) {
+        switch (b.type) {
+            case 'text':
+                message += b.text;
+                break;
+            case 'resource_link':
+                // A lightweight, human-readable hint for the LLM.
+                message += `\n[Context] ${b.uri}`;
+                break;
+            case 'image': {
+                // pi expects base64 image bytes in `data` without a data-url prefix.
+                images.push({
+                    type: 'image',
+                    mimeType: b.mimeType,
+                    data: b.data
+                });
+                break;
+            }
+            case 'resource': {
+                // Clients should not send this if embeddedContext=false, but be resilient.
+                const r = b.resource;
+                const uri = typeof r?.uri === 'string' ? r.uri : '(unknown)';
+                if ('text' in r && typeof r.text === 'string') {
+                    // TextResourceContents
+                    const mime = typeof r?.mimeType === 'string' ? r.mimeType : 'text/plain';
+                    message += `\n[Embedded Context] ${uri} (${mime})\n${r.text}`;
+                }
+                else if ('blob' in r && typeof r.blob === 'string') {
+                    // BlobResourceContents
+                    const mime = typeof r?.mimeType === 'string'
+                        ? r.mimeType
+                        : 'application/octet-stream';
+                    const bytes = Buffer.byteLength(r.blob, 'base64');
+                    message += `\n[Embedded Context] ${uri} (${mime}, ${bytes} bytes)`;
+                }
+                else {
+                    message += `\n[Embedded Context] ${uri}`;
+                }
+                break;
+            }
+            case 'audio': {
+                // Not supported by pi. Provide a marker so we don't silently drop context.
+                const bytes = Buffer.byteLength(b.data, 'base64');
+                message += `\n[Audio] (${b.mimeType}, ${bytes} bytes) not supported by pi-acp`;
+                break;
+            }
+            default:
+                // Ignore unknown block types for now.
+                break;
+        }
+    }
+    return { message, images };
+}

package/dist/server/app.js

@@ -1,3 +1,13 @@
+import { artifactActionRoutes } from "./routes/artifact-actions.js";
+import { artifactTransitionRoutes } from "./routes/artifact-transitions.js";
+import { addressUrl } from "../shared/network/address-url.js";
+import { artifactAgentRoutes } from "./routes/artifact-agent.js";
+import { ForbiddenError } from "./errors/http.js";
+import { artifactDefinitionRoutes } from "./routes/artifact-definitions.js";
+import { DEFAULT_DB_PREFIX } from "../shared/app/storage-constants.js";
+import { artifactRoutes } from "./routes/artifacts.js";
+import { ArtifactStorageService } from "./services/artifact-storage.service.js";
+import { ArtifactMaintenanceService } from "./services/artifact-maintenance.service.js";
 import { watchNotes } from "./services/notes-watcher.service.js";
 import { notesRoutes } from "./routes/notes.js";
 import { NotesService } from "./services/notes.service.js";
@@ -49,8 +59,15 @@ const DEVICE_SWEEP_MS = 60 * 60 * 1000;
 // also when another server process on the same database revoked it.
 // One indexed SELECT per connected device.
 const DEVICE_RECHECK_MS = 2000;
+// A wildcard bind accepts loopback connections; the MCP process connects there.
+const WILDCARD_LOOPBACK = {
+    '::': '::1',
+    '0.0.0.0': '127.0.0.1'
+};
 export function buildApp(options = {}) {
     const app = Fastify({
+        // Logging is off. Redact the Authorization header before you turn it on:
+        // it carries the agent session key (ADR 0096).
         logger: false,
         forceCloseConnections: true,
         ajv: {
@@ -62,6 +79,7 @@ export function buildApp(options = {}) {
             ]
         }
     });
+    const allowedHosts = new AllowedHosts(options.allowedHosts);
     const repositoryPath = options.repositoryPath ?? process.cwd();
     const db = options.db ?? createTestDatabase();
     const eventBus = options.eventBus ?? createEventBus();
@@ -70,6 +88,8 @@ export function buildApp(options = {}) {
         onChange: () => eventBus.publish({ type: 'devices:changed' })
     });
     const deviceConnections = new DeviceConnections(devices);
+    // Set after the access hook exists, because the registry needs the listening server address.
+    let agentRegistry;
     devices.removeExpired();
     const sweep = setInterval(() => devices.removeExpired(), DEVICE_SWEEP_MS);
     sweep.unref();
@@ -92,7 +112,16 @@ export function buildApp(options = {}) {
     app.register(fastifyPlugin(async (root) => {
         root.addHook('onRequest', createAccessHook({
             devices,
-            allowedHosts: new AllowedHosts(options.allowedHosts)
+            allowedHosts,
+            authorizeArtifactAgent(request, reply) {
+                const id = agentRegistry?.authenticateArtifactKey(request.headers.authorization);
+                if (!id || !agentRegistry) {
+                    throw new ForbiddenError('Artifact session access denied.');
+                }
+                const release = agentRegistry.trackArtifactRequest(id, () => reply.raw.destroy());
+                reply.raw.once('finish', release);
+                reply.raw.once('close', release);
+            }
         }));
     }));
     // The spec collects routes as they are added, so it comes before them.
@@ -120,6 +149,45 @@ export function buildApp(options = {}) {
             watcher.close();
         });
     }
+    const artifacts = options.artifacts ??
+        new ArtifactStorageService({
+            db,
+            repositoryPath,
+            prefix: options.artifactPrefix ?? DEFAULT_DB_PREFIX,
+            eventBus
+        });
+    app.register(artifactRoutes, { service: artifacts });
+    app.register(artifactActionRoutes, {
+        service: artifacts.lifecycle,
+        recheckAccess: createAccessHook({ devices, allowedHosts })
+    });
+    artifacts.lifecycle.transitions.setActorGuard(actor => actor.id === 'local' || devices.isTrusted(actor.id));
+    artifacts.lifecycle.transitions.setErrorHandler(error => app.log.error({ err: error }, 'Artifact transition work failed'));
+    app.register(artifactTransitionRoutes, {
+        service: artifacts.lifecycle.transitions,
+        recheckAccess: createAccessHook({ devices, allowedHosts })
+    });
+    app.addHook('onReady', async () => {
+        artifacts.lifecycle.jobs.recover();
+        artifacts.lifecycle.transitions.start();
+    });
+    app.addHook('onClose', async () => {
+        artifacts.lifecycle.transitions.stop();
+        artifacts.lifecycle.jobs.close();
+    });
+    app.register(artifactDefinitionRoutes, { storage: artifacts });
+    const artifactMaintenance = new ArtifactMaintenanceService({
+        storage: artifacts,
+        onError: (error, phase) => {
+            app.log.error({ err: error, phase }, 'Artifact maintenance failed');
+        }
+    });
+    app.addHook('onReady', async () => {
+        artifactMaintenance.start();
+    });
+    app.addHook('onClose', async () => {
+        artifactMaintenance.stop();
+    });
     app.register(diffRoutes, { repositoryPath });
     app.register(gitRoutes, { repositoryPath });
     app.register(projectFileRoutes, { repositoryPath });
@@ -148,12 +216,31 @@ export function buildApp(options = {}) {
         });
     }
     if (options.agentPresets) {
+        const registry = createSessionRegistry({
+            presets: options.agentPresets,
+            connections: deviceConnections,
+            artifactUrl: () => {
+                const address = app.server.address();
+                // Before listen there is no address; only tests that skip listen get here.
+                if (!address)
+                    return undefined;
+                if (typeof address === 'string') {
+                    throw new Error(`Artifact tools need a TCP address, but the server listens on "${address}".`);
+                }
+                return `${addressUrl(WILDCARD_LOOPBACK[address.address] ?? address.address, address.port)}/`;
+            },
+            repositoryPath,
+            taskIds: sessionId => artifacts.definitions.assignment(sessionId).taskIds,
+            taskAssignment: sessionId => artifacts.definitions.assignment(sessionId)
+        });
+        agentRegistry = registry;
+        app.register(artifactAgentRoutes, { storage: artifacts, registry });
+        artifacts.tasks.attachSessions(registry);
+        artifacts.lifecycle.attachSessions(registry);
         app.register(agentRoutes, {
+            artifacts,
             notes,
-            registry: createSessionRegistry({
-                presets: options.agentPresets,
-                repositoryPath
-            }),
+            registry,
             db,
             repositoryPath,
             eventBus,