npm - @phuetz/code-buddy - Versions diffs - 2.1.0 → 2.2.0 - Mend

@phuetz/code-buddy 2.1.0 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (41) hide show

package/README.fr.md +2 -2
package/README.md +3 -2
package/codebuddy-runtime.json +4 -4
package/dist/agent/execution/agent-executor.js +16 -5
package/dist/agent/execution/tool-selection-strategy.d.ts +7 -0
package/dist/agent/execution/tool-selection-strategy.js +13 -0
package/dist/codebuddy/fleet-tool-defs.d.ts +1 -0
package/dist/codebuddy/fleet-tool-defs.js +31 -0
package/dist/codebuddy/providers/provider-openai-compat.d.ts +7 -0
package/dist/codebuddy/providers/provider-openai-compat.js +28 -0
package/dist/commands/handlers/missing-handlers.js +8 -0
package/dist/commands/mcp.d.ts +13 -0
package/dist/commands/mcp.js +62 -21
package/dist/config/model-tools.js +99 -0
package/dist/doctor/integrations.d.ts +18 -0
package/dist/doctor/integrations.js +14 -0
package/dist/errors/crash-handler.js +2 -0
package/dist/mcp/client.d.ts +11 -0
package/dist/mcp/client.js +62 -3
package/dist/mcp/mcp-oauth-constants.d.ts +8 -0
package/dist/mcp/mcp-oauth-constants.js +9 -0
package/dist/mcp/mcp-oauth-provider.d.ts +80 -0
package/dist/mcp/mcp-oauth-provider.js +241 -0
package/dist/mcp/mcp-oauth.d.ts +60 -1
package/dist/mcp/mcp-oauth.js +241 -65
package/dist/mcp/transports.d.ts +4 -0
package/dist/mcp/transports.js +52 -3
package/dist/services/prompt-builder.js +3 -1
package/dist/services/runtime-settings-context.d.ts +8 -0
package/dist/services/runtime-settings-context.js +11 -1
package/dist/tools/metadata.js +9 -0
package/dist/tools/peer-tool-invoke-tool.d.ts +61 -0
package/dist/tools/peer-tool-invoke-tool.js +396 -0
package/dist/tools/registry/fleet-tools.d.ts +12 -3
package/dist/tools/registry/fleet-tools.js +116 -4
package/dist/tools/registry/index.d.ts +1 -1
package/dist/tools/registry/index.js +2 -2
package/dist/utils/config-validation/schema.d.ts +2 -2
package/dist/utils/graceful-shutdown.d.ts +8 -0
package/dist/utils/graceful-shutdown.js +23 -7
package/package.json +1 -1

package/dist/mcp/mcp-oauth.js CHANGED Viewed

@@ -11,6 +11,29 @@ import * as path from 'path';
 import { URL } from 'url';
 import { logger } from '../utils/logger.js';
 import { readTextAtomicSync, writeFileAtomicSync } from '../utils/atomic-write.js';
+import { SDK_MANAGED_TOKEN_URL } from './mcp-oauth-constants.js';
+function storedClientFrom(info) {
+    const client = { client_id: info.client_id };
+    if (info.client_secret)
+        client.client_secret = info.client_secret;
+    if (info.client_id_issued_at !== undefined)
+        client.client_id_issued_at = info.client_id_issued_at;
+    if (info.client_secret_expires_at !== undefined)
+        client.client_secret_expires_at = info.client_secret_expires_at;
+    if (info.redirect_uris?.length)
+        client.redirect_uris = [...info.redirect_uris];
+    if (info.token_endpoint_auth_method)
+        client.token_endpoint_auth_method = info.token_endpoint_auth_method;
+    if (info.grant_types?.length)
+        client.grant_types = [...info.grant_types];
+    if (info.response_types?.length)
+        client.response_types = [...info.response_types];
+    if (info.client_name)
+        client.client_name = info.client_name;
+    if (info.scope)
+        client.scope = info.scope;
+    return client;
+}
 // ============================================================================
 // PKCE (RFC 7636)
 // ============================================================================
@@ -35,7 +58,9 @@ export function generateCodeChallenge(verifier) {
 const ALGORITHM = 'aes-256-gcm';
 const SALT_LENGTH = 32;
 function getEncryptionKey() {
-    // Use CODEBUDDY_VAULT_KEY if available, otherwise derive from machine ID
+    // Prefer CODEBUDDY_VAULT_KEY or CODEBUDDY_MCP_KEY. The USER+platform fallback
+    // is derivable by anyone on the same account: AES-GCM still runs, but that is
+    // not a strong vault. Set an explicit key for real confidentiality.
     return process.env.CODEBUDDY_VAULT_KEY
         || process.env.CODEBUDDY_MCP_KEY
         || `mcp-oauth-${process.env.USER || process.env.USERNAME || 'default'}-${process.platform}`;
@@ -101,63 +126,153 @@ function saveTokenStore(store) {
     const encrypted = encryptData(JSON.stringify(store));
     writeFileAtomicSync(filePath, encrypted, { mode: 0o600 });
 }
+export class OAuthCallbackCancelledError extends Error {
+    constructor(message = 'OAuth authorization cancelled') {
+        super(message);
+        this.name = 'OAuthCallbackCancelledError';
+    }
+}
 /**
- * Start a temporary local HTTP server to receive the OAuth callback.
- * Returns a promise that resolves with the authorization code.
+ * Bind the loopback callback server. Callers must await `listening` before
+ * opening a browser: a bind failure must not leave an unhandled rejection
+ * nor launch a flow that can never complete.
  */
-function startCallbackServer(redirectUri, expectedState, timeoutMs = 120_000) {
-    return new Promise((resolve, reject) => {
-        const url = new URL(redirectUri);
-        const port = parseInt(url.port || '19836', 10);
-        const pathname = url.pathname || '/callback';
-        const server = http.createServer((req, res) => {
-            const reqUrl = new URL(req.url || '/', `http://localhost:${port}`);
-            if (reqUrl.pathname !== pathname) {
-                res.writeHead(404);
-                res.end('Not found');
-                return;
-            }
-            const code = reqUrl.searchParams.get('code');
-            const state = reqUrl.searchParams.get('state');
-            const error = reqUrl.searchParams.get('error');
-            if (error) {
-                res.writeHead(200, { 'Content-Type': 'text/html' });
-                res.end('<html><body><h1>Authorization Failed</h1><p>You can close this window.</p></body></html>');
-                server.close();
-                reject(new Error(`OAuth authorization error: ${error}`));
-                return;
-            }
-            if (!code) {
-                res.writeHead(400, { 'Content-Type': 'text/html' });
-                res.end('<html><body><h1>Missing authorization code</h1></body></html>');
-                return;
-            }
-            if (state !== expectedState) {
-                res.writeHead(400, { 'Content-Type': 'text/html' });
-                res.end('<html><body><h1>State mismatch — possible CSRF attack</h1></body></html>');
-                server.close();
-                reject(new Error('OAuth state mismatch'));
-                return;
-            }
+export function startCallbackSession(redirectUri, expectedState, timeoutMs = 120_000, signal) {
+    const url = new URL(redirectUri);
+    const port = parseInt(url.port || '19836', 10);
+    const pathname = url.pathname || '/callback';
+    let listenResolve;
+    let listenReject;
+    let resultResolve;
+    let resultReject;
+    let listeningSettled = false;
+    let resultSettled = false;
+    let timer;
+    let server;
+    const listening = new Promise((resolve, reject) => {
+        listenResolve = resolve;
+        listenReject = reject;
+    });
+    const result = new Promise((resolve, reject) => {
+        resultResolve = resolve;
+        resultReject = reject;
+    });
+    // Attach observers at construction so a pre-aborted signal cannot leave an
+    // unhandledRejection on the public startCallbackServer wrapper (the early
+    // return used to skip the .catch() that lived after listen()).
+    listening.catch(() => undefined);
+    result.catch(() => undefined);
+    const settleListen = (err) => {
+        if (listeningSettled)
+            return;
+        listeningSettled = true;
+        if (err)
+            listenReject(err);
+        else
+            listenResolve();
+    };
+    const settleResult = (value, err) => {
+        if (resultSettled)
+            return;
+        resultSettled = true;
+        if (timer)
+            clearTimeout(timer);
+        if (err)
+            resultReject(err);
+        else
+            resultResolve(value);
+    };
+    let abort;
+    const onAbort = () => abort(new OAuthCallbackCancelledError());
+    const detachAbort = () => signal?.removeEventListener('abort', onAbort);
+    abort = (reason) => {
+        detachAbort();
+        const fail = reason ?? new OAuthCallbackCancelledError();
+        if (!listeningSettled)
+            settleListen(fail);
+        if (!resultSettled)
+            settleResult(undefined, fail);
+        if (timer) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+        if (server) {
+            server.removeAllListeners('error');
+            const closing = server;
+            server = undefined;
+            closing.close();
+        }
+    };
+    if (signal?.aborted) {
+        abort(new OAuthCallbackCancelledError());
+        return { listening, result, abort };
+    }
+    signal?.addEventListener('abort', onAbort, { once: true });
+    timer = setTimeout(() => {
+        abort(new Error('OAuth callback timed out (120s)'));
+        detachAbort();
+    }, timeoutMs);
+    server = http.createServer((req, res) => {
+        const reqUrl = new URL(req.url || '/', `http://127.0.0.1:${port}`);
+        if (reqUrl.pathname !== pathname) {
+            res.writeHead(404);
+            res.end('Not found');
+            return;
+        }
+        const code = reqUrl.searchParams.get('code');
+        const state = reqUrl.searchParams.get('state');
+        const error = reqUrl.searchParams.get('error');
+        if (error) {
             res.writeHead(200, { 'Content-Type': 'text/html' });
-            res.end('<html><body><h1>Authorization Successful</h1><p>You can close this window and return to the terminal.</p></body></html>');
-            server.close();
-            resolve({ code, state });
-        });
-        // Set timeout
-        const timer = setTimeout(() => {
-            server.close();
-            reject(new Error('OAuth callback timed out (120s)'));
-        }, timeoutMs);
-        server.on('close', () => clearTimeout(timer));
-        server.on('error', (err) => {
+            res.end('<html><body><h1>Authorization Failed</h1><p>You can close this window.</p></body></html>');
+            detachAbort();
+            abort(new Error(`OAuth authorization error: ${error}`));
+            return;
+        }
+        if (!code) {
+            res.writeHead(400, { 'Content-Type': 'text/html' });
+            res.end('<html><body><h1>Missing authorization code</h1></body></html>');
+            return;
+        }
+        if (state !== expectedState) {
+            res.writeHead(400, { 'Content-Type': 'text/html' });
+            res.end('<html><body><h1>State mismatch — possible CSRF attack</h1></body></html>');
+            detachAbort();
+            abort(new Error('OAuth state mismatch'));
+            return;
+        }
+        res.writeHead(200, { 'Content-Type': 'text/html' });
+        res.end('<html><body><h1>Authorization Successful</h1><p>You can close this window and return to the terminal.</p></body></html>');
+        detachAbort();
+        if (timer) {
             clearTimeout(timer);
-            reject(new Error(`Failed to start callback server: ${err.message}`));
-        });
-        server.listen(port, '127.0.0.1', () => {
-            logger.debug(`OAuth callback server listening on port ${port}`);
-        });
+            timer = undefined;
+        }
+        const closing = server;
+        server = undefined;
+        closing?.removeAllListeners('error');
+        closing?.close();
+        settleListen();
+        settleResult({ code, state });
+    });
+    server.on('error', (err) => {
+        detachAbort();
+        abort(new Error(`Failed to start callback server: ${err.message}`));
     });
+    server.listen(port, '127.0.0.1', () => {
+        logger.debug(`OAuth callback server listening on port ${port}`);
+        settleListen();
+    });
+    return { listening, result, abort };
+}
+/**
+ * Start a temporary local HTTP server to receive the OAuth callback.
+ * Awaits a successful listen before waiting for the code.
+ */
+export async function startCallbackServer(redirectUri, expectedState, timeoutMs = 120_000, signal) {
+    const session = startCallbackSession(redirectUri, expectedState, timeoutMs, signal);
+    await session.listening;
+    return session.result;
 }
 // ============================================================================
 // Browser Opener
@@ -165,7 +280,7 @@ function startCallbackServer(redirectUri, expectedState, timeoutMs = 120_000) {
 /**
  * Open a URL in the default browser (cross-platform)
  */
-async function openBrowser(url) {
+export async function openBrowser(url) {
     const { exec } = await import('child_process');
     const command = process.platform === 'win32'
         ? `start "" "${url}"`
@@ -244,9 +359,11 @@ export class MCPOAuthManager {
         authUrl.searchParams.set('state', state);
         authUrl.searchParams.set('code_challenge', codeChallenge);
         authUrl.searchParams.set('code_challenge_method', 'S256');
-        // Start callback server
-        const callbackPromise = startCallbackServer(redirectUri, state);
-        // Open browser
+        // Bind the loopback callback before opening the browser: a listen failure
+        // must not launch a flow that can never complete (same contract as the SDK
+        // provider path). Keep the manual URL if the opener fails.
+        const session = startCallbackSession(redirectUri, state);
+        await session.listening;
         logger.info('Opening browser for OAuth authorization...');
         try {
             await openBrowser(authUrl.toString());
@@ -254,8 +371,7 @@ export class MCPOAuthManager {
         catch {
             logger.info(`Please open this URL in your browser:\n${authUrl.toString()}`);
         }
-        // Wait for callback
-        const { code } = await callbackPromise;
+        const { code } = await session.result;
         // Exchange code for token
         const token = await exchangeCodeForToken(config, code, codeVerifier, redirectUri);
         // Store token
@@ -306,14 +422,20 @@ export class MCPOAuthManager {
         // Load from disk
         const store = loadTokenStore();
         const entry = store[serverId];
-        if (!entry)
+        const token = entry?.token;
+        if (!token?.accessToken || !entry)
             return null;
-        const { token, config } = entry;
+        const { config } = entry;
         // If token is still valid (with 60s buffer), return it
         if (token.expiresAt > Date.now() + 60_000) {
             this.tokenCache.set(serverId, token);
             return token.accessToken;
         }
+        // Entries written by the SDK-backed provider are refreshed by the SDK itself.
+        if (config.tokenUrl === SDK_MANAGED_TOKEN_URL) {
+            logger.debug(`MCP OAuth token for ${serverId} is SDK-managed; refresh happens on the next transport connection`);
+            return null;
+        }
         // Try to refresh
         if (token.refreshToken) {
             try {
@@ -340,17 +462,42 @@ export class MCPOAuthManager {
         return null;
     }
     /**
-     * Store a token encrypted on disk and in memory cache
+     * Store a token encrypted on disk and in memory cache.
+     * Preserves any previously persisted client metadata for the same server.
      */
     storeToken(serverId, token, config) {
         this.tokenCache.set(serverId, token);
         const store = loadTokenStore();
+        const prev = store[serverId];
+        const clientId = config.clientId || prev?.config.clientId || prev?.client?.client_id || '';
+        const client = prev?.client
+            ? storedClientFrom({ ...prev.client, ...(clientId ? { client_id: clientId } : {}) })
+            : (clientId ? storedClientFrom({ client_id: clientId }) : undefined);
         store[serverId] = {
             token,
             config: {
-                clientId: config.clientId,
-                tokenUrl: config.tokenUrl,
+                clientId,
+                tokenUrl: config.tokenUrl || prev?.config.tokenUrl || SDK_MANAGED_TOKEN_URL,
+            },
+            ...(client ? { client } : {}),
+        };
+        saveTokenStore(store);
+    }
+    /**
+     * Persist client registration (client_id and optional DCR metadata) in the
+     * encrypted store, even before a token exists. Never writes plaintext.
+     */
+    storeClientInformation(serverId, info) {
+        const client = storedClientFrom(info);
+        const store = loadTokenStore();
+        const prev = store[serverId];
+        store[serverId] = {
+            ...(prev?.token ? { token: prev.token } : {}),
+            config: {
+                clientId: client.client_id,
+                tokenUrl: prev?.config.tokenUrl ?? SDK_MANAGED_TOKEN_URL,
             },
+            client,
         };
         saveTokenStore(store);
     }
@@ -363,12 +510,41 @@ export class MCPOAuthManager {
         delete store[serverId];
         saveTokenStore(store);
     }
+    /** Drop access/refresh tokens only; keep client_id and DCR metadata. */
+    clearTokens(serverId) {
+        this.tokenCache.delete(serverId);
+        const store = loadTokenStore();
+        const prev = store[serverId];
+        if (!prev)
+            return;
+        const { token: _dropped, ...rest } = prev;
+        store[serverId] = rest;
+        if (!rest.client && !rest.config?.clientId)
+            delete store[serverId];
+        saveTokenStore(store);
+    }
     /**
      * Check if a token exists for a server (may be expired)
      */
+    /** Stored token and client id for a server, without refresh side effects. */
+    getStoredToken(serverId) {
+        const entry = loadTokenStore()[serverId];
+        if (!entry?.token?.accessToken)
+            return null;
+        return { token: entry.token, clientId: entry.config.clientId, ...(entry.client ? { client: entry.client } : {}) };
+    }
+    /** Persisted client id / DCR metadata, independent of whether a token exists. */
+    getStoredClientInformation(serverId) {
+        const entry = loadTokenStore()[serverId];
+        if (entry?.client?.client_id)
+            return entry.client;
+        if (entry?.config.clientId)
+            return { client_id: entry.config.clientId };
+        return null;
+    }
     hasToken(serverId) {
         const store = loadTokenStore();
-        return serverId in store;
+        return Boolean(store[serverId]?.token?.accessToken);
     }
 }
 // ============================================================================

package/dist/mcp/transports.d.ts CHANGED Viewed

@@ -1,4 +1,5 @@
 import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { type MCPTransportOAuthConfig } from "./mcp-oauth-provider.js";
 import { EventEmitter } from "events";
 export type TransportType = 'stdio' | 'http' | 'sse' | 'sse_sdk' | 'legacy_rpc' | 'streamable_http';
 export interface TransportConfig {
@@ -11,6 +12,8 @@ export interface TransportConfig {
     env?: Record<string, string>;
     url?: string;
     headers?: Record<string, string>;
+    /** OAuth bearer for HTTP transports (SDK discovery + PKCE, tokens in .codebuddy/mcp-tokens.json). */
+    auth?: MCPTransportOAuthConfig;
 }
 export interface MCPTransport {
     connect(): Promise<Transport>;
@@ -45,6 +48,7 @@ export declare class SSETransport implements MCPTransport {
 export declare class StreamableHttpTransport extends EventEmitter implements MCPTransport {
     private config;
     private transport?;
+    private oauthProvider?;
     constructor(config: TransportConfig);
     connect(): Promise<Transport>;
     disconnect(): Promise<void>;

package/dist/mcp/transports.js CHANGED Viewed

@@ -1,6 +1,7 @@
 import { SSEClientTransport as SDKSSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { StdioClientTransport, getDefaultEnvironment } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { createOAuthProvider } from "./mcp-oauth-provider.js";
 import { EventEmitter } from "events";
 import axios from "axios";
 import { logger } from '../utils/logger.js';
@@ -49,10 +50,14 @@ export class StdioTransport {
     }
     async disconnect() {
         if (this.transport) {
-            await this.transport.close();
-            this.transport = undefined;
+            try {
+                await this.transport.close();
+            }
+            finally {
+                this.transport = undefined;
+            }
         }
-        // The StdioClientTransport from the SDK is expected to terminate the child process.
+        // SDK close() ends stdin, then SIGTERM/SIGKILL the child it spawned.
     }
     getType() {
         return 'stdio';
@@ -156,6 +161,7 @@ class HttpClientTransport extends EventEmitter {
 export class StreamableHttpTransport extends EventEmitter {
     config;
     transport;
+    oauthProvider;
     constructor(config) {
         super();
         this.config = config;
@@ -167,12 +173,18 @@ export class StreamableHttpTransport extends EventEmitter {
         if (!['http:', 'https:'].includes(url.protocol)) {
             throw new Error('Streamable HTTP MCP requires an HTTP(S) URL');
         }
+        const provider = this.config.auth?.type === 'oauth' ? createOAuthProvider(this.config.url, this.config.auth) : undefined;
+        this.oauthProvider = provider;
         this.transport = new StreamableHTTPClientTransport(url, {
             requestInit: { headers: this.config.headers, redirect: 'error' },
+            ...(provider ? { authProvider: provider } : {}),
         });
+        provider?.attachTransport(this.transport);
         return this.transport;
     }
     async disconnect() {
+        this.oauthProvider?.abortAuthorization();
+        this.oauthProvider = undefined;
         const transport = this.transport;
         this.transport = undefined;
         await transport?.close();
@@ -203,10 +215,47 @@ export function resolveMCPTransport(config) {
         if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash)
             throw new Error('MCP requires HTTP(S) without embedded credentials, query or fragment');
     }
+    if (config.auth) {
+        const auth = { ...config.auth,
+            serverId: config.auth.serverId && resolve(config.auth.serverId),
+            clientId: config.auth.clientId && resolve(config.auth.clientId),
+            clientMetadataUrl: config.auth.clientMetadataUrl && resolve(config.auth.clientMetadataUrl),
+            redirectUri: config.auth.redirectUri && resolve(config.auth.redirectUri) };
+        if (auth.redirectUri) {
+            // The authorization code must only ever come back to the local callback server.
+            let redirect;
+            try {
+                redirect = new URL(auth.redirectUri);
+            }
+            catch {
+                throw new Error('MCP OAuth redirectUri must be a loopback http URL');
+            }
+            // Hostname localhost is allowed so a CIMD document's redirect_uris can match.
+            // The callback server still binds 127.0.0.1 only — a browser that resolves
+            // localhost to ::1 will not hit it. Use 127.0.0.1 when the metadata says so.
+            if (redirect.protocol !== 'http:' || !['127.0.0.1', 'localhost'].includes(redirect.hostname))
+                throw new Error('MCP OAuth redirectUri must be a loopback http URL');
+        }
+        if (auth.clientMetadataUrl) {
+            let meta;
+            try {
+                meta = new URL(auth.clientMetadataUrl);
+            }
+            catch {
+                throw new Error('MCP OAuth clientMetadataUrl must be an https URL with a document path');
+            }
+            if (meta.protocol !== 'https:' || meta.pathname === '/')
+                throw new Error('MCP OAuth clientMetadataUrl must be an https URL with a document path');
+        }
+        return { ...resolved, auth };
+    }
     return resolved;
 }
 export function createTransport(input) {
     const config = resolveMCPTransport(input);
+    if (config.auth?.type === 'oauth' && config.type !== 'streamable_http') {
+        throw new Error(`MCP OAuth is only supported on streamable_http (got ${config.type}); refusing to connect without the authProvider.`);
+    }
     switch (config.type) {
         case 'stdio':
             return new StdioTransport(config);

package/dist/services/prompt-builder.js CHANGED Viewed

@@ -597,7 +597,9 @@ export class PromptBuilder {
                             `provider status, or list_peers() for a quick status. Then ` +
                             `peer_delegate can ask the chosen peer a question; reuse the ` +
                             `dispatchProfile returned by route_peer so the peer receives ` +
-                            `matching guidance. For ordered specialist collaboration, pass ` +
+                            `matching guidance. To read a file on a peer, call ` +
+                            `peer_tool_invoke({"peer":"<id>","tool":"view_file","args":{"path":"oracle.txt"}}) ` +
+                            `after list_peers — always pass peer and tool. For ordered specialist collaboration, pass ` +
                             `chainRoles such as ["code","review","safe"] to route_peer and ` +
                             `then run the returned nextCalls in order, or call peer_chain ` +
                             `to route and execute the chain with stage handoffs. The peer answers ` +

package/dist/services/runtime-settings-context.d.ts CHANGED Viewed

@@ -69,5 +69,13 @@ export declare function getRuntimeSettingsSnapshot(evidence?: RuntimeSettingsEvi
     provider: string;
 };
 export declare function formatRuntimeSettingsContext(evidence: RuntimeSettingsEvidence): string;
+/**
+ * Fleet tools force-included only for a fleet inspection query, or when
+ * peers are actually registered. Never part of the global alwaysInclude
+ * default (zero token cost with an empty registry).
+ */
+export declare const FLEET_SURFACE_TOOLS: readonly ["list_peers", "route_peer", "peer_delegate", "peer_tool_invoke"];
+/** Force-include fleet tools when at least one peer is registered. */
+export declare function connectedFleetSurfaceTools(): string[];
 /** Ensure operational questions can reach the existing tools even with RAG selection. */
 export declare function runtimeInspectionTools(query: string): string[];

package/dist/services/runtime-settings-context.js CHANGED Viewed

@@ -55,11 +55,21 @@ export function formatRuntimeSettingsContext(evidence) {
     return '<runtime_settings ephemeral="true">\n' +
         JSON.stringify(getRuntimeSettingsSnapshot(evidence)) + '\n</runtime_settings>';
 }
+/**
+ * Fleet tools force-included only for a fleet inspection query, or when
+ * peers are actually registered. Never part of the global alwaysInclude
+ * default (zero token cost with an empty registry).
+ */
+export const FLEET_SURFACE_TOOLS = ['list_peers', 'route_peer', 'peer_delegate', 'peer_tool_invoke'];
+/** Force-include fleet tools when at least one peer is registered. */
+export function connectedFleetSurfaceTools() {
+    return getFleetRegistry().size() > 0 ? [...FLEET_SURFACE_TOOLS] : [];
+}
 /** Ensure operational questions can reach the existing tools even with RAG selection. */
 export function runtimeInspectionTools(query) {
     const text = query.normalize('NFD').replace(/[\u0300-\u036f]/g, '').toLowerCase();
     if (/\b(fleet|flotte|peers?|autres? (?:code[ -]?)?budd(?:y|ies)|other (?:code[ -]?)?budd(?:y|ies)|instances? (?:actives?|buddy)|buddy.*ensemble)\b/.test(text)) {
-        return ['list_peers', 'route_peer', 'peer_delegate'];
+        return [...FLEET_SURFACE_TOOLS];
     }
     if (/\b(theme|parametres?|parametrage|settings|configuration actuelle|current configuration)\b/.test(text)) {
         return ['self_describe'];

package/dist/tools/metadata.js CHANGED Viewed

@@ -1736,6 +1736,15 @@ export const TOOL_METADATA = [
         priority: 7,
         description: 'Delegate a one-shot question to a connected fleet peer Code Buddy and get its answer plus Hermes-style dispatch policy metadata back inline'
     },
+    {
+        name: 'peer_tool_invoke',
+        effect: 'emission',
+        category: 'utility',
+        keywords: ['peer', 'tool', 'invoke', 'fleet', 'view_file', 'list_directory', 'search', 'read', 'remote', 'workspace', 'allowlist', 'file', 'oracle'],
+        priority: 8,
+        description: 'Read a file on a connected fleet peer. Always pass peer and tool, e.g. {"peer":"B","tool":"view_file","args":{"path":"oracle.txt"}}'
+        // fleetSafe omitted / false: outbound fleet call, not peer-exposable.
+    },
     {
         name: 'peer_chain',
         effect: 'emission',

package/dist/tools/peer-tool-invoke-tool.d.ts ADDED Viewed

@@ -0,0 +1,61 @@
+/**
+ * peer_tool_invoke tool — wraps `peer.tool.invoke` for the local agent.
+ *
+ * Lets the LLM read/search on a connected fleet peer (view_file,
+ * list_directory, search) without going through `peer.chat` (which has
+ * no tools). The three security gates stay on the remote peer
+ * (`peer-tool-bridge.ts`): allowlist, fleetSafe, workspace root.
+ *
+ * Extra tool names from `peer.describe` are trusted only when
+ * `CODEBUDDY_PEER_TRUST_DESCRIBE=true`. B still enforces its own
+ * allowlist even then.
+ *
+ * This side (A) does not interpret paths and does not add new remote
+ * capabilities. Failures always return `success: false`.
+ *
+ * @module src/tools/peer-tool-invoke-tool
+ */
+import type { ToolResult } from '../types/index.js';
+export declare const DEFAULT_PEER_TOOL_INVOKE_TOOLS: readonly ["view_file", "list_directory", "search"];
+export declare const DEFAULT_TIMEOUT_MS = 15000;
+export declare const MIN_TIMEOUT_MS = 1000;
+export declare const MAX_TIMEOUT_MS = 120000;
+export declare const MAX_ARGS_BYTES: number;
+export declare const MAX_OUTPUT_BYTES: number;
+export declare const MAX_PEER_ID_LENGTH = 128;
+export declare const MAX_TOOL_NAME_LENGTH = 64;
+/** Imperative tool description with a concrete call example for local models. */
+export declare const PEER_TOOL_INVOKE_DESCRIPTION: string;
+export declare const PEER_TOOL_INVOKE_PARAM_DESCRIPTIONS: {
+    readonly peer: "Required. Connected peer id from list_peers (the --name of /fleet listen). Example: \"B\".";
+    readonly tool: "Required. Read-only tool on that peer. Default set: view_file, list_directory, search. Extra names from peer.describe are accepted only when CODEBUDDY_PEER_TRUST_DESCRIBE=true. Example: \"view_file\".";
+    readonly args: "Object of arguments for the remote tool. For view_file use {\"path\":\"oracle.txt\"} or {\"file_path\":\"oracle.txt\"}. For list_directory use {\"path\":\".\"}. For search use {\"query\":\"TODO\",\"path\":\"src\"}. Paths are relative to the peer workspace and are not resolved on this host.";
+    readonly timeoutMs: "Optional timeout in milliseconds. Default 15000. Min 1000. Max 120000.";
+};
+export declare const PEER_ID_RE: RegExp;
+export interface PeerToolInvokeParams {
+    peer: string;
+    tool: string;
+    args?: Record<string, unknown>;
+    timeoutMs?: number;
+}
+export interface PeerToolInvokeData {
+    peer: string;
+    tool: string;
+    output: string;
+    durationMs: number;
+    truncated?: boolean;
+    elapsedMs: number;
+}
+export type PeerToolInvokeResult = ToolResult & {
+    data?: PeerToolInvokeData;
+};
+export declare function clampPeerToolInvokeTimeout(raw: unknown): number;
+export declare function isFlatToolArgs(value: unknown): value is Record<string, unknown>;
+/**
+ * Strip absolute paths and secrets from a peer error before it reaches the
+ * model. Known refusal codes are mapped to path-free sentences; this covers
+ * the unrecognized fallback (and peer.describe failures).
+ */
+export declare function redactPeerToolInvokeError(text: string): string;
+export declare function executePeerToolInvoke(params: PeerToolInvokeParams): Promise<PeerToolInvokeResult>;