agentic-qe 3.14.0 → 3.14.2

package/dist/mcp/index.d.ts

@@ -3,6 +3,7 @@
  * Model Context Protocol server and tools
  */
 export * from './types';
+export { CONSERVATIVE_TOOL_ANNOTATIONS, BUILT_IN_TOOL_NAMES, BUILT_IN_TOOL_SAFETY_INVENTORY, getBuiltInToolAnnotations, getBuiltInToolSafetyInventory, resolveToolAnnotations, type ResolvedToolAnnotations, } from './tool-annotations';
 export { ToolRegistry, createToolRegistry } from './tool-registry';
 export { getConnectionPool, initializeConnectionPool, shutdownConnectionPool, createConnectionPool, type PoolConnection, type ConnectionMetrics, type ConnectionPoolConfig, type PoolStats, DEFAULT_POOL_CONFIG, } from './connection-pool';
 export { getLoadBalancer, resetLoadBalancer, createLoadBalancer, type AgentLoadInfo, type LoadBalancingStrategy, type LoadBalancerConfig, type LoadBalancerStats, DEFAULT_LOAD_BALANCER_CONFIG, } from './load-balancer';

package/dist/mcp/index.js

@@ -4,6 +4,7 @@
  */
 // Types
 export * from './types.js';
+export { CONSERVATIVE_TOOL_ANNOTATIONS, BUILT_IN_TOOL_NAMES, BUILT_IN_TOOL_SAFETY_INVENTORY, getBuiltInToolAnnotations, getBuiltInToolSafetyInventory, resolveToolAnnotations, } from './tool-annotations.js';
 // Tool Registry (O(1) hash-indexed lookup via Map)
 export { ToolRegistry, createToolRegistry } from './tool-registry.js';
 // Connection Pool (ADR-039)

package/dist/mcp/protocol-server.js

@@ -7,6 +7,7 @@
  */
 import { createStdioTransport, JSON_RPC_ERRORS, isJsonRpcCodedError, McpError, } from './transport/index.js';
 import { createToolRegistry } from './tool-registry.js';
+import { resolveToolAnnotations } from './tool-annotations.js';
 import { MiddlewareChain } from './middleware/middleware-chain.js';
 import { createMicrocompactMiddleware } from './middleware/microcompact.js';
 import { SessionStore } from './services/session-store.js';
@@ -374,6 +375,7 @@ export class MCPProtocolServer {
         const tools = Array.from(this.tools.values()).map((entry) => ({
             name: entry.definition.name,
             description: entry.definition.description,
+            annotations: entry.definition.annotations,
             inputSchema: this.buildInputSchema(entry.definition),
         }));
         return { tools };
@@ -1446,8 +1448,15 @@ export class MCPProtocolServer {
         console.error(`[MCP] Registered ${this.tools.size} tools (${bridgedCount} via QE bridge)`);
     }
     registerTool(entry) {
-        this.tools.set(entry.definition.name, entry);
-        this.registry.register(entry.definition, entry.handler);
+        const normalizedEntry = {
+            ...entry,
+            definition: {
+                ...entry.definition,
+                annotations: resolveToolAnnotations(entry.definition.name, entry.definition.annotations),
+            },
+        };
+        this.tools.set(normalizedEntry.definition.name, normalizedEntry);
+        this.registry.register(normalizedEntry.definition, normalizedEntry.handler);
     }
     buildInputSchema(definition) {
         const properties = {};

package/dist/mcp/qe-tool-bridge.js

@@ -72,6 +72,7 @@ export function registerMissingQETools(registerFn) {
                 name: tool.name,
                 description: tool.description,
                 category: 'domain',
+                annotations: tool.annotations,
                 parameters: schemaToParameters(tool),
             },
             handler: async (params) => {

package/dist/mcp/services/session-resume.d.ts

@@ -1,29 +1,25 @@
-/**
- * Agentic QE v3 - Session Resume Service
- *
- * IMP-04: Transcript-First Session Durability
- * Reads an existing JSONL session file by sampling the head (first 4KB)
- * and tail (last 64KB) to reconstruct metadata and recent entries
- * without reading the entire file.
- *
- * @module mcp/services/session-resume
- */
 import type { SessionEntry, SessionMetadata } from './session-store';
+export type SessionRecoveryDisposition = 'MISSING' | 'EMPTY' | 'LEGACY_UNVERIFIED' | 'INVALID' | 'UNTRUSTED' | 'RESOURCE_LIMIT';
+export interface SessionResumeOptions {
+    /** Canonical directory that must contain the session file. */
+    sessionRoot: string;
+    /** Explicit compatibility opt-in; legacy JSONL has no commit proof. */
+    allowLegacyUnverified?: boolean;
+    maxFileBytes?: number;
+    maxRecordBytes?: number;
+    maxRecords?: number;
+}
 export interface SessionResumeResult {
     metadata: SessionMetadata;
     recentEntries: SessionEntry[];
     lastState: 'idle' | 'running' | 'requires_action';
     canResume: boolean;
+    disposition: SessionRecoveryDisposition;
+    diagnostics: string[];
 }
 /**
- * Resume a session from a JSONL file.
- *
- * Reads the first 4KB (head) to extract session start metadata and
- * the last 64KB (tail) to get recent entries. Parses JSONL lines,
- * reconstructs the parentUuid linked list, and returns metadata +
- * recent entries + resume capability.
- *
- * Corrupt or incomplete lines are skipped gracefully.
+ * Inspect a legacy transcript through one no-follow descriptor. Automatic
+ * resume requires an explicit opt-in because this format has no commit marker.
  */
-export declare function resumeSession(filePath: string): SessionResumeResult;
+export declare function resumeSession(filePath: string, options: SessionResumeOptions): SessionResumeResult;
 //# sourceMappingURL=session-resume.d.ts.map

package/dist/mcp/services/session-resume.js

@@ -1,221 +1,231 @@
-/**
- * Agentic QE v3 - Session Resume Service
- *
- * IMP-04: Transcript-First Session Durability
- * Reads an existing JSONL session file by sampling the head (first 4KB)
- * and tail (last 64KB) to reconstruct metadata and recent entries
- * without reading the entire file.
- *
- * @module mcp/services/session-resume
- */
+/** Bounded, fail-closed recovery for legacy JSONL session transcripts. */
 import * as fs from 'fs';
 import * as path from 'path';
-// ============================================================================
-// Constants
-// ============================================================================
-const HEAD_BYTES = 4 * 1024; // 4KB
-const TAIL_BYTES = 64 * 1024; // 64KB
-// ============================================================================
-// Public API
-// ============================================================================
-/**
- * Resume a session from a JSONL file.
- *
- * Reads the first 4KB (head) to extract session start metadata and
- * the last 64KB (tail) to get recent entries. Parses JSONL lines,
- * reconstructs the parentUuid linked list, and returns metadata +
- * recent entries + resume capability.
- *
- * Corrupt or incomplete lines are skipped gracefully.
- */
-export function resumeSession(filePath) {
-    // If file doesn't exist, return non-resumable result
-    if (!fs.existsSync(filePath)) {
-        return {
-            metadata: {
-                sessionId: extractSessionId(filePath),
-                createdAt: 0,
-                lastActivityAt: 0,
-                entryCount: 0,
-                state: 'idle',
-            },
-            recentEntries: [],
-            lastState: 'idle',
-            canResume: false,
-        };
-    }
-    const stat = fs.statSync(filePath);
-    const fileSize = stat.size;
-    if (fileSize === 0) {
-        return {
-            metadata: {
-                sessionId: extractSessionId(filePath),
-                createdAt: 0,
-                lastActivityAt: 0,
-                entryCount: 0,
-                state: 'idle',
-            },
-            recentEntries: [],
-            lastState: 'idle',
-            canResume: false,
-        };
-    }
-    // Read head (first 4KB)
-    const headEntries = readHead(filePath, fileSize);
-    // Read tail (last 64KB)
-    const tailEntries = readTail(filePath, fileSize);
-    // Merge and deduplicate: use a Map keyed by uuid to ensure uniqueness
-    const entryMap = new Map();
-    for (const entry of headEntries) {
-        entryMap.set(entry.uuid, entry);
-    }
-    for (const entry of tailEntries) {
-        entryMap.set(entry.uuid, entry);
-    }
-    const allEntries = Array.from(entryMap.values());
-    allEntries.sort((a, b) => a.timestamp - b.timestamp);
-    // Reconstruct metadata from available entries
-    const firstEntry = headEntries[0] ?? allEntries[0];
-    const lastEntry = tailEntries[tailEntries.length - 1] ?? allEntries[allEntries.length - 1];
-    // For entry count: if file is small enough that head+tail overlap,
-    // allEntries.length is accurate. Otherwise, count total lines.
-    let entryCount;
-    if (fileSize <= HEAD_BYTES + TAIL_BYTES) {
-        entryCount = allEntries.length;
-    }
-    else {
-        entryCount = countLines(filePath);
-    }
-    const lastState = lastEntry?.state ?? 'idle';
-    const metadata = {
-        sessionId: extractSessionId(filePath),
-        createdAt: firstEntry?.timestamp ?? 0,
-        lastActivityAt: lastEntry?.timestamp ?? 0,
-        entryCount,
-        state: lastState,
-    };
+const DEFAULT_MAX_FILE_BYTES = 16 * 1024 * 1024;
+const DEFAULT_MAX_RECORD_BYTES = 1024 * 1024;
+const DEFAULT_MAX_RECORDS = 100_000;
+const RECENT_ENTRY_LIMIT = 256;
+const ENTRY_TYPES = new Set(['tool_call', 'tool_result', 'state_change', 'error']);
+const ENTRY_STATES = new Set(['idle', 'running', 'requires_action']);
+const ENTRY_KEYS = new Set([
+    'uuid', 'parentUuid', 'timestamp', 'type', 'toolName', 'params', 'result', 'state', 'tokenEstimate',
+]);
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function emptyResult(filePath, disposition, diagnostics = []) {
     return {
-        metadata,
-        recentEntries: tailEntries,
-        lastState,
-        canResume: allEntries.length > 0,
+        metadata: {
+            sessionId: path.basename(filePath, '.jsonl'), createdAt: 0, lastActivityAt: 0,
+            entryCount: 0, state: 'idle',
+        },
+        recentEntries: [], lastState: 'idle', canResume: false, disposition, diagnostics,
     };
 }
-// ============================================================================
-// Private helpers
-// ============================================================================
-/**
- * Extract session ID from file path (filename without extension).
- */
-function extractSessionId(filePath) {
-    return path.basename(filePath, '.jsonl');
+function isWithin(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
 }
-/**
- * Read and parse the first HEAD_BYTES of the file.
- */
-function readHead(filePath, fileSize) {
-    const bytesToRead = Math.min(HEAD_BYTES, fileSize);
-    const fd = fs.openSync(filePath, 'r');
+function isValidEntry(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const entry = value;
+    if (Object.keys(entry).some(key => !ENTRY_KEYS.has(key)))
+        return false;
+    const params = entry.params;
+    return typeof entry.uuid === 'string' && UUID_PATTERN.test(entry.uuid)
+        && (entry.parentUuid === null
+            || (typeof entry.parentUuid === 'string' && UUID_PATTERN.test(entry.parentUuid)))
+        && typeof entry.timestamp === 'number' && Number.isSafeInteger(entry.timestamp) && entry.timestamp >= 0
+        && typeof entry.type === 'string' && ENTRY_TYPES.has(entry.type)
+        && typeof entry.state === 'string' && ENTRY_STATES.has(entry.state)
+        && (entry.toolName === undefined || (typeof entry.toolName === 'string' && entry.toolName.length > 0))
+        && (params === undefined || (typeof params === 'object' && params !== null && !Array.isArray(params)))
+        && (entry.tokenEstimate === undefined || (typeof entry.tokenEstimate === 'number'
+            && Number.isSafeInteger(entry.tokenEstimate)
+            && entry.tokenEstimate >= 0));
+}
+function resolveLimit(value, defaultValue) {
+    const limit = value ?? defaultValue;
+    return Number.isSafeInteger(limit) && limit > 0 && limit <= defaultValue ? limit : undefined;
+}
+function sameFile(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function validateOpenedPath(fd, candidate, root, openedStat) {
     try {
-        const buffer = Buffer.alloc(bytesToRead);
-        fs.readSync(fd, buffer, 0, bytesToRead, 0);
-        const text = buffer.toString('utf-8');
-        return parseJsonlLines(text, /* isHead */ true);
+        const canonicalTarget = fs.realpathSync(candidate);
+        const currentStat = fs.lstatSync(candidate);
+        if (!isWithin(root, canonicalTarget) || currentStat.isSymbolicLink() || !sameFile(openedStat, currentStat)) {
+            return 'session path changed or escaped the configured root';
+        }
+        // Linux exposes the descriptor target directly. This closes intermediate
+        // component substitution without relying only on the current pathname.
+        if (process.platform === 'linux') {
+            const descriptorTarget = fs.realpathSync(`/proc/self/fd/${fd}`);
+            if (!isWithin(root, descriptorTarget))
+                return 'opened session descriptor escapes the configured root';
+        }
     }
-    finally {
-        fs.closeSync(fd);
+    catch {
+        return 'opened session path cannot be verified';
     }
+    return undefined;
+}
+function readExactly(fd, fileSize) {
+    const buffer = Buffer.alloc(fileSize);
+    let offset = 0;
+    while (offset < fileSize) {
+        const count = fs.readSync(fd, buffer, offset, fileSize - offset, offset);
+        if (count === 0)
+            throw new Error('unexpected EOF while reading session transcript');
+        offset += count;
+    }
+    return buffer;
 }
 /**
- * Read and parse the last TAIL_BYTES of the file.
+ * Inspect a legacy transcript through one no-follow descriptor. Automatic
+ * resume requires an explicit opt-in because this format has no commit marker.
  */
-function readTail(filePath, fileSize) {
-    const bytesToRead = Math.min(TAIL_BYTES, fileSize);
-    const offset = Math.max(0, fileSize - bytesToRead);
-    const fd = fs.openSync(filePath, 'r');
+export function resumeSession(filePath, options) {
+    if (!options || typeof options.sessionRoot !== 'string' || options.sessionRoot.trim().length === 0) {
+        return emptyResult(filePath, 'UNTRUSTED', ['a non-empty session root is required']);
+    }
+    const maxFileBytes = resolveLimit(options.maxFileBytes, DEFAULT_MAX_FILE_BYTES);
+    const maxRecordBytes = resolveLimit(options.maxRecordBytes, DEFAULT_MAX_RECORD_BYTES);
+    const maxRecords = resolveLimit(options.maxRecords, DEFAULT_MAX_RECORDS);
+    if (maxFileBytes === undefined || maxRecordBytes === undefined || maxRecords === undefined) {
+        return emptyResult(filePath, 'RESOURCE_LIMIT', ['recovery limits must be finite positive integers within hard ceilings']);
+    }
+    const candidate = path.resolve(filePath);
+    let root;
+    let parent;
     try {
-        const buffer = Buffer.alloc(bytesToRead);
-        fs.readSync(fd, buffer, 0, bytesToRead, offset);
-        const text = buffer.toString('utf-8');
-        // When offset is 0, we read from the start of the file so
-        // the first line is complete -- don't skip it.
-        const isMidFileRead = offset > 0;
-        return parseJsonlLines(text, /* isHead */ false, isMidFileRead);
+        root = fs.realpathSync(options.sessionRoot);
+        parent = fs.realpathSync(path.dirname(candidate));
+        if (!fs.statSync(root).isDirectory())
+            throw new Error('session root is not a directory');
     }
-    finally {
-        fs.closeSync(fd);
+    catch {
+        return emptyResult(filePath, 'UNTRUSTED', ['session root or parent cannot be resolved']);
     }
-}
-/**
- * Parse JSONL text into SessionEntry[], skipping corrupt/incomplete lines.
- * When reading from a mid-file offset (tail), the first partial line is skipped.
- * When reading head, the last partial line is skipped if the chunk doesn't
- * end with a newline.
- *
- * @param text - Raw text from the file chunk
- * @param isHead - Whether this is a head read (skip trailing partial line)
- * @param skipFirstLine - Whether to skip the first line (true for mid-file
- *   tail reads where the first line is likely a partial). Defaults to !isHead.
- */
-function parseJsonlLines(text, isHead, skipFirstLine) {
-    const lines = text.split('\n');
-    const entries = [];
-    // Default: skip first line for non-head reads (standard tail behavior)
-    const shouldSkipFirst = skipFirstLine ?? !isHead;
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i].trim();
-        if (!line)
-            continue;
-        // Skip first line of mid-file tail read (may be partial)
-        if (shouldSkipFirst && i === 0 && lines.length > 1)
-            continue;
-        // Skip last line of head read if it may be truncated
-        if (isHead && i === lines.length - 1 && lines.length > 1 && !text.endsWith('\n'))
-            continue;
-        try {
-            const entry = JSON.parse(line);
-            if (isValidEntry(entry)) {
-                entries.push(entry);
+    if (!isWithin(root, parent)) {
+        return emptyResult(filePath, 'UNTRUSTED', ['session path escapes the configured root']);
+    }
+    let linkStat;
+    try {
+        linkStat = fs.lstatSync(candidate);
+    }
+    catch (error) {
+        const code = error.code;
+        return emptyResult(filePath, code === 'ENOENT' ? 'MISSING' : 'UNTRUSTED', [`lstat failed: ${code ?? 'UNKNOWN'}`]);
+    }
+    if (linkStat.isSymbolicLink() || !linkStat.isFile()) {
+        return emptyResult(filePath, 'UNTRUSTED', ['session path is not a regular, non-symlink file']);
+    }
+    let fd;
+    try {
+        fd = fs.openSync(candidate, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+        const stat = fs.fstatSync(fd);
+        if (!sameFile(linkStat, stat)) {
+            return emptyResult(filePath, 'UNTRUSTED', ['session path changed before secure open']);
+        }
+        if (!stat.isFile() || stat.nlink !== 1) {
+            return emptyResult(filePath, 'UNTRUSTED', ['opened session is not an exclusive regular file']);
+        }
+        if (stat.size === 0)
+            return emptyResult(filePath, 'EMPTY');
+        if (stat.size > maxFileBytes) {
+            return emptyResult(filePath, 'RESOURCE_LIMIT', [`file exceeds ${maxFileBytes} bytes`]);
+        }
+        const pathError = validateOpenedPath(fd, candidate, root, stat);
+        if (pathError)
+            return emptyResult(filePath, 'UNTRUSTED', [pathError]);
+        const bytes = readExactly(fd, stat.size);
+        const finalStat = fs.fstatSync(fd);
+        const finalPathError = validateOpenedPath(fd, candidate, root, finalStat);
+        if (finalPathError || !sameFile(stat, finalStat) || stat.size !== finalStat.size
+            || stat.mtimeMs !== finalStat.mtimeMs || stat.ctimeMs !== finalStat.ctimeMs) {
+            return emptyResult(filePath, 'UNTRUSTED', [finalPathError ?? 'session changed while it was being inspected']);
+        }
+        const hasTornTail = bytes[bytes.length - 1] !== 0x0a;
+        let committedBytes = bytes;
+        if (hasTornTail) {
+            const finalLineBreak = bytes.lastIndexOf(0x0a);
+            const tornTailStart = finalLineBreak + 1;
+            const tornTailBytes = bytes.length - tornTailStart;
+            if (tornTailBytes > maxRecordBytes) {
+                return emptyResult(filePath, 'RESOURCE_LIMIT', [`record exceeds ${maxRecordBytes} bytes`]);
             }
+            committedBytes = bytes.subarray(0, tornTailStart);
+        }
+        let text;
+        try {
+            text = new TextDecoder('utf-8', { fatal: true }).decode(committedBytes);
         }
         catch {
-            // Skip corrupt lines
-            continue;
+            return emptyResult(filePath, 'INVALID', ['transcript is not valid UTF-8']);
         }
-    }
-    return entries;
-}
-/**
- * Minimal validation that a parsed object looks like a SessionEntry.
- */
-function isValidEntry(obj) {
-    if (typeof obj !== 'object' || obj === null)
-        return false;
-    const entry = obj;
-    return (typeof entry.uuid === 'string' &&
-        typeof entry.timestamp === 'number' &&
-        typeof entry.type === 'string' &&
-        typeof entry.state === 'string');
-}
-/**
- * Count total lines in a file (for large files where head+tail don't overlap).
- * Only counts non-empty lines that parse as valid JSON.
- */
-function countLines(filePath) {
-    const content = fs.readFileSync(filePath, 'utf-8');
-    let count = 0;
-    for (const line of content.split('\n')) {
-        const trimmed = line.trim();
-        if (trimmed) {
+        const lines = text.split('\n');
+        const entries = [];
+        const seen = new Set();
+        let previous;
+        for (const rawLine of lines) {
+            if (!rawLine.trim())
+                continue;
+            if (Buffer.byteLength(rawLine, 'utf8') > maxRecordBytes) {
+                return emptyResult(filePath, 'RESOURCE_LIMIT', [`record exceeds ${maxRecordBytes} bytes`]);
+            }
+            if (entries.length >= maxRecords) {
+                return emptyResult(filePath, 'RESOURCE_LIMIT', [`record count exceeds ${maxRecords}`]);
+            }
+            let parsed;
             try {
-                JSON.parse(trimmed);
-                count++;
+                parsed = JSON.parse(rawLine);
             }
             catch {
-                // Skip corrupt lines in count
+                return emptyResult(filePath, 'INVALID', ['corrupt JSON occurs before the final torn record']);
+            }
+            if (!isValidEntry(parsed))
+                return emptyResult(filePath, 'INVALID', ['entry fails the session schema']);
+            if (seen.has(parsed.uuid))
+                return emptyResult(filePath, 'INVALID', ['duplicate entry UUID']);
+            if (previous) {
+                if (parsed.parentUuid !== previous.uuid)
+                    return emptyResult(filePath, 'INVALID', ['broken parentUuid lineage']);
+                if (parsed.timestamp < previous.timestamp)
+                    return emptyResult(filePath, 'INVALID', ['timestamps are not monotonic']);
             }
+            else if (parsed.parentUuid !== null) {
+                return emptyResult(filePath, 'INVALID', ['first entry has a forged parentUuid']);
+            }
+            seen.add(parsed.uuid);
+            entries.push(parsed);
+            previous = parsed;
+        }
+        if (entries.length === 0) {
+            return emptyResult(filePath, hasTornTail ? 'INVALID' : 'EMPTY', hasTornTail ? ['only record is torn'] : []);
         }
+        const lastEntry = entries[entries.length - 1];
+        const diagnostics = [
+            'legacy JSONL has no durable commit marker',
+            ...(hasTornTail ? ['discarded an incomplete final record'] : []),
+        ];
+        return {
+            metadata: {
+                sessionId: path.basename(filePath, '.jsonl'), createdAt: entries[0].timestamp,
+                lastActivityAt: lastEntry.timestamp, entryCount: entries.length, state: lastEntry.state,
+            },
+            recentEntries: entries.slice(-RECENT_ENTRY_LIMIT), lastState: lastEntry.state,
+            canResume: options.allowLegacyUnverified === true,
+            disposition: 'LEGACY_UNVERIFIED', diagnostics,
+        };
+    }
+    catch (error) {
+        const code = error.code;
+        return emptyResult(filePath, 'UNTRUSTED', [`secure open/read failed: ${code ?? 'UNKNOWN'}`]);
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
     }
-    return count;
 }
 //# sourceMappingURL=session-resume.js.map

package/dist/mcp/tool-annotations.d.ts

@@ -0,0 +1,25 @@
+/**
+ * MCP tool safety annotations and the built-in safety inventory.
+ *
+ * The inventory is deliberately conservative. A tool is marked read-only
+ * only when its registered operation is an observation/query with no write or
+ * execution path. Every other built-in receives the MCP-safe fallback: it may
+ * be destructive, is not assumed idempotent, and may interact with the world.
+ * These values guide clients but never replace authorization, sandbox, or
+ * policy enforcement.
+ */
+import type { ToolAnnotations } from './types';
+export type ResolvedToolAnnotations = Required<Pick<ToolAnnotations, 'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>> & Pick<ToolAnnotations, 'title'>;
+export interface BuiltInToolSafetyDisposition {
+    annotations: ResolvedToolAnnotations;
+    reason: string;
+}
+export declare const CONSERVATIVE_TOOL_ANNOTATIONS: ResolvedToolAnnotations;
+/** Complete deterministic inventory of names advertised by both MCP paths. */
+export declare const BUILT_IN_TOOL_NAMES: readonly string[];
+export declare const BUILT_IN_TOOL_SAFETY_INVENTORY: Readonly<Record<string, BuiltInToolSafetyDisposition>>;
+/** Resolve explicit metadata over inventory metadata over conservative defaults. */
+export declare function resolveToolAnnotations(name: string, annotations?: ToolAnnotations): ResolvedToolAnnotations;
+export declare function getBuiltInToolAnnotations(): Readonly<Record<string, ToolAnnotations>>;
+export declare function getBuiltInToolSafetyInventory(): Readonly<Record<string, BuiltInToolSafetyDisposition>>;
+//# sourceMappingURL=tool-annotations.d.ts.map

package/dist/mcp/tool-annotations.js

@@ -0,0 +1,75 @@
+/**
+ * MCP tool safety annotations and the built-in safety inventory.
+ *
+ * The inventory is deliberately conservative. A tool is marked read-only
+ * only when its registered operation is an observation/query with no write or
+ * execution path. Every other built-in receives the MCP-safe fallback: it may
+ * be destructive, is not assumed idempotent, and may interact with the world.
+ * These values guide clients but never replace authorization, sandbox, or
+ * policy enforcement.
+ */
+export const CONSERVATIVE_TOOL_ANNOTATIONS = Object.freeze({
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true,
+});
+const HARD_CODED_TOOL_NAMES = [
+    'accessibility_test', 'advisor_consult', 'agent_complete', 'agent_list',
+    'agent_metrics', 'agent_spawn', 'agent_status', 'aqe_health', 'chaos_test',
+    'code_index', 'contract_validate', 'coverage_analyze_sublinear',
+    'cross_phase_cleanup', 'cross_phase_query', 'cross_phase_stats',
+    'cross_phase_store', 'defect_predict', 'fleet_health', 'fleet_init',
+    'fleet_status', 'format_signals', 'infra_healing_feed_output',
+    'infra_healing_recover', 'infra_healing_status', 'memory_delete',
+    'memory_query', 'memory_retrieve', 'memory_share', 'memory_store',
+    'memory_usage', 'migration_check', 'migration_promote', 'migration_status',
+    'model_route', 'phase_end', 'phase_start', 'pipeline_list', 'pipeline_load',
+    'pipeline_run', 'pipeline_validate', 'quality_assess',
+    'requirements_validate', 'routing_economics', 'routing_metrics',
+    'security_scan_comprehensive', 'session_cache_stats', 'task_cancel',
+    'task_list', 'task_orchestrate', 'task_status', 'task_submit',
+    'team_broadcast', 'team_health', 'team_list', 'team_message', 'team_rebalance',
+    'team_scale', 'test_execute_parallel', 'test_generate_enhanced',
+    'validation_pipeline',
+];
+// QE tools not duplicated by the hard-coded protocol registrations.
+const BRIDGED_TOOL_NAMES = [
+    'qe/analysis/token_usage', 'qe/code/c4',
+    'qe/coherence/audit', 'qe/coherence/check', 'qe/coherence/collapse',
+    'qe/coherence/consensus', 'qe/coverage/gaps',
+    'qe/embeddings/compare', 'qe/embeddings/generate', 'qe/embeddings/search',
+    'qe/embeddings/stats', 'qe/embeddings/store',
+    'qe/learning/dream', 'qe/learning/optimize',
+    'qe/mincut/health', 'qe/mincut/analyze', 'qe/mincut/strengthen',
+    'qe/planning/goap_execute', 'qe/planning/goap_plan', 'qe/planning/goap_status',
+    'qe/quality/gate', 'qe/qx/analyze', 'qe/requirements/quality-criteria',
+    'qe/security/url-validate', 'qe/tests/load', 'qe/tests/schedule',
+    'qe/visual/compare', 'qe/workflows/browser-load',
+];
+/** Complete deterministic inventory of names advertised by both MCP paths. */
+export const BUILT_IN_TOOL_NAMES = Object.freeze([...HARD_CODED_TOOL_NAMES, ...BRIDGED_TOOL_NAMES].sort());
+function conservativeDisposition() {
+    return {
+        annotations: CONSERVATIVE_TOOL_ANNOTATIONS,
+        reason: 'No narrow side-effect-free guarantee is recorded for this built-in; retain conservative policy defaults.',
+    };
+}
+export const BUILT_IN_TOOL_SAFETY_INVENTORY = Object.freeze(Object.fromEntries(BUILT_IN_TOOL_NAMES.map((name) => [name, conservativeDisposition()])));
+/** Resolve explicit metadata over inventory metadata over conservative defaults. */
+export function resolveToolAnnotations(name, annotations) {
+    const reviewedDisposition = BUILT_IN_TOOL_SAFETY_INVENTORY[name];
+    return Object.freeze({
+        ...(reviewedDisposition?.annotations ?? CONSERVATIVE_TOOL_ANNOTATIONS),
+        // Dynamic and plugin-supplied names cannot self-assert optimistic hints.
+        // Add the name to the reviewed inventory before accepting overrides.
+        ...(reviewedDisposition ? annotations : undefined),
+    });
+}
+export function getBuiltInToolAnnotations() {
+    return Object.fromEntries(Object.entries(BUILT_IN_TOOL_SAFETY_INVENTORY).map(([name, disposition]) => [name, disposition.annotations]));
+}
+export function getBuiltInToolSafetyInventory() {
+    return BUILT_IN_TOOL_SAFETY_INVENTORY;
+}
+//# sourceMappingURL=tool-annotations.js.map