@tequila99/githuman 0.11.2 → 0.13.0

package/dist/server/routes/artifacts.js

@@ -0,0 +1,111 @@
+import { ArtifactExportService } from "../services/artifact-export.service.js";
+import { ArtifactExportQuery, ArtifactOriginalExportSchema, ArtifactMetadataExportSchema, ArtifactSearchBody, ArtifactSearchQuery, ArtifactSearchSchema, ArtifactSearchDiagnosticsSchema, ArtifactContentQuery, ArtifactContentSchema, ArtifactHistoryQuery, ArtifactHistorySchema, ArtifactListQuery, ArtifactListSchema, ArtifactParams, ArtifactSchema } from "../../shared/artifacts/schemas.js";
+import { ERROR_RESPONSES } from "../../shared/http/schemas.js";
+export async function artifactRoutes(app, { service }) {
+    const typed = app.withTypeProvider();
+    const exports = new ArtifactExportService(service);
+    // The schema describes the downloaded file; Fastify sends exact buffers or pre-serialized JSON streams.
+    typed.get('/api/artifacts/:id/export', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Download the original bytes or consistent metadata history',
+            params: ArtifactParams,
+            querystring: ArtifactExportQuery,
+            response: {
+                200: {
+                    description: 'Exact original Markdown file or streamed metadata history snapshot.',
+                    content: {
+                        'text/markdown': { schema: ArtifactOriginalExportSchema },
+                        'application/json': { schema: ArtifactMetadataExportSchema }
+                    }
+                },
+                ...ERROR_RESPONSES
+            }
+        }
+    }, (request, reply) => {
+        const id = request.params.id;
+        if (request.query.format === 'original') {
+            const { artifact, content } = exports.original(id);
+            reply.header('Content-Disposition', `attachment; filename="artifact-${id}.md"`);
+            reply.header('X-Artifact-SHA256', artifact.sha256);
+            reply.type('text/markdown; charset=utf-8');
+            reply.send(content);
+            return;
+        }
+        const stream = exports.metadataHistory(id);
+        reply.header('Content-Disposition', `attachment; filename="artifact-${id}.metadata-history.json"`);
+        reply.type('application/json; charset=utf-8');
+        const close = () => stream.destroy();
+        reply.raw.once('close', close);
+        stream.once('close', () => reply.raw.removeListener('close', close));
+        reply.send(stream);
+    });
+    typed.get('/api/artifacts/search', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Search verified artifact titles and body text',
+            querystring: ArtifactSearchQuery,
+            response: { 200: ArtifactSearchSchema, ...ERROR_RESPONSES }
+        }
+    }, request => {
+        const { status, typeId, taskId, tag, ...query } = request.query;
+        return service.search.search({
+            ...query,
+            filters: {
+                ...(status ? { statuses: [status] } : {}),
+                ...(typeId ? { typeIds: [typeId] } : {}),
+                ...(taskId ? { taskIds: [taskId] } : {}),
+                ...(tag ? { tags: [tag] } : {})
+            }
+        });
+    });
+    typed.post('/api/artifacts/search', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Search with multiple metadata filters',
+            body: ArtifactSearchBody,
+            response: { 200: ArtifactSearchSchema, ...ERROR_RESPONSES }
+        }
+    }, request => service.search.search(request.body));
+    typed.get('/api/artifacts/search/diagnostics', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Read derived search index diagnostics',
+            response: { 200: ArtifactSearchDiagnosticsSchema, ...ERROR_RESPONSES }
+        }
+    }, () => service.search.diagnostics());
+    typed.get('/api/artifacts', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'List committed artifacts',
+            querystring: ArtifactListQuery,
+            response: { 200: ArtifactListSchema, ...ERROR_RESPONSES }
+        }
+    }, request => service.list(request.query.limit, request.query.cursor));
+    typed.get('/api/artifacts/:id', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Read current artifact metadata',
+            params: ArtifactParams,
+            response: { 200: ArtifactSchema, ...ERROR_RESPONSES }
+        }
+    }, request => service.get(request.params.id));
+    typed.get('/api/artifacts/:id/content', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Read verified immutable artifact content',
+            params: ArtifactParams,
+            querystring: ArtifactContentQuery,
+            response: { 200: ArtifactContentSchema, ...ERROR_RESPONSES }
+        }
+    }, request => service.readContent(request.params.id, request.query.offset, request.query.limit));
+    typed.get('/api/artifacts/:id/history', {
+        schema: {
+            tags: ['artifacts'],
+            summary: 'Read immutable artifact history',
+            params: ArtifactParams,
+            querystring: ArtifactHistoryQuery,
+            response: { 200: ArtifactHistorySchema, ...ERROR_RESPONSES }
+        }
+    }, request => service.history(request.params.id, request.query.afterSeq, request.query.limit));
+}

package/dist/server/routes/events.js

@@ -30,7 +30,11 @@ export async function eventRoutes(app, opts) {
         const unsubscribe = eventBus.subscribe(event => {
             safeSend(reply.sse, {
                 event: event.type,
-                data: { reviewId: event.reviewId }
+                data: {
+                    reviewId: event.reviewId,
+                    storeId: event.storeId,
+                    storeEpoch: event.storeEpoch
+                }
             });
         });
         reply.sse.onClose(() => {

package/dist/server/services/agent/agent-session.js

@@ -1,4 +1,8 @@
+import { isLocalPiLaunch } from "../../adapters/pi-acp/launch.js";
+import { isRecord } from "../../../shared/utils/guards.js";
 import { AgentSessionError, AgentSessionStateError, AgentConfigError } from "../../errors/agents.js";
+import { ARTIFACT_TASK_PROMPT_HINT } from "../../../shared/artifact-tools/instructions.js";
+import { ARTIFACT_AGENT_KEY_ENV, ARTIFACT_MCP_SERVER_NAME } from "../../../shared/artifacts/mcp-constants.js";
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { rm } from 'node:fs/promises';
@@ -16,6 +20,8 @@ export const MAX_BUFFERED_EVENTS = 5_000;
 const STDERR_TAIL_CHARS = 2_000;
 /** How long a closed connection waits for the `exit` event that carries the reason. */
 const EXIT_GRACE_MS = 500;
+// Bound pending tool context retained only for server permission policies.
+const MAX_PERMISSION_TOOL_CALLS = 64;
 /** The option the server picks for an auto-approved request; never a rejection. */
 function autoApproveChoice(options) {
     return (options.find(o => o.kind === 'allow_once') ??
@@ -35,11 +41,14 @@ export class AgentSession {
     presetId;
     name;
     reviewId;
+    kind;
+    #turnTaskContext;
     #status = 'starting';
     /** Set when the user (or the server) ends the session: its exit is no failure. */
     #closing = false;
     #error = null;
     #autoApprove = false;
+    #permissionToolCalls = new Map();
     #child;
     #connection;
     #acpSessionId;
@@ -47,6 +56,8 @@ export class AgentSession {
     #image = false;
     #config = [];
     #stderrTail = '';
+    #mcpSecrets = [];
+    #hasArtifactMcp = false;
     /** Settles when the agent process has exited. */
     #exited = Promise.resolve();
     #ownEventId = 0;
@@ -61,10 +72,35 @@ export class AgentSession {
         this.presetId = options.preset.id;
         this.name = options.name;
         this.reviewId = options.reviewId ?? null;
+        this.kind = options.kind;
     }
     get status() {
         return this.#status;
     }
+    get turnTaskContext() {
+        return this.#turnTaskContext;
+    }
+    prepareTaskActivation(turnId, assignmentVersion, taskId, requestId) {
+        // Cancellation clears the context before the agent stops reporting busy.
+        if (!this.#turnTaskContext || this.#turnTaskContext.turnId !== turnId) {
+            throw new AgentSessionStateError('The response ended or its task context changed.');
+        }
+        const context = Object.freeze({
+            sessionId: this.id,
+            turnId,
+            assignmentVersion,
+            taskIds: Object.freeze([taskId]),
+            source: 'turn_activation',
+            activationRequestId: requestId
+        });
+        // The caller commits and applies synchronously, without yielding to cancellation or another prompt.
+        return {
+            context,
+            apply: () => {
+                this.#turnTaskContext = context;
+            }
+        };
+    }
     /** Whether the agent advertised `promptCapabilities.embeddedContext`. */
     get supportsEmbeddedContext() {
         return this.#embeddedContext;
@@ -76,8 +112,12 @@ export class AgentSession {
     info() {
         return {
             id: this.id,
+            ...(this.#options.taskIds
+                ? { taskIds: this.#options.taskIds(this.id) }
+                : {}),
             presetId: this.presetId,
             name: this.name,
+            ...(this.kind === undefined ? {} : { kind: this.kind }),
             status: this.#status,
             reviewId: this.reviewId,
             autoApprove: this.#autoApprove,
@@ -106,7 +146,7 @@ export class AgentSession {
         catch (error) {
             // An exit during the start already reported itself (`#onExit`).
             if (this.#error === null && !this.#closing) {
-                const message = errorMessage(error);
+                const message = this.#redact(errorMessage(error));
                 this.#error = message;
                 this.#emit({ type: 'error', message });
             }
@@ -115,16 +155,28 @@ export class AgentSession {
     }
     async #start() {
         const { preset, cwd } = this.#options;
+        const localPi = isLocalPiLaunch(preset);
+        if (preset.id === 'pi' && this.kind === 'validation' && !localPi) {
+            throw new AgentSessionError('Pi validation requires the trusted local GitHuman pi launcher. The configured command is available for chat only.');
+        }
         const child = spawn(preset.command, preset.args, {
             cwd,
             stdio: ['pipe', 'pipe', 'pipe'],
-            env: { ...process.env, ...preset.env }
+            env: {
+                ...process.env,
+                ...preset.env,
+                ...(localPi
+                    ? {
+                        GITHUMAN_PI_PROFILE: this.kind === 'validation' ? 'validator' : 'chat'
+                    }
+                    : {})
+            }
         });
         this.#child = child;
         this.#exited = new Promise(resolve => child.once('exit', resolve));
         child.stderr.setEncoding('utf-8');
         child.stderr.on('data', (chunk) => {
-            this.#stderrTail = (this.#stderrTail + chunk).slice(-STDERR_TAIL_CHARS);
+            this.#stderrTail = this.#redact(this.#stderrTail + chunk).slice(-STDERR_TAIL_CHARS);
         });
         // Swallow stdin EPIPE after the agent died; the closed connection reports it.
         child.stdin.on('error', () => { });
@@ -181,10 +233,28 @@ export class AgentSession {
         const prompt = init.agentCapabilities?.promptCapabilities;
         this.#embeddedContext = prompt?.embeddedContext === true;
         this.#image = prompt?.image === true;
+        const mcpServers = typeof this.#options.mcpServers === 'function'
+            ? this.#options.mcpServers(this.id)
+            : (this.#options.mcpServers ?? []);
+        this.#hasArtifactMcp = mcpServers.some(server => server.name === ARTIFACT_MCP_SERVER_NAME);
+        this.#mcpSecrets = mcpServers.flatMap(server => 'env' in server
+            ? server.env
+                .filter(entry => entry.name === ARTIFACT_AGENT_KEY_ENV)
+                .map(entry => entry.value)
+            : []);
         const created = await connection.agent.request(acp.methods.agent.session.new, {
             cwd: this.#options.cwd,
-            mcpServers: []
+            mcpServers
         });
+        if (isLocalPiLaunch(this.#options.preset)) {
+            const ack = created['_meta']?.githumanBridge;
+            if (!isRecord(ack) ||
+                ack.version !== 1 ||
+                ack.profile !== (this.kind === 'validation' ? 'validator' : 'chat') ||
+                ack.registryGeneration !== 1) {
+                throw new AgentSessionError('Pi bridge did not confirm its launch profile and MCP registry.');
+            }
+        }
         this.#acpSessionId = created.sessionId;
         this.#setConfig(mapConfigOptions(created.configOptions));
     }
@@ -223,7 +293,9 @@ export class AgentSession {
             this.#setConfig(mapConfigOptions(response.configOptions));
         }
         catch (error) {
-            throw new AgentSessionError(errorMessage(error), { cause: error });
+            throw new AgentSessionError(this.#redact(errorMessage(error)), {
+                cause: error
+            });
         }
     }
     /** The agent process ended: report why, unless the session itself ended it. */
@@ -257,8 +329,15 @@ export class AgentSession {
         }
         this.#markClosed();
     }
+    // Hides the session key in errors and stderr. Messages that the agent itself writes stay as they are.
+    #redact(text) {
+        for (const secret of this.#mcpSecrets) {
+            text = text.replaceAll(secret, '[redacted]');
+        }
+        return text;
+    }
     #exitMessage(code, signal) {
-        const tail = this.#stderrTail.trim();
+        const tail = this.#redact(this.#stderrTail.trim());
         return (`Agent exited (${signal ?? `code ${code}`})` +
             (tail === '' ? '' : `: ${tail.slice(-400)}`));
     }
@@ -268,13 +347,29 @@ export class AgentSession {
      */
     prompt(blocks, display) {
         const { connection, sessionId } = this.#readyChannel();
+        const assignment = this.#options.taskAssignment?.(this.id);
+        const turn = Object.freeze({
+            turnId: randomUUID(),
+            sessionId: this.id,
+            assignmentVersion: assignment?.version ?? 0,
+            source: 'turn_assignment',
+            taskIds: Object.freeze([...(assignment?.taskIds ?? [])])
+        });
+        this.#turnTaskContext = turn;
         this.#setStatus('busy');
         this.#emit({
             type: 'user',
             text: display.text,
             context: display.context ?? []
         });
-        void this.#runPrompt(connection, sessionId, blocks);
+        // Append the reminder without changing the user transcript or validator assignments.
+        const prompt = this.#hasArtifactMcp && !this.#options.permissionPolicy
+            ? [
+                ...blocks,
+                { type: 'text', text: ARTIFACT_TASK_PROMPT_HINT }
+            ]
+            : blocks;
+        void this.#runPrompt(connection, sessionId, prompt, turn.turnId);
     }
     /**
      * Throws when the session cannot take a prompt now. The route calls this
@@ -293,12 +388,14 @@ export class AgentSession {
         }
         return { connection, sessionId };
     }
-    async #runPrompt(connection, sessionId, blocks) {
+    async #runPrompt(connection, sessionId, blocks, turnId) {
         try {
             const response = await connection.agent.request(acp.methods.agent.session.prompt, { sessionId, prompt: blocks });
+            this.#clearTurnTaskContext(turnId);
             this.#emit({ type: 'stop', stopReason: response.stopReason });
         }
         catch (error) {
+            this.#clearTurnTaskContext(turnId);
             // A failure of the transport comes before the `exit` event, and only
             // that event can say why the agent died: let it report first.
             if (!(error instanceof acp.RequestError)) {
@@ -308,10 +405,14 @@ export class AgentSession {
                 ]);
             }
             if (!this.#isClosed() && this.#error === null) {
-                this.#emit({ type: 'error', message: errorMessage(error) });
+                this.#emit({
+                    type: 'error',
+                    message: this.#redact(errorMessage(error))
+                });
             }
         }
         finally {
+            this.#clearTurnTaskContext(turnId);
             // A request still open once the turn is over (it ended in an error, say)
             // is dead: answering it later would still make the agent act on it.
             this.#cancelPendingPermissions();
@@ -320,6 +421,11 @@ export class AgentSession {
             }
         }
     }
+    #clearTurnTaskContext(turnId) {
+        if (this.#turnTaskContext?.turnId === turnId) {
+            this.#turnTaskContext = undefined;
+        }
+    }
     /** A method, so TypeScript does not keep a stale narrowing across an `await`. */
     #isClosed() {
         return this.#status === 'closed';
@@ -328,6 +434,8 @@ export class AgentSession {
         if (this.#status !== 'busy' || !this.#connection || !this.#acpSessionId) {
             return;
         }
+        // Stop inheritance immediately; the agent may take time to finish cancellation.
+        this.#turnTaskContext = undefined;
         try {
             await this.#connection.agent.notify(acp.methods.agent.session.cancel, {
                 sessionId: this.#acpSessionId
@@ -336,7 +444,9 @@ export class AgentSession {
         catch (error) {
             // The connection closed since the check above: the turn is over anyway.
             if (!this.#isClosed()) {
-                throw new AgentSessionError(errorMessage(error), { cause: error });
+                throw new AgentSessionError(this.#redact(errorMessage(error)), {
+                    cause: error
+                });
             }
         }
     }
@@ -367,6 +477,9 @@ export class AgentSession {
         if (this.#status === 'closed') {
             throw new AgentSessionStateError('The session is closed');
         }
+        if (enabled && this.#options.permissionPolicy) {
+            throw new AgentSessionStateError('This session uses a fixed permission policy.');
+        }
         if (this.#autoApprove === enabled) {
             return;
         }
@@ -396,6 +509,9 @@ export class AgentSession {
         if (this.#status !== 'busy') {
             return Promise.resolve({ outcome: { outcome: 'cancelled' } });
         }
+        if (this.#options.permissionPolicy) {
+            return Promise.resolve(this.#policyPermission(params));
+        }
         const requestId = randomUUID();
         const request = mapPermissionRequest(requestId, params);
         if (this.#autoApprove) {
@@ -416,6 +532,40 @@ export class AgentSession {
             this.#emit(request);
         });
     }
+    #policyPermission(params) {
+        const previous = this.#permissionToolCalls.get(params.toolCall.toolCallId);
+        this.#permissionToolCalls.delete(params.toolCall.toolCallId);
+        let decision = {
+            allow: false,
+            reason: 'Permission policy could not verify this action.'
+        };
+        try {
+            decision = this.#options.permissionPolicy(params, previous);
+        }
+        catch {
+            // Policy failures must not create a manual prompt or grant an action.
+        }
+        const choice = decision.allow
+            ? params.options.find(option => option.kind === 'allow_once')
+            : undefined;
+        if (choice) {
+            this.#emit({ type: 'auto-approved', title: decision.reason });
+            return { outcome: { outcome: 'selected', optionId: choice.optionId } };
+        }
+        this.#emit({
+            type: 'tool',
+            toolCallId: params.toolCall.toolCallId,
+            title: 'Validation permission denied',
+            status: 'failed',
+            output: decision.allow
+                ? 'Permission policy requires an allow_once option.'
+                : decision.reason
+        });
+        const reject = params.options.find(option => option.kind === 'reject_once');
+        return reject
+            ? { outcome: { outcome: 'selected', optionId: reject.optionId } }
+            : { outcome: { outcome: 'cancelled' } };
+    }
     #onUpdate(update) {
         // Agents may speak outside a turn — pi greets with its version and skill
         // list right after session/new. That is noise in a chat transcript.
@@ -423,6 +573,24 @@ export class AgentSession {
             update.sessionUpdate === 'agent_message_chunk') {
             return;
         }
+        if (this.#options.permissionPolicy &&
+            this.#status === 'busy' &&
+            (update.sessionUpdate === 'tool_call' ||
+                update.sessionUpdate === 'tool_call_update')) {
+            if (update.status === 'completed' || update.status === 'failed') {
+                this.#permissionToolCalls.delete(update.toolCallId);
+            }
+            else {
+                const previous = this.#permissionToolCalls.get(update.toolCallId);
+                this.#permissionToolCalls.set(update.toolCallId, {
+                    ...previous,
+                    ...update
+                });
+                if (this.#permissionToolCalls.size > MAX_PERMISSION_TOOL_CALLS) {
+                    this.#permissionToolCalls.delete(this.#permissionToolCalls.keys().next().value);
+                }
+            }
+        }
         const event = mapSessionUpdate(update);
         if (event?.type === 'config') {
             // Keep `#config` current: `setConfig` checks values against it.
@@ -476,12 +644,14 @@ export class AgentSession {
         if (this.#status === 'closed') {
             return;
         }
+        this.#turnTaskContext = undefined;
         this.#setStatus('closed', this.#error ?? undefined);
         void rm(this.attachmentDir, { recursive: true, force: true }).catch(() => { });
         // Unanswered permission requests must not leave the agent blocked forever.
         this.#cancelPendingPermissions();
     }
     #cancelPendingPermissions() {
+        this.#permissionToolCalls.clear();
         // Each resolver removes itself from the map, which Map iteration allows.
         for (const pending of this.#pendingPermissions.values()) {
             pending.resolve({ outcome: { outcome: 'cancelled' } });

package/dist/server/services/agent/context-builder.js

@@ -1,3 +1,4 @@
+import { artifactBody } from "../../../shared/utils/artifact-body.js";
 import { MAX_ATTACHMENT_BYTES } from "../../../shared/agents/constants.js";
 import { AgentContextError } from "../../errors/agents.js";
 import { errorMessage } from "../../../shared/utils/error-message.js";
@@ -33,8 +34,9 @@ function fenceFor(text) {
  * goes in as an embedded resource when the agent supports it, otherwise as a
  * fenced block in a plain text part — same content either way.
  */
-function embed(deps, uri, title, mimeType, text) {
-    const body = truncateText(text, MAX_EMBEDDED_CHARS, omitted => `\n… [truncated by githuman: ${omitted} more characters]`);
+function embed(deps, uri, title, mimeType, text, prefix = '') {
+    const body = prefix +
+        truncateText(text, MAX_EMBEDDED_CHARS, omitted => `\n… [truncated by githuman: ${omitted} more characters]`);
     if (deps.embeddedContext) {
         return { type: 'resource', resource: { uri, mimeType, text: body } };
     }
@@ -173,7 +175,33 @@ async function buildNoteItem(item, deps) {
         throw asContextError(error);
     }
 }
+async function buildArtifactItem(item, deps) {
+    try {
+        const storage = deps.artifacts;
+        if (!storage || item.storeId !== storage.storeId) {
+            throw new AgentContextError('Artifact store is unavailable or has changed');
+        }
+        const { content, ...snapshot } = storage.graph.readDocumentContext(item.artifactId);
+        const { artifact } = snapshot;
+        const prefix = 'Artifact metadata snapshot (current; original frontmatter is historical):\n' +
+            JSON.stringify(snapshot) +
+            '\n\n' +
+            'Use artifacts.relations with direction and nextCursor to read remaining links. Read related documents explicitly via artifacts.get and artifacts.get_content; they are not embedded here.\n' +
+            'Cite documents with /#/artifacts?storeId=' +
+            encodeURIComponent(storage.storeId) +
+            '&selectedId=' +
+            encodeURIComponent(artifact.id) +
+            '. Related document citations use their own selectedId.\n' +
+            'Use artifacts.get_content with this artifact ID and offset=0 to read the full original UTF-8 file; follow nextOffset. bodyStartLine identifies the body. Cite artifact IDs and distinguish historical statuses from current accepted context.\n\nDocument body:\n';
+        return embed(deps, `githuman://artifact/${encodeURIComponent(item.storeId)}/${encodeURIComponent(artifact.id)}`, `Artifact ${artifact.title}:`, 'text/markdown', artifactBody(content.toString('utf8'), artifact.bodyStartLine), prefix);
+    }
+    catch (error) {
+        throw asContextError(error);
+    }
+}
 function buildItem(item, deps) {
+    if (item.kind === 'artifact')
+        return buildArtifactItem(item, deps);
     if (item.kind === 'note')
         return buildNoteItem(item, deps);
     if (item.kind === 'diff') {