@phuetz/code-buddy 1.0.0 → 1.2.0

package/dist/tools/computer-control-tool.js

@@ -18,6 +18,7 @@ import { listApplicationProfiles, resolveApplicationProfile, } from './applicati
 import { getActiveRunStore } from '../observability/run-store.js';
 import { logger } from '../utils/logger.js';
 import { getDesktopAutomation, getPermissionManager, getSystemControl, getSmartSnapshotManager, getScreenRecorder, } from '../desktop-automation/index.js';
+import { OmniParserRunner } from "../desktop-automation/omniparser-runner.js";
 const execFileAsync = promisify(execFile);
 let visionGroundingProvider = null;
 export function setVisionGroundingProvider(p) {
@@ -55,6 +56,7 @@ export class ComputerControlTool {
     systemControl = getSystemControl();
     snapshotManager = getSmartSnapshotManager();
     screenRecorder = getScreenRecorder();
+    omniParser = new OmniParserRunner();
     lastTargetFocusProof = null;
     lastVisualContextProof = null;
     /**
@@ -161,6 +163,20 @@ export class ComputerControlTool {
                     return run(() => this.excelGetCell(enrichedInput));
                 case 'excel_save_workbook':
                     return run(() => this.excelSaveWorkbook(enrichedInput));
+                case 'powerpoint_open_presentation':
+                    return run(() => this.powerpointOpenPresentation(enrichedInput));
+                case 'powerpoint_add_slide':
+                    return run(() => this.powerpointAddSlide(enrichedInput));
+                case 'powerpoint_set_text':
+                    return run(() => this.powerpointSetText(enrichedInput));
+                case 'powerpoint_save_presentation':
+                    return run(() => this.powerpointSavePresentation(enrichedInput));
+                case 'word_open_document':
+                    return run(() => this.wordOpenDocument(enrichedInput));
+                case 'word_type_text':
+                    return run(() => this.wordTypeText(enrichedInput));
+                case 'word_save_document':
+                    return run(() => this.wordSaveDocument(enrichedInput));
                 case 'use_app_workflow':
                 case 'macro':
                     return run(() => this.executeMacro(enrichedInput));
@@ -417,7 +433,7 @@ export class ComputerControlTool {
         const snapshot = await this.snapshotManager.takeSnapshot({
             interactiveOnly: input.interactiveOnly ?? true,
         });
-        const textRepresentation = this.snapshotManager.toTextRepresentation(snapshot);
+        let textRepresentation = this.snapshotManager.toTextRepresentation(snapshot);
         // Capture and normalize screenshot for LLM
         let screenshotData = {};
         try {
@@ -447,6 +463,26 @@ export class ComputerControlTool {
         catch (err) {
             logger.debug('Screenshot capture failed in snapshot_with_screenshot', { error: err });
         }
+        // Apply OmniParser if requested and screenshot was successful
+        if (input.useOmniParser && screenshotData.base64) {
+            const omniResult = await this.omniParser.parseScreen(screenshotData.base64, {
+                width: screenshotData.width,
+                height: screenshotData.height,
+            });
+            if (omniResult.elements.length > 0) {
+                // Override screenshot with the annotated (Set-of-Marks) image whose numbers match the ids below.
+                screenshotData.base64 = omniResult.annotatedImageBase64;
+                const unit = omniResult.elements[0]?.normalized ? 'ratio 0-1' : 'px';
+                const parsedText = omniResult.elements
+                    .map((e) => `[${e.id}] ${e.type}${e.interactable ? ' (interactive)' : ''} "${e.content}" center=(${e.center[0]},${e.center[1]})`)
+                    .join('\n');
+                textRepresentation += `\n\n[OmniParser Elements] (coords in ${unit}; use 'click' at an element center to act):\n${parsedText}`;
+            }
+            else {
+                // No elements => server down/misconfigured or empty parse. Keep the original snapshot, don't add noise.
+                logger.debug('OmniParser returned no elements; keeping original screenshot and snapshot text');
+            }
+        }
         return {
             success: true,
             output: textRepresentation,
@@ -1512,7 +1548,7 @@ if ($clickButtonName) {
     withDerivedAppWindowTarget(input, profile) {
         const next = { ...input };
         if (profile.id === 'notepad' && input.filePath && !next.windowTitle && !next.windowTitleRegex) {
-            next.windowTitle = path.basename(input.filePath);
+            next.windowTitle = this.basenameForWindowTitle(input.filePath);
             next.windowTitleMatch = 'contains';
         }
         return next;
@@ -1603,11 +1639,14 @@ if ($clickButtonName) {
             }
         }
         if (profile?.id === 'notepad' && input.filePath && !next.windowTitle && !next.windowTitleRegex) {
-            next.windowTitle = path.basename(input.filePath);
+            next.windowTitle = this.basenameForWindowTitle(input.filePath);
             next.windowTitleMatch = 'contains';
         }
         return next;
     }
+    basenameForWindowTitle(filePath) {
+        return filePath.includes('\\') ? path.win32.basename(filePath) : path.basename(filePath);
+    }
     async excelOpenWorkbook(input) {
         const result = await this.runExcelAutomation({
             operation: 'open',
@@ -1666,6 +1705,97 @@ if ($clickButtonName) {
             data: result,
         };
     }
+    async powerpointOpenPresentation(input) {
+        const result = await this.runPowerpointAutomation({
+            operation: 'open',
+            filePath: input.filePath,
+        });
+        return {
+            success: true,
+            output: `PowerPoint presentation ready: ${result.presentationName ?? result.filePath ?? 'new presentation'}`,
+            data: result,
+        };
+    }
+    async powerpointAddSlide(input) {
+        const result = await this.runPowerpointAutomation({
+            operation: 'addSlide',
+            filePath: input.filePath,
+            layoutIndex: input.layoutIndex,
+        });
+        return {
+            success: true,
+            output: `PowerPoint slide added (index ${result.slideIndex})`,
+            data: result,
+        };
+    }
+    async powerpointSetText(input) {
+        if (input.slideIndex === undefined || input.shapeIndex === undefined) {
+            return { success: false, error: 'slideIndex and shapeIndex are required' };
+        }
+        const result = await this.runPowerpointAutomation({
+            operation: 'setText',
+            filePath: input.filePath,
+            slideIndex: input.slideIndex,
+            shapeIndex: input.shapeIndex,
+            value: input.value ?? input.text ?? '',
+        });
+        return {
+            success: true,
+            output: `PowerPoint slide ${input.slideIndex} shape ${input.shapeIndex} text set.`,
+            data: result,
+        };
+    }
+    async powerpointSavePresentation(input) {
+        const result = await this.runPowerpointAutomation({
+            operation: 'save',
+            filePath: input.filePath,
+            saveAsPath: input.saveAsPath,
+        });
+        return {
+            success: true,
+            output: `PowerPoint presentation saved${result.filePath ? `: ${result.filePath}` : ''}`,
+            data: result,
+        };
+    }
+    async wordOpenDocument(input) {
+        const result = await this.runWordAutomation({
+            operation: 'open',
+            filePath: input.filePath,
+        });
+        return {
+            success: true,
+            output: `Word document ready: ${result.documentName ?? result.filePath ?? 'new document'}`,
+            data: result,
+        };
+    }
+    async wordTypeText(input) {
+        const value = input.value ?? input.text;
+        if (value === undefined || value === null) {
+            return { success: false, error: 'value (or text) is required for word_type_text' };
+        }
+        const result = await this.runWordAutomation({
+            operation: 'typeText',
+            filePath: input.filePath,
+            value,
+        });
+        return {
+            success: true,
+            output: `Word document text appended.`,
+            data: result,
+        };
+    }
+    async wordSaveDocument(input) {
+        const result = await this.runWordAutomation({
+            operation: 'save',
+            filePath: input.filePath,
+            saveAsPath: input.saveAsPath,
+        });
+        return {
+            success: true,
+            output: `Word document saved${result.filePath ? `: ${result.filePath}` : ''}`,
+            data: result,
+        };
+    }
     // ============================================================================
     // Mouse Actions
     // ============================================================================
@@ -2697,6 +2827,186 @@ switch ($operation) {
   value = $value
   visible = $excel.Visible
 } | ConvertTo-Json -Compress
+`;
+        const stdout = await this.runPowerShellEncoded(script, 30000);
+        return JSON.parse(stdout || '{}');
+    }
+    async runPowerpointAutomation(payload) {
+        if (process.platform !== 'win32') {
+            throw new Error('PowerPoint application profile currently requires Windows COM automation.');
+        }
+        const encodedPayload = Buffer.from(JSON.stringify(payload), 'utf8').toString('base64');
+        const script = `
+$ErrorActionPreference = 'Stop'
+$payload = [System.Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encodedPayload}')) | ConvertFrom-Json
+
+function Get-PowerPointApplication {
+  try {
+    return [Runtime.InteropServices.Marshal]::GetActiveObject('PowerPoint.Application')
+  } catch {
+    return New-Object -ComObject PowerPoint.Application
+  }
+}
+
+function Resolve-Presentation($ppt, $filePath) {
+  if ($filePath) {
+    $fullPath = [System.IO.Path]::GetFullPath([string]$filePath)
+    foreach ($pres in @($ppt.Presentations)) {
+      try {
+        if ($pres.FullName -eq $fullPath) { return $pres }
+      } catch {}
+    }
+    if (Test-Path -LiteralPath $fullPath) {
+      return $ppt.Presentations.Open($fullPath)
+    }
+    $pres = $ppt.Presentations.Add()
+    $pres.SaveAs($fullPath)
+    return $pres
+  }
+
+  if ($ppt.Presentations.Count -gt 0) {
+    return $ppt.ActivePresentation
+  }
+  return $ppt.Presentations.Add()
+}
+
+$ppt = Get-PowerPointApplication
+$ppt.Visible = 1
+$presentation = Resolve-Presentation $ppt $payload.filePath
+$operation = [string]$payload.operation
+$slideIndex = $payload.slideIndex
+$shapeIndex = $payload.shapeIndex
+$value = $null
+
+switch ($operation) {
+  'open' {
+    $value = $null
+  }
+  'addSlide' {
+    $layoutIndex = 1
+    if ($null -ne $payload.layoutIndex) { $layoutIndex = $payload.layoutIndex }
+    # ppLayoutText = 2, ppLayoutTitle = 1
+    $slideCount = $presentation.Slides.Count
+    $slide = $presentation.Slides.Add($slideCount + 1, $layoutIndex)
+    $slideIndex = $slide.SlideIndex
+  }
+  'setText' {
+    if ($null -eq $slideIndex -or $null -eq $shapeIndex) { throw 'slideIndex and shapeIndex are required' }
+    $slide = $presentation.Slides.Item([int]$slideIndex)
+    $shape = $slide.Shapes.Item([int]$shapeIndex)
+    if ($shape.HasTextFrame) {
+      $shape.TextFrame.TextRange.Text = $payload.value
+    } else {
+      throw 'Shape does not have a text frame'
+    }
+    $value = $payload.value
+  }
+  'save' {
+    if ($payload.saveAsPath) {
+      $savePath = [System.IO.Path]::GetFullPath([string]$payload.saveAsPath)
+      $presentation.SaveAs($savePath)
+    } elseif ($payload.filePath) {
+      $presentation.Save()
+    } elseif ($presentation.Path) {
+      $presentation.Save()
+    } else {
+      throw 'saveAsPath is required for an unsaved presentation.'
+    }
+    $value = $null
+  }
+  default {
+    throw "Unknown PowerPoint operation '$operation'"
+  }
+}
+
+[pscustomobject]@{
+  operation = $operation
+  filePath = $presentation.FullName
+  presentationName = $presentation.Name
+  slideIndex = $slideIndex
+  value = $value
+} | ConvertTo-Json -Compress
+`;
+        const stdout = await this.runPowerShellEncoded(script, 30000);
+        return JSON.parse(stdout || '{}');
+    }
+    async runWordAutomation(payload) {
+        if (process.platform !== 'win32') {
+            throw new Error('Word application profile currently requires Windows COM automation.');
+        }
+        const encodedPayload = Buffer.from(JSON.stringify(payload), 'utf8').toString('base64');
+        const script = `
+$ErrorActionPreference = 'Stop'
+$payload = [System.Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encodedPayload}')) | ConvertFrom-Json
+
+function Get-WordApplication {
+  try {
+    return [Runtime.InteropServices.Marshal]::GetActiveObject('Word.Application')
+  } catch {
+    return New-Object -ComObject Word.Application
+  }
+}
+
+function Resolve-Document($word, $filePath) {
+  if ($filePath) {
+    $fullPath = [System.IO.Path]::GetFullPath([string]$filePath)
+    foreach ($doc in @($word.Documents)) {
+      try {
+        if ($doc.FullName -eq $fullPath) { return $doc }
+      } catch {}
+    }
+    if (Test-Path -LiteralPath $fullPath) {
+      return $word.Documents.Open($fullPath)
+    }
+    $doc = $word.Documents.Add()
+    $doc.SaveAs([string]$fullPath)
+    return $doc
+  }
+
+  if ($word.Documents.Count -gt 0) {
+    return $word.ActiveDocument
+  }
+  return $word.Documents.Add()
+}
+
+$word = Get-WordApplication
+$word.Visible = 1
+$document = Resolve-Document $word $payload.filePath
+$operation = [string]$payload.operation
+$value = $null
+
+switch ($operation) {
+  'open' {
+    $value = $null
+  }
+  'typeText' {
+    $document.Content.InsertAfter([string]$payload.value)
+    $value = $payload.value
+  }
+  'save' {
+    if ($payload.saveAsPath) {
+      $savePath = [System.IO.Path]::GetFullPath([string]$payload.saveAsPath)
+      $document.SaveAs([string]$savePath)
+    } elseif ($payload.filePath) {
+      $document.Save()
+    } elseif ($document.Path) {
+      $document.Save()
+    } else {
+      throw 'saveAsPath is required for an unsaved document.'
+    }
+    $value = $null
+  }
+  default {
+    throw "Unknown Word operation '$operation'"
+  }
+}
+
+[pscustomobject]@{
+  operation = $operation
+  filePath = $document.FullName
+  documentName = $document.Name
+  value = $value
+} | ConvertTo-Json -Compress
 `;
         const stdout = await this.runPowerShellEncoded(script, 30000);
         return JSON.parse(stdout || '{}');
@@ -5202,8 +5512,8 @@ $proc = Get-Process -Id $pid -ErrorAction SilentlyContinue
     requiresApplicationConfirmation(input) {
         if (input.simulateOnly)
             return false;
-        if (input.action.startsWith('excel_')) {
-            return ['excel_open_workbook', 'excel_set_cell', 'excel_save_workbook'].includes(input.action);
+        if (input.action.startsWith('excel_') || input.action.startsWith('powerpoint_') || input.action.startsWith('word_')) {
+            return ['excel_open_workbook', 'excel_set_cell', 'excel_save_workbook', 'powerpoint_open_presentation', 'powerpoint_add_slide', 'powerpoint_set_text', 'powerpoint_save_presentation', 'word_open_document', 'word_type_text', 'word_save_document'].includes(input.action);
         }
         if (input.action === 'save_app_document') {
             return true;
@@ -5240,6 +5550,8 @@ $proc = Get-Process -Id $pid -ErrorAction SilentlyContinue
             'set_slider_value', 'select_tree_item', 'expand_tree_item', 'collapse_tree_item',
             'click_dialog_button', 'handle_dialog',
             'open_app', 'focus_app', 'save_app_document', 'excel_open_workbook', 'excel_set_cell', 'excel_save_workbook',
+            'powerpoint_open_presentation', 'powerpoint_add_slide', 'powerpoint_set_text', 'powerpoint_save_presentation',
+            'word_open_document', 'word_type_text', 'word_save_document',
             'click', 'left_click', 'middle_click', 'double_click', 'right_click', 'move_mouse', 'drag', 'scroll',
             'type', 'key', 'key_down', 'key_up', 'hotkey',
             'focus_window', 'close_window', 'minimize_window', 'maximize_window', 'restore_window',

package/dist/tools/document-generator.d.ts

@@ -52,3 +52,17 @@ export declare function executeGenerateDocument(args: {
     outputPath: string;
     theme?: string;
 }): Promise<ToolResult>;
+/**
+ * Streaming variant of {@link executeGenerateDocument}: identical output, but
+ * yields the build phases (prepare → parse → build → write → verify → done) as
+ * they happen so a host UI (e.g. the Cowork trace panel) can show the steps
+ * unfold one by one instead of a single opaque "Created X" at the end. Used by
+ * the tool-handler streaming path (`STREAMING_TOOLS`).
+ */
+export declare function executeGenerateDocumentStreaming(args: {
+    type: string;
+    title: string;
+    content: string;
+    outputPath: string;
+    theme?: string;
+}): AsyncGenerator<string, ToolResult, undefined>;

package/dist/tools/document-generator.js

@@ -649,4 +649,83 @@ export async function executeGenerateDocument(args) {
         },
     };
 }
+/**
+ * Streaming variant of {@link executeGenerateDocument}: identical output, but
+ * yields the build phases (prepare → parse → build → write → verify → done) as
+ * they happen so a host UI (e.g. the Cowork trace panel) can show the steps
+ * unfold one by one instead of a single opaque "Created X" at the end. Used by
+ * the tool-handler streaming path (`STREAMING_TOOLS`).
+ */
+export async function* executeGenerateDocumentStreaming(args) {
+    const type = args.type;
+    const { title, content, outputPath, theme } = args;
+    const file = path.basename(outputPath);
+    const label = type.toUpperCase();
+    try {
+        const expectedExt = expectedExtensionForType(type);
+        if (path.extname(outputPath).toLowerCase() !== expectedExt) {
+            return { success: false, error: `outputPath must end with ${expectedExt} for ${label} documents` };
+        }
+        yield `📄 Preparing ${label} "${title}"…\n`;
+        const outDir = path.dirname(path.resolve(outputPath));
+        if (!fs.existsSync(outDir))
+            fs.mkdirSync(outDir, { recursive: true });
+        yield `📑 Parsing content…\n`;
+        const sections = parseMarkdownSections(content);
+        yield `   parsed ${sections.length} section(s)\n`;
+        const buildLabel = type === 'pptx' ? `Building ${sections.length + 1} slide(s)`
+            : type === 'xlsx' ? 'Building spreadsheet'
+                : type === 'docx' ? 'Building document'
+                    : 'Rendering pages';
+        yield `🧩 ${buildLabel}…\n`;
+        let embeddedImages;
+        let rowCount = 0;
+        switch (type) {
+            case 'pptx':
+                await generatePptx(title, sections, outputPath, theme);
+                break;
+            case 'docx':
+                embeddedImages = await generateDocx(title, sections, outputPath);
+                break;
+            case 'xlsx':
+                rowCount = await generateXlsx(title, content, outputPath);
+                break;
+            case 'pdf':
+                await generatePdf(title, sections, outputPath);
+                break;
+            default: return { success: false, error: `Unknown document type: ${type}` };
+        }
+        yield `💾 Wrote ${file}\n`;
+        yield `✅ Verifying…\n`;
+        const docxValidation = type === 'docx' ? await validateDocxPackage(outputPath) : undefined;
+        const sizeKb = fs.existsSync(outputPath)
+            ? Math.max(1, Math.round(fs.statSync(outputPath).size / 1024))
+            : 0;
+        logger.info(`Document generated (streaming): ${outputPath} (${type})`);
+        yield `✓ Created ${file} (${sizeKb} KB)\n`;
+        const embImgs = embeddedImages ?? [];
+        const embeddedImageLines = embImgs.length > 0
+            ? ['Embedded images:', ...embImgs.map((i) => `- ${i.path}${i.caption ? ` (${i.caption})` : ''} [${i.width}x${i.height}]`)]
+            : [];
+        const validationLines = docxValidation
+            ? [
+                'DOCX validation:',
+                `- relationships: ${docxValidation.relationshipCount}`,
+                `- embedded image relationships: ${docxValidation.embeddedRelationshipCount}`,
+                `- media files: ${docxValidation.mediaFileCount}`,
+            ]
+            : [];
+        const xlsxLine = type === 'xlsx' ? [`Rows: ${rowCount}`] : [];
+        return {
+            success: true,
+            output: [`Created ${label}: ${outputPath}`, ...xlsxLine, ...embeddedImageLines, ...validationLines].join('\n'),
+            data: { outputPath, embeddedImages: embImgs, ...(docxValidation ? { docxValidation } : {}) },
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.error('Document generation (streaming) failed', { error: msg });
+        return { success: false, error: `Document generation failed: ${msg}` };
+    }
+}
 //# sourceMappingURL=document-generator.js.map

package/dist/tools/execute-code-rpc-invoker.d.ts

@@ -17,9 +17,17 @@
  *      override via env `CODEBUDDY_EXECUTE_CODE_TOOL_RPC_ALLOWLIST` (csv).
  *   3. **fleetSafe** — the tool's registry metadata must declare
  *      `fleetSafe: true` (read-only by definition).
+ *   4. **Per-tool opt-in** — `CODEBUDDY_EXECUTE_CODE_RPC_TOOLS` (csv)
+ *      adds specific executor-backed tools to the allowlist. These tools
+ *      bypass the `fleetSafe` gate since they are explicitly opted in by the
+ *      operator. Each tool name is validated against both the registry and
+ *      this module's executor table; unknown or unsupported names are logged
+ *      and skipped.
  *
- * No write/exec tool is reachable; the executors below physically only
- * read. This mirrors the audited `peer-tool-bridge.ts` pattern.
+ * No write/exec tool is reachable by default; the default executors
+ * below physically only read. Tools added via RPC_TOOLS opt-in are the
+ * operator's responsibility. This mirrors the audited
+ * `peer-tool-bridge.ts` pattern.
  */
 export interface ExecuteCodeRpcInvokeRequest {
     tool: string;
@@ -35,11 +43,27 @@ export type ExecuteCodeRpcInvoker = (request: ExecuteCodeRpcInvokeRequest) => Pr
 /** Truthy-flag parse — the single master gate. Read once, in the parent. */
 export declare function isExecuteCodeToolRpcEnabled(raw?: string | undefined): boolean;
 export declare function getExecuteCodeToolRpcAllowlist(raw?: string | undefined): Set<string>;
+/**
+ * Parse `CODEBUDDY_EXECUTE_CODE_RPC_TOOLS` — a csv of additional tool names
+ * to add to the RPC allowlist. Each name is validated against the registry
+ * and this module's executor table; unknown or unsupported names are logged
+ * as warnings and silently skipped so a typo never opens an unintended tool.
+ *
+ * Tools listed here bypass the `fleetSafe` gate because the operator
+ * explicitly opted them in — requiring `fleetSafe: true` would defeat
+ * the purpose of this escape hatch.
+ */
+export declare function getExecuteCodeRpcExtraTools(raw?: string | undefined, isRegistered?: (name: string) => boolean, hasExecutor?: (name: string) => boolean): Set<string>;
 interface InvokerOptions {
     /** Root the read-only executors are confined to. Defaults to cwd. */
     workspaceRoot: string;
     allowlist?: Set<string>;
     isFleetSafe?: (name: string) => boolean;
+    /**
+     * Additional tools to allow through RPC, bypassing the fleetSafe gate.
+     * Parsed from `CODEBUDDY_EXECUTE_CODE_RPC_TOOLS` by default.
+     */
+    extraTools?: Set<string>;
 }
 /**
  * Build the policy-gated invoker. The master flag is intentionally NOT

package/dist/tools/execute-code-rpc-invoker.js

@@ -17,9 +17,17 @@
  *      override via env `CODEBUDDY_EXECUTE_CODE_TOOL_RPC_ALLOWLIST` (csv).
  *   3. **fleetSafe** — the tool's registry metadata must declare
  *      `fleetSafe: true` (read-only by definition).
+ *   4. **Per-tool opt-in** — `CODEBUDDY_EXECUTE_CODE_RPC_TOOLS` (csv)
+ *      adds specific executor-backed tools to the allowlist. These tools
+ *      bypass the `fleetSafe` gate since they are explicitly opted in by the
+ *      operator. Each tool name is validated against both the registry and
+ *      this module's executor table; unknown or unsupported names are logged
+ *      and skipped.
  *
- * No write/exec tool is reachable; the executors below physically only
- * read. This mirrors the audited `peer-tool-bridge.ts` pattern.
+ * No write/exec tool is reachable by default; the default executors
+ * below physically only read. Tools added via RPC_TOOLS opt-in are the
+ * operator's responsibility. This mirrors the audited
+ * `peer-tool-bridge.ts` pattern.
  */
 import { spawn } from 'child_process';
 import { rgPath } from '@vscode/ripgrep';
@@ -28,6 +36,7 @@ import * as path from 'path';
 import { logger } from '../utils/logger.js';
 import { getToolRegistry } from './registry.js';
 const DEFAULT_ALLOWLIST = ['view_file', 'list_directory', 'search'];
+const EXECUTOR_TOOL_NAMES = new Set(DEFAULT_ALLOWLIST);
 const READ_TRUNCATE_BYTES = 256 * 1024;
 const LIST_DIRECTORY_MAX_ENTRIES = 256;
 const SEARCH_TIMEOUT_MS = 30_000;
@@ -45,25 +54,57 @@ export function getExecuteCodeToolRpcAllowlist(raw = process.env.CODEBUDDY_EXECU
     const items = raw.split(',').map((item) => item.trim()).filter(Boolean);
     return items.length > 0 ? new Set(items) : new Set(DEFAULT_ALLOWLIST);
 }
+/**
+ * Parse `CODEBUDDY_EXECUTE_CODE_RPC_TOOLS` — a csv of additional tool names
+ * to add to the RPC allowlist. Each name is validated against the registry
+ * and this module's executor table; unknown or unsupported names are logged
+ * as warnings and silently skipped so a typo never opens an unintended tool.
+ *
+ * Tools listed here bypass the `fleetSafe` gate because the operator
+ * explicitly opted them in — requiring `fleetSafe: true` would defeat
+ * the purpose of this escape hatch.
+ */
+export function getExecuteCodeRpcExtraTools(raw = process.env.CODEBUDDY_EXECUTE_CODE_RPC_TOOLS, isRegistered = (name) => !!getToolRegistry().getTool(name), hasExecutor = (name) => EXECUTOR_TOOL_NAMES.has(name)) {
+    if (!raw)
+        return new Set();
+    const items = raw.split(',').map((item) => item.trim()).filter(Boolean);
+    const validated = new Set();
+    for (const name of items) {
+        if (!isRegistered(name)) {
+            logger.warn('[execute-code-rpc] CODEBUDDY_EXECUTE_CODE_RPC_TOOLS: unknown tool, skipping', { tool: name });
+            continue;
+        }
+        if (!hasExecutor(name)) {
+            logger.warn('[execute-code-rpc] CODEBUDDY_EXECUTE_CODE_RPC_TOOLS: tool has no execute_code RPC executor, skipping', { tool: name });
+            continue;
+        }
+        validated.add(name);
+    }
+    return validated;
+}
 /**
  * Build the policy-gated invoker. The master flag is intentionally NOT
  * read here — the runner only constructs an invoker once it has already
  * decided RPC is enabled, keeping the flag boundary in the parent.
  */
 export function createExecuteCodeRpcInvoker(options) {
-    const allowlist = options.allowlist ?? getExecuteCodeToolRpcAllowlist();
+    const baseAllowlist = options.allowlist ?? getExecuteCodeToolRpcAllowlist();
+    const extraTools = options.extraTools ?? getExecuteCodeRpcExtraTools();
+    const combinedAllowlist = new Set([...baseAllowlist, ...extraTools]);
     const isFleetSafe = options.isFleetSafe ?? ((name) => getToolRegistry().isFleetSafe(name));
     const workspaceRoot = path.resolve(options.workspaceRoot);
     return async (request) => {
         const tool = request.tool;
         try {
-            if (!allowlist.has(tool)) {
+            if (!combinedAllowlist.has(tool)) {
                 return {
                     ok: false,
                     error: `TOOL_NOT_ALLOWED_FOR_EXECUTE_CODE_RPC: tool "${tool}" is not in the execute_code RPC allowlist`,
                 };
             }
-            if (!isFleetSafe(tool)) {
+            // Tools explicitly opted in via CODEBUDDY_EXECUTE_CODE_RPC_TOOLS
+            // bypass the fleetSafe gate — the operator accepted responsibility.
+            if (!extraTools.has(tool) && !isFleetSafe(tool)) {
                 return {
                     ok: false,
                     error: `TOOL_NOT_FLEET_SAFE: tool "${tool}" lacks fleetSafe metadata`,