@peakflo/agent-harness 0.2.4-rc.1 → 0.2.4

package/dist/runtime/knowledge-tools.js

@@ -0,0 +1,410 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KnowledgeToolHost = exports.KNOWLEDGE_FILE_DOWNLOAD_TOOL = exports.KNOWLEDGE_FILES_LIST_TOOL = exports.KNOWLEDGE_SERVER_NAME = void 0;
+exports.safeDownloadName = safeDownloadName;
+/**
+ * KNOWLEDGE TOOLS, SERVED BY THE HARNESS (P9).
+ *
+ * `knowledge_files_list` and `knowledge_file_download` are MCP tools the agent
+ * calls like any other. They are served here, on a loopback socket, rather than
+ * by the gateway, because the download has to land in THIS workspace and the
+ * gateway has no access to it.
+ *
+ *   model → harness (MCP over loopback, path secret)
+ *         → control plane (lease-authenticated: who may read what, decided there)
+ *         → signed URL → harness fetches it into `downloads/<name>`
+ *
+ * The signed URL goes from the control plane to the harness and stops there.
+ * The tool result names the saved path, size and type, and nothing else. The
+ * model never holds the URL, the transcript never records it, and the log line
+ * carries only ids.
+ *
+ * THE SERVER IS MINIMAL ON PURPOSE. It implements the three methods an MCP
+ * client needs for a tools-only server (`initialize`, `tools/list`,
+ * `tools/call`) over the Streamable HTTP transport in its JSON-response form.
+ * It never opens a server-sent-events stream (GET is 405), because the tools
+ * are synchronous and nothing is pushed to the client.
+ *
+ * ONE SECRET PER SESSION. Each session's endpoint carries a random path
+ * (`/mcp/<token>`). The token is the only thing that maps a request to a
+ * session, and the host header must name the loopback address, which blocks a
+ * DNS-rebinding page from reaching it. A request outside an active turn is
+ * refused, because the lease that authorises it exists only during the turn.
+ */
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:fs/promises");
+const node_http_1 = require("node:http");
+const node_path_1 = require("node:path");
+const control_plane_1 = require("../control-plane");
+const space_files_1 = require("./space-files");
+/** The name the agent sees the server under. */
+exports.KNOWLEDGE_SERVER_NAME = 'pf-knowledge';
+exports.KNOWLEDGE_FILES_LIST_TOOL = 'knowledge_files_list';
+exports.KNOWLEDGE_FILE_DOWNLOAD_TOOL = 'knowledge_file_download';
+const SUPPORTED_PROTOCOL_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05'];
+const DEFAULT_PROTOCOL_VERSION = '2025-06-18';
+const MAX_BODY_BYTES = 256 * 1024;
+const SERVER_VERSION = '1';
+const TOOLS = [
+    {
+        name: exports.KNOWLEDGE_FILES_LIST_TOOL,
+        description: 'List the knowledge files you may read: id, datastore, name, type, size and status. Metadata only. Use it to find a fileId for knowledge_file_download.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                datastoreId: {
+                    type: 'string',
+                    description: 'Optional. Only list files of this datastore.'
+                }
+            },
+            additionalProperties: false
+        }
+    },
+    {
+        name: exports.KNOWLEDGE_FILE_DOWNLOAD_TOOL,
+        description: 'Download one knowledge file into ./downloads (up to 50 MB). Returns the saved path, size and type. Read it with your file tools afterwards.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                datastoreId: {
+                    type: 'string',
+                    description: 'The datastore id from knowledge_files_list.'
+                },
+                fileId: {
+                    type: 'string',
+                    description: 'The file id from knowledge_files_list.'
+                }
+            },
+            required: ['datastoreId', 'fileId'],
+            additionalProperties: false
+        }
+    }
+];
+/** A name safe as one path segment, for a download's name. */
+function safeDownloadName(raw) {
+    let name = (0, space_files_1.replaceControlCharacters)(String(raw ?? ''))
+        .replace(/[\\/:*?"<>|]/g, '_')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .replace(/^\.+/, '')
+        .trim();
+    if (!name)
+        name = 'file';
+    if (name.length > 150) {
+        const dot = name.lastIndexOf('.');
+        const ext = dot > 0 && name.length - dot <= 16 ? name.slice(dot) : '';
+        name = name.slice(0, 150 - ext.length) + ext;
+    }
+    return name;
+}
+/** `name`, or `name (2).ext`, ... for the first slot not already in `downloads/`. */
+async function freeDownloadPath(dir, name) {
+    const dot = name.lastIndexOf('.');
+    const stem = dot > 0 ? name.slice(0, dot) : name;
+    const ext = dot > 0 ? name.slice(dot) : '';
+    for (let index = 1;; index++) {
+        const candidate = index === 1 ? name : `${stem} (${index})${ext}`;
+        try {
+            await (0, promises_1.stat)((0, node_path_1.join)(dir, candidate));
+        }
+        catch {
+            return { name: candidate, path: (0, node_path_1.join)(dir, candidate) };
+        }
+    }
+}
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+/** A tool-level failure: a message for the model, never a stack or a URL. */
+class ToolFailure extends Error {
+}
+function plainMessage(error) {
+    if (error instanceof ToolFailure)
+        return error.message;
+    if (error instanceof control_plane_1.ControlPlaneError)
+        return error.message;
+    return 'The knowledge tool could not complete this request.';
+}
+const ID_PATTERN = /^[0-9a-fA-F-]{36}$/;
+function requiredId(value, field) {
+    if (typeof value !== 'string' || !ID_PATTERN.test(value))
+        throw new ToolFailure(`${field} must be an id from knowledge_files_list.`);
+    return value;
+}
+function optionalId(value, field) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    return requiredId(value, field);
+}
+/** The request body, or null when it is larger than the limit. */
+function readBody(req, limit) {
+    return new Promise((resolve, reject) => {
+        let size = 0;
+        const chunks = [];
+        req.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > limit) {
+                resolve(null);
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        req.on('error', reject);
+    });
+}
+class KnowledgeToolHost {
+    options;
+    server = null;
+    port = 0;
+    starting = null;
+    tokenBySession = new Map();
+    sessionByToken = new Map();
+    turns = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    /** The endpoint a session's agent is configured with. Starts the listener on first use. */
+    async endpointFor(sessionId) {
+        await this.start();
+        let token = this.tokenBySession.get(sessionId);
+        if (!token) {
+            token = (0, node_crypto_1.randomBytes)(24).toString('base64url');
+            this.tokenBySession.set(sessionId, token);
+            this.sessionByToken.set(token, sessionId);
+        }
+        return `http://127.0.0.1:${this.port}/mcp/${token}`;
+    }
+    /** Bind the current turn's lease, or clear it with null when the turn ends. */
+    bindTurn(sessionId, turn) {
+        if (turn)
+            this.turns.set(sessionId, turn);
+        else
+            this.turns.delete(sessionId);
+    }
+    async stop() {
+        const server = this.server;
+        this.server = null;
+        this.starting = null;
+        this.turns.clear();
+        if (server)
+            await new Promise((resolve) => server.close(() => resolve()));
+    }
+    start() {
+        if (this.server)
+            return Promise.resolve();
+        if (!this.starting) {
+            this.starting = new Promise((resolve, reject) => {
+                const server = (0, node_http_1.createServer)((req, res) => {
+                    void this.handle(req, res).catch((error) => {
+                        this.options.logger.error(`[knowledge] request failed: ${error instanceof Error ? error.message : String(error)}`);
+                        if (!res.headersSent)
+                            res.statusCode = 500;
+                        res.end();
+                    });
+                });
+                server.once('error', (error) => {
+                    this.starting = null;
+                    reject(error);
+                });
+                // Loopback only. Nothing outside this host can open this socket.
+                server.listen(0, '127.0.0.1', () => {
+                    const address = server.address();
+                    this.port = typeof address === 'object' && address ? address.port : 0;
+                    this.server = server;
+                    // Never keeps the process alive on its own: a one-shot run must still exit.
+                    server.unref();
+                    resolve();
+                });
+            });
+        }
+        return this.starting;
+    }
+    async handle(req, res) {
+        const host = req.headers.host ?? '';
+        if (host !== `127.0.0.1:${this.port}` &&
+            host !== `localhost:${this.port}`) {
+            res.statusCode = 403;
+            res.end();
+            return;
+        }
+        const match = /^\/mcp\/([A-Za-z0-9_-]{20,})$/.exec(req.url ?? '');
+        const sessionId = match ? this.sessionByToken.get(match[1]) : undefined;
+        if (!sessionId) {
+            res.statusCode = 404;
+            res.end();
+            return;
+        }
+        if (req.method === 'DELETE') {
+            res.statusCode = 200;
+            res.end();
+            return;
+        }
+        // The server never opens an event stream: a tools-only server has nothing to push.
+        if (req.method !== 'POST') {
+            res.statusCode = 405;
+            res.setHeader('Allow', 'POST, DELETE');
+            res.end();
+            return;
+        }
+        const raw = await readBody(req, MAX_BODY_BYTES);
+        if (raw === null) {
+            res.statusCode = 413;
+            res.end();
+            return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return this.send(res, {
+                jsonrpc: '2.0',
+                id: null,
+                error: { code: -32700, message: 'Parse error' }
+            });
+        }
+        const messages = Array.isArray(parsed) ? parsed : [parsed];
+        const replies = [];
+        for (const message of messages) {
+            const reply = await this.dispatch(message, sessionId);
+            if (reply)
+                replies.push(reply);
+        }
+        if (!replies.length) {
+            // Only notifications: the protocol's answer is 202 with no body.
+            res.statusCode = 202;
+            res.end();
+            return;
+        }
+        this.send(res, Array.isArray(parsed) ? replies : replies[0]);
+    }
+    send(res, body) {
+        res.statusCode = 200;
+        res.setHeader('Content-Type', 'application/json');
+        res.end(JSON.stringify(body));
+    }
+    async dispatch(message, sessionId) {
+        if (!message || typeof message !== 'object' || message.jsonrpc !== '2.0') {
+            return {
+                jsonrpc: '2.0',
+                id: null,
+                error: { code: -32600, message: 'Invalid Request' }
+            };
+        }
+        // No `id` means a notification. Nothing is answered.
+        if (message.id === undefined)
+            return null;
+        const id = message.id;
+        const method = typeof message.method === 'string' ? message.method : '';
+        switch (method) {
+            case 'initialize': {
+                const requested = message.params?.protocolVersion;
+                const protocolVersion = typeof requested === 'string' &&
+                    SUPPORTED_PROTOCOL_VERSIONS.includes(requested)
+                    ? requested
+                    : DEFAULT_PROTOCOL_VERSION;
+                return {
+                    jsonrpc: '2.0',
+                    id,
+                    result: {
+                        protocolVersion,
+                        capabilities: { tools: {} },
+                        serverInfo: { name: exports.KNOWLEDGE_SERVER_NAME, version: SERVER_VERSION }
+                    }
+                };
+            }
+            case 'ping':
+                return { jsonrpc: '2.0', id, result: {} };
+            case 'tools/list':
+                return { jsonrpc: '2.0', id, result: { tools: TOOLS } };
+            case 'tools/call': {
+                const params = (message.params ?? {});
+                const result = await this.callTool(String(params.name ?? ''), (params.arguments ?? {}), sessionId);
+                return { jsonrpc: '2.0', id, result };
+            }
+            default:
+                return {
+                    jsonrpc: '2.0',
+                    id,
+                    error: { code: -32601, message: 'Method not found' }
+                };
+        }
+    }
+    async callTool(name, args, sessionId) {
+        const turn = this.turns.get(sessionId);
+        try {
+            if (!turn) {
+                throw new ToolFailure('Knowledge files are only available while a turn is running.');
+            }
+            if (name === exports.KNOWLEDGE_FILES_LIST_TOOL) {
+                return {
+                    content: [{ type: 'text', text: await this.list(turn, args) }]
+                };
+            }
+            if (name === exports.KNOWLEDGE_FILE_DOWNLOAD_TOOL) {
+                return {
+                    content: [
+                        { type: 'text', text: await this.download(turn, args, sessionId) }
+                    ]
+                };
+            }
+            throw new ToolFailure(`Unknown tool: ${name}`);
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: plainMessage(error) }],
+                isError: true
+            };
+        }
+    }
+    async list(turn, args) {
+        const datastoreId = optionalId(args.datastoreId, 'datastoreId');
+        const result = await turn.control.list(datastoreId);
+        if (!result.files.length)
+            return 'No knowledge files are available for this chat.';
+        const lines = result.files.map((file) => `${file.fileId} | ${file.datastoreName} | ${file.name} | ${file.mimeType ?? 'unknown type'} | ${file.sizeBytes === null ? 'unknown size' : formatBytes(file.sizeBytes)} | ${file.status}`);
+        const header = 'fileId | datastore | name | type | size | status';
+        const tail = result.truncated
+            ? '\n(The list is longer than this; narrow it with datastoreId.)'
+            : '';
+        return `${header}\n${lines.join('\n')}${tail}`;
+    }
+    async download(turn, args, sessionId) {
+        const datastoreId = requiredId(args.datastoreId, 'datastoreId');
+        const fileId = requiredId(args.fileId, 'fileId');
+        const signed = await turn.control.download(datastoreId, fileId);
+        if (!(Number.isSafeInteger(signed.sizeBytes) && signed.sizeBytes >= 0)) {
+            throw new ToolFailure('The file size could not be read.');
+        }
+        if (signed.sizeBytes > space_files_1.SPACE_FILE_MAX_BYTES) {
+            throw new ToolFailure('That file is larger than the 50 MB download limit.');
+        }
+        const dir = (0, node_path_1.join)(turn.workspaceDir, space_files_1.DOWNLOADS_DIR);
+        await (0, promises_1.mkdir)(dir, { recursive: true });
+        const { name, path } = await freeDownloadPath(dir, safeDownloadName(signed.name));
+        const tmp = (0, node_path_1.join)(dir, `.tmp-${(0, node_crypto_1.randomUUID)()}`);
+        try {
+            await (0, space_files_1.downloadTo)(signed.url, tmp, {
+                maxBytes: signed.sizeBytes,
+                timeoutMs: this.options.downloadTimeoutMs ?? space_files_1.SPACE_FILE_DOWNLOAD_TIMEOUT_MS,
+                fetchImpl: this.options.fetchImpl ?? fetch
+            });
+            await (0, promises_1.rename)(tmp, path);
+        }
+        catch (error) {
+            await (0, promises_1.rm)(tmp, { force: true });
+            // The error is scrubbed of URLs by the caller's plainMessage; the reason is logged without one.
+            this.options.logger.warn(`[knowledge] download of ${fileId} failed: ${error instanceof Error ? error.message.replace(/https?:\/\/\S+/gi, '<url>') : 'unknown error'}`);
+            throw new ToolFailure('That file could not be downloaded right now. Try again in a moment.');
+        }
+        this.options.logger.log(`[knowledge] saved ${fileId} to ${space_files_1.DOWNLOADS_DIR}/${name} for session ${sessionId}`);
+        return `Saved to ${space_files_1.DOWNLOADS_DIR}/${name} (${formatBytes(signed.sizeBytes)}, ${signed.mimeType ?? 'unknown type'}). Read it with your file tools.`;
+    }
+}
+exports.KnowledgeToolHost = KnowledgeToolHost;

package/dist/runtime/session-runner.d.ts

@@ -22,6 +22,7 @@ import type { CodingAgentAdapter } from '../adapters';
 import { SessionModelGateway } from '../adapters/model-gateway';
 import { ArtifactInspector, ConversationStore, EventSink, ModelMessageRecord, Notifier, SecretProvider, Telemetry, TranscriptStore, WorkspaceProvider } from '../ports';
 import { LeaseResponse, ModelMessageInput, TranscriptPartInput, TurnMetadata } from '../types';
+import { KnowledgeToolHost, type KnowledgeControl } from './knowledge-tools';
 import { McpAuthProxy } from './mcp-auth-proxy';
 export interface SessionRunnerDeps {
     /** Resolves a backend name from the lease to a working adapter. */
@@ -102,6 +103,14 @@ export interface SessionRunnerDeps {
      * global `fetch` otherwise. Injected so tests need no network.
      */
     fetchAttachment?: typeof fetch;
+    /**
+     * The knowledge tools (P9): the process's loopback host, and this lease's
+     * control-plane client. Absent on a harness that does not serve them.
+     */
+    knowledge?: {
+        host: KnowledgeToolHost;
+        control: KnowledgeControl;
+    };
 }
 export interface RunTurnResult {
     turn: TurnMetadata;
@@ -499,6 +508,14 @@ export declare class SessionRunner {
      * a security position rather than a gap.
      */
     private setUpSecrets;
+    /**
+     * Make `space-files/` match this turn's Space files manifest (P9).
+     *
+     * Runs when the lease carries a manifest, or when this workspace already has a
+     * sync record: a chat that moved to a Space with no files must not keep the
+     * old Space's copies. Never throws; a failed sync is logged and the turn runs.
+     */
+    private syncSpaceFilesForTurn;
     /**
      * Build the backend's session config.
      *

package/dist/runtime/session-runner.js

@@ -32,8 +32,10 @@ const model_gateway_1 = require("../adapters/model-gateway");
 const contract_1 = require("../contract");
 const attachments_1 = require("./attachments");
 const conversation_1 = require("./conversation");
+const knowledge_tools_1 = require("./knowledge-tools");
 const permission_mode_1 = require("./permission-mode");
 const projection_1 = require("./projection");
+const space_files_1 = require("./space-files");
 /** How often the runner asks the adapter for new output when nothing pushes. */
 const POLL_INTERVAL_MS = 2_000;
 /**
@@ -527,6 +529,9 @@ class SessionRunner {
              * .droppedAttachments`'s doc comment.
              */
             const hasDroppedAttachments = (session.input.droppedAttachments?.length ?? 0) > 0;
+            if (workspaceDir) {
+                await this.syncSpaceFilesForTurn(session, workspaceDir);
+            }
             if (workspaceDir && (hasLeasedAttachments || hasDroppedAttachments)) {
                 const sync = await (0, attachments_1.syncAttachmentsToWorkspace)(session.input.attachments, workspaceDir, {
                     fetchImpl: this.deps.fetchAttachment,
@@ -619,7 +624,20 @@ class SessionRunner {
             adapter = this.deps.getAdapter(session.agent.backend);
             await adapter.initialize();
             secretToken = this.setUpSecrets(session);
-            const config = this.buildSessionConfig(session, workspaceDir, secretToken, signal);
+            /*
+             * THE KNOWLEDGE TOOLS FOR THIS TURN (P9). Bound to this lease and this
+             * workspace, and unbound in `finally`, so a tool call that arrives between
+             * turns is refused rather than acting on a lease that has ended.
+             */
+            let knowledgeUrl = null;
+            if (session.spaceFiles && this.deps.knowledge && workspaceDir) {
+                this.deps.knowledge.host.bindTurn(session.sessionId, {
+                    control: this.deps.knowledge.control,
+                    workspaceDir
+                });
+                knowledgeUrl = await this.deps.knowledge.host.endpointFor(session.sessionId);
+            }
+            const config = this.buildSessionConfig(session, workspaceDir, secretToken, signal, knowledgeUrl);
             /*
              * REMEMBER THE CONVERSATION. This block is the fix for the defect that
              * made this a chat product that could not hold a conversation: the
@@ -727,7 +745,7 @@ class SessionRunner {
                         `${memory.backendSessionId} for ${session.sessionId}: ` +
                         `${caught instanceof Error ? caught.message : String(caught)}. ` +
                         'Falling back to replay.');
-                    this.deps.conversation?.setCheckpoint(session.sessionId, null, session.agent.backend, { backendOwnerId: ownBackendInstanceId });
+                    this.deps.conversation?.setCheckpoint((0, conversation_1.conversationKey)(session), null, session.agent.backend, { backendOwnerId: ownBackendInstanceId });
                 }
             }
             if (!backendSessionId) {
@@ -741,7 +759,7 @@ class SessionRunner {
             // half-way still leaves a resumable session behind, and the alternative
             // — recording it only on success — loses the context in exactly the case
             // where the user most wants it back.
-            this.deps.conversation?.setCheckpoint(session.sessionId, backendSessionId, session.agent.backend, {
+            this.deps.conversation?.setCheckpoint((0, conversation_1.conversationKey)(session), backendSessionId, session.agent.backend, {
                 // WHICH INSTANCE minted it, so only this runner resumes it (#1591).
                 backendOwnerId: ownBackendInstanceId,
                 // The decision this backend session was CREATED under. The next turn
@@ -886,6 +904,7 @@ class SessionRunner {
              */
             this.turnContext = null;
             this.closeApproval(session.sessionId);
+            this.deps.knowledge?.host.bindTurn(session.sessionId, null);
             this.closeQuestion(session.sessionId);
             this.emittedApprovals.clear();
             /*
@@ -987,7 +1006,7 @@ class SessionRunner {
         // what lets this runner answer the next turn without a network call, and a
         // send that happens first would be lost on a crash between the two.
         try {
-            this.deps.conversation?.appendModelMessages(session.sessionId, modelMessages);
+            this.deps.conversation?.appendModelMessages((0, conversation_1.conversationKey)(session), modelMessages);
         }
         catch (caught) {
             // A cache that cannot be written is a slow next turn, not a failed one.
@@ -1839,8 +1858,8 @@ class SessionRunner {
     async loadMemory(session, ownBackendInstanceId) {
         this.priorMessageCount = 0;
         const store = this.deps.conversation;
-        const local = store?.getModelMessages(session.sessionId) ?? [];
-        const localCheckpoint = store?.getCheckpoint(session.sessionId) ?? null;
+        const local = store?.getModelMessages((0, conversation_1.conversationKey)(session)) ?? [];
+        const localCheckpoint = store?.getCheckpoint((0, conversation_1.conversationKey)(session)) ?? null;
         /*
          * Only meaningful when the checkpoint we are about to RESUME is the local
          * one. If the lease hands us a different backend session, the local record
@@ -1957,7 +1976,7 @@ class SessionRunner {
             const remote = await this.deps.fetchHistory(session.sessionId);
             // Cache it, so a second turn on this runner costs no network call.
             try {
-                store?.replaceModelMessages(session.sessionId, remote.messages);
+                store?.replaceModelMessages((0, conversation_1.conversationKey)(session), remote.messages);
             }
             catch {
                 /* a cache that will not write is a slow turn, not a failed one */
@@ -2039,6 +2058,34 @@ class SessionRunner {
         this.deps.secrets.registerSession(token, session.agent.agentId, []);
         return token;
     }
+    /**
+     * Make `space-files/` match this turn's Space files manifest (P9).
+     *
+     * Runs when the lease carries a manifest, or when this workspace already has a
+     * sync record: a chat that moved to a Space with no files must not keep the
+     * old Space's copies. Never throws; a failed sync is logged and the turn runs.
+     */
+    async syncSpaceFilesForTurn(session, workspaceDir) {
+        if (!session.spaceFiles && !(await (0, space_files_1.hasSpaceFilesState)(workspaceDir)))
+            return;
+        try {
+            const sync = await (0, space_files_1.syncSpaceFiles)(session.spaceFiles, workspaceDir, {
+                fetchImpl: this.deps.fetchAttachment,
+                logger: this.logger
+            });
+            this.deps.telemetry.record('provider.turn.space_files', {
+                present: sync.present.length,
+                downloaded: sync.downloaded.length,
+                kept: sync.kept.length,
+                removed: sync.removed.length,
+                failed: sync.failed.length,
+                notDownloaded: sync.notDownloaded.length
+            });
+        }
+        catch (error) {
+            this.logger.warn(`[SessionRunner] Space files sync failed: ${(error instanceof Error ? error.message : String(error)).replace(/https?:\/\/\S+/gi, '<url>')}`);
+        }
+    }
     /**
      * Build the backend's session config.
      *
@@ -2055,7 +2102,7 @@ class SessionRunner {
      * security perimeter and trusting it to filter its own tools is exactly
      * defect G2.
      */
-    buildSessionConfig(session, workspaceDir, secretToken, signal) {
+    buildSessionConfig(session, workspaceDir, secretToken, signal, knowledgeUrl = null) {
         const mcpServers = {};
         for (const server of session.agent.mcpServers) {
             const proxied = this.deps.proxy.registerTarget(server.url, server.name);
@@ -2073,6 +2120,18 @@ class SessionRunner {
                 this.logger.warn(`[SessionRunner] MCP server "${server.name}" omitted: proxy not running`);
             }
         }
+        /*
+         * The knowledge server is on loopback with a per-session path secret, so it
+         * is not routed through the GitHub/MCP token proxy: there is no vendor token
+         * on this hop, and the control plane authorises every call by lease.
+         */
+        if (knowledgeUrl) {
+            mcpServers[knowledge_tools_1.KNOWLEDGE_SERVER_NAME] = {
+                name: knowledge_tools_1.KNOWLEDGE_SERVER_NAME,
+                type: 'http',
+                url: knowledgeUrl
+            };
+        }
         const abort = new AbortController();
         signal.addEventListener('abort', () => abort.abort(), { once: true });
         const brokerPort = this.deps.secrets.getBrokerPort();
@@ -2098,7 +2157,8 @@ class SessionRunner {
             secretShellPath: this.deps.secrets.writeShellWrapper() ?? undefined,
             environment: this.deps.workspace.getEnvironment?.(session.sessionId, [
                 session.agent.model.gatewayUrl ?? '',
-                ...session.agent.mcpServers.map((server) => server.url)
+                ...session.agent.mcpServers.map((server) => server.url),
+                ...(knowledgeUrl ? [knowledgeUrl] : [])
             ]),
             /*
              * DEFECT G1, THE OTHER HALF.