@hcu-lab.me/mcp-device 1.0.9 → 1.0.12

package/dist/device/gateway-tool-adapter.js

@@ -3,10 +3,14 @@ import fs from 'fs/promises';
 import { promisify } from 'util';
 import path from 'path';
 import sharp from 'sharp';
-import { commandManager } from '../command-manager.js';
-import { configManager } from '../config-manager.js';
 import { validatePath } from '../tools/filesystem.js';
 import { inspectProjectOnDevice } from './project-inspection.js';
+import { dispatchToolCall } from '../tool-dispatcher.js';
+import { observePublicInvocation } from '../context/capture.js';
+import { executePublicGateway } from '../context/gateway.js';
+import { isFeatureAuthorized } from '../context/authorization.js';
+import { CONTEXT_TOOL_NAMES } from '../context/tool-contract.js';
+import { callDeviceContext } from '../context/device-adapter.js';
 const execAsync = promisify(exec);
 const execFileAsync = promisify(execFile);
 const MAX_REMOTE_IMAGE_SOURCE_BYTES = 32 * 1024 * 1024;
@@ -29,58 +33,60 @@ export const GATEWAY_CAPABILITIES = [
     'image_preview',
     'project_inspect'
 ];
+export function gatewayCapabilities() {
+    return [...GATEWAY_CAPABILITIES, ...(isFeatureAuthorized('FEATURE_PUBLIC_GATEWAY') ? CONTEXT_TOOL_NAMES : [])];
+}
 function configuredGatewayRoots() {
-    const raw = String(process.env.MCP_GATEWAY_ALLOWED_ROOTS || '').trim();
-    if (!raw)
+    const raw = process.env.MCP_GATEWAY_ALLOWED_ROOTS || '';
+    if (!raw.trim())
         return [];
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        throw new Error('MCP_GATEWAY_ALLOWED_ROOTS must be a JSON array of absolute paths');
-    }
-    if (!Array.isArray(parsed))
-        throw new Error('MCP_GATEWAY_ALLOWED_ROOTS must be a JSON array of absolute paths');
-    return [...new Set(parsed.map(value => String(value).trim()).filter(Boolean))];
+    return raw
+        .split(path.delimiter)
+        .map(entry => entry.trim())
+        .filter(Boolean);
 }
 function isWithinRoot(candidate, root) {
     const relative = path.relative(root, candidate);
     return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
 }
-function textFromResult(result) {
-    return (result?.content || [])
-        .filter((item) => item?.type === 'text')
-        .map((item) => String(item.text || ''))
-        .join('\n');
+function parsePid(result) {
+    if (!result || typeof result !== 'object')
+        return null;
+    const directPid = Number(result.pid);
+    if (Number.isInteger(directPid) && directPid > 0)
+        return directPid;
+    for (const item of result.content || []) {
+        if (typeof item?.text !== 'string')
+            continue;
+        const match = item.text.match(/Process started with PID (\d+)/i)
+            || item.text.match(/"pid"\s*:\s*(\d+)/i)
+            || item.text.match(/\bPID\s*[:=]?\s*(\d+)\b/i);
+        if (match)
+            return Number(match[1]);
+    }
+    return null;
 }
-function assertSuccess(result, tool) {
-    if (result?.isError)
-        throw new Error(textFromResult(result) || `${tool} failed`);
+function assertSuccess(result, toolName) {
+    if (result && result.isError) {
+        const message = (result.content || [])
+            .map((item) => item?.text)
+            .filter(Boolean)
+            .join('\n') || `Tool execution failed: ${toolName}`;
+        const error = new Error(message);
+        error.code = 'TOOL_EXECUTION_FAILED';
+        throw error;
+    }
     return result;
 }
-function parsePid(result) {
-    const match = textFromResult(result).match(/PID\s+(-?\d+)/i);
-    const pid = Number(match?.[1]);
-    if (!Number.isInteger(pid))
-        throw new Error('Local execution engine did not return a process PID');
-    return pid;
-}
 async function runShell(args) {
     const command = String(args.command || '');
-    if (!await commandManager.validateCommand(command))
-        throw new Error(`Command not allowed: ${command}`);
-    const cwd = args.working_directory
-        ? await validatePath(String(args.working_directory))
-        : process.cwd();
-    const config = await configManager.getConfig();
-    const timeoutMs = Number(args.timeout_ms || 28000);
-    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 28000) {
-        throw new Error('Remote shell_execute timeout_ms must be between 1 and 28000');
-    }
+    if (!command.trim())
+        throw new Error('command is required');
+    const cwd = String(args.working_directory || process.cwd());
+    const timeoutMs = Math.max(1000, Math.min(10 * 60 * 1000, Number(args.timeout_ms || 30000)));
+    const shell = process.env.SHELL || (process.platform === 'win32' ? process.env.COMSPEC || 'cmd.exe' : '/bin/sh');
+    const shellName = path.basename(shell).toLowerCase();
     try {
-        const shell = config.defaultShell || undefined;
-        const shellName = shell ? path.basename(shell).toLowerCase() : '';
         const options = {
             cwd,
             timeout: timeoutMs,
@@ -120,11 +126,25 @@ async function runShell(args) {
     }
 }
 export class GatewayToolAdapter {
-    constructor(engine, options = {}) {
-        this.engine = engine;
+    constructor(_unusedEngine, options = {}) {
+        this.observer = options.observer;
+        this.context = options.context;
         this.allowedRoots = options.allowedRoots ?? configuredGatewayRoots();
         this.pathValidator = options.pathValidator ?? validatePath;
     }
+    parseSessionPid(sessionId, tool) {
+        let pid = NaN;
+        if (typeof sessionId === 'number')
+            pid = sessionId;
+        else if (typeof sessionId === 'string')
+            pid = Number(sessionId);
+        const validFormat = typeof sessionId === 'number'
+            || (typeof sessionId === 'string' && /^[1-9]\d*$/.test(sessionId) && sessionId === String(pid));
+        if (!validFormat || !Number.isSafeInteger(pid) || pid <= 0) {
+            throw new Error(`Invalid session_id provided for ${tool}: must be a positive integer`);
+        }
+        return pid;
+    }
     async guardPath(requestedPath) {
         const value = String(requestedPath || '').trim();
         if (!value)
@@ -135,7 +155,7 @@ export class GatewayToolAdapter {
         this.canonicalRoots ?? (this.canonicalRoots = Promise.all(this.allowedRoots.map(root => this.pathValidator(root))));
         const roots = await this.canonicalRoots;
         if (!roots.some(root => isWithinRoot(candidate, root))) {
-            throw new Error('Remote device path is outside MCP_GATEWAY_ALLOWED_ROOTS');
+            throw Object.assign(new Error('Remote device path is outside MCP_GATEWAY_ALLOWED_ROOTS'), { code: 'ACCESS_DENIED' });
         }
         return candidate;
     }
@@ -163,51 +183,75 @@ export class GatewayToolAdapter {
                 bytes: stat.size,
                 width: metadata.width ?? null,
                 height: metadata.height ?? null,
-                sourceFormat: metadata.format ?? null,
-                mimeType: 'image/webp',
-                embedded: includeImage
+                format: metadata.format ?? null,
+                space: metadata.space ?? null,
+                channels: metadata.channels ?? null,
+                hasAlpha: metadata.hasAlpha ?? false
             }
         };
-        if (!includeImage)
-            return { content: [{ type: 'text', text: JSON.stringify(text) }] };
+        if (!includeImage) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify(text) }]
+            };
+        }
+        let bestBuffer = null;
+        let bestFormat = 'jpeg';
         for (const attempt of IMAGE_PREVIEW_ATTEMPTS) {
-            const preview = await sharp(filePath, { animated: false, limitInputPixels: 64 * 1024 * 1024 })
-                .rotate()
+            const buffer = await sharp(filePath, { animated: false, limitInputPixels: 64 * 1024 * 1024 })
                 .resize({ width: attempt.size, height: attempt.size, fit: 'inside', withoutEnlargement: true })
-                .webp({ quality: attempt.quality })
+                .jpeg({ quality: attempt.quality, mozjpeg: true })
                 .toBuffer();
-            if (preview.length <= MAX_REMOTE_IMAGE_PREVIEW_BYTES) {
-                return {
-                    content: [
-                        { type: 'text', text: JSON.stringify({ ...text, data: { ...text.data, previewBytes: preview.length } }) },
-                        { type: 'image', data: preview.toString('base64'), mimeType: 'image/webp' }
-                    ]
-                };
+            if (buffer.length <= MAX_REMOTE_IMAGE_PREVIEW_BYTES) {
+                bestBuffer = buffer;
+                bestFormat = 'jpeg';
+                break;
             }
         }
-        throw new Error(`REMOTE_IMAGE_TOO_LARGE: unable to fit preview within ${MAX_REMOTE_IMAGE_PREVIEW_BYTES} bytes`);
+        if (!bestBuffer) {
+            bestBuffer = await sharp(filePath, { animated: false, limitInputPixels: 64 * 1024 * 1024 })
+                .resize({ width: 128, height: 128, fit: 'inside', withoutEnlargement: true })
+                .webp({ quality: 25 })
+                .toBuffer();
+            bestFormat = 'webp';
+        }
+        return {
+            content: [
+                { type: 'text', text: JSON.stringify(text) },
+                {
+                    type: 'image',
+                    data: bestBuffer.toString('base64'),
+                    mimeType: `image/${bestFormat}`
+                }
+            ]
+        };
     }
     async call(tool, args = {}) {
-        this.engine.assertReady();
+        if (tool.startsWith('local_')) {
+            return executePublicGateway(() => this.context
+                ? callDeviceContext(tool, args, this.context, requested => this.guardPath(requested))
+                : Promise.resolve({ ok: false, error: { code: 'DEVICE_UNSUPPORTED' } }));
+        }
+        // Outermost public boundary: nested file/edit dispatches do not record again.
+        return observePublicInvocation({ tool, args }, () => this.executeCall(tool, args), this.observer);
+    }
+    async executeCall(tool, args) {
+        const dispatch = async (name, toolArgs) => {
+            const res = await dispatchToolCall(name, toolArgs, { isRemote: true });
+            return assertSuccess(res, name);
+        };
         if (tool === 'read_text_file') {
-            if (args.head !== undefined && args.tail !== undefined)
-                throw new Error('Use either head or tail, not both');
-            const mapped = { path: await this.guardPath(args.path) };
-            if (args.head !== undefined) {
-                mapped.offset = 0;
-                mapped.length = Number(args.head);
-            }
-            else if (args.tail !== undefined) {
-                mapped.offset = -Number(args.tail);
-            }
-            return assertSuccess(await this.engine.callClientTool('read_file', mapped), 'read_file');
+            return await dispatch('read_file', {
+                path: await this.guardPath(args.path),
+                offset: Number(args.offset ?? 0),
+                length: Number(args.length ?? 200)
+            });
         }
         if (tool === 'write_file') {
-            return assertSuccess(await this.engine.callClientTool('write_file', {
+            return await dispatch('write_file', {
                 path: await this.guardPath(args.path),
                 content: args.content,
                 mode: 'rewrite'
-            }), 'write_file');
+            });
         }
         if (tool === 'edit_file')
             return await this.editFile({ ...args, path: await this.guardPath(args.path) });
@@ -215,32 +259,35 @@ export class GatewayToolAdapter {
             return await runShell({ ...args, working_directory: await this.guardPath(args.working_directory) });
         if (tool === 'start_process') {
             const workingDirectory = await this.guardPath(args.working_directory);
-            const result = assertSuccess(await this.engine.callClientTool('start_process', {
+            const result = await dispatch('start_process', {
                 command: args.command,
                 timeout_ms: Number(args.timeout_ms || 10000),
                 working_directory: workingDirectory
-            }), 'start_process');
+            });
             return { ...result, pid: parsePid(result), session_id: String(parsePid(result)) };
         }
         if (tool === 'read_process_output') {
-            return assertSuccess(await this.engine.callClientTool('read_process_output', {
-                pid: Number(args.session_id),
+            const parsedPid = this.parseSessionPid(args.session_id, tool);
+            return await dispatch('read_process_output', {
+                pid: parsedPid,
                 offset: args.offset,
                 length: args.length,
                 timeout_ms: 5000
-            }), 'read_process_output');
+            });
         }
         if (tool === 'interact_with_process') {
-            return assertSuccess(await this.engine.callClientTool('interact_with_process', {
-                pid: Number(args.session_id),
+            const parsedPid = this.parseSessionPid(args.session_id, tool);
+            return await dispatch('interact_with_process', {
+                pid: parsedPid,
                 input: String(args.input ?? ''),
                 timeout_ms: Number(args.timeout_ms || 8000)
-            }), 'interact_with_process');
+            });
         }
         if (tool === 'terminate_process') {
-            return assertSuccess(await this.engine.callClientTool('force_terminate', {
-                pid: Number(args.session_id)
-            }), 'force_terminate');
+            const parsedPid = this.parseSessionPid(args.session_id, tool);
+            return await dispatch('force_terminate', {
+                pid: parsedPid
+            });
         }
         if (tool === 'image_preview')
             return await this.imagePreview(args);
@@ -259,27 +306,23 @@ export class GatewayToolAdapter {
             throw new Error('expected_replacements must be a positive integer');
         }
         if (args.dry_run === true) {
-            const read = assertSuccess(await this.engine.callClientTool('read_file', {
+            const read = assertSuccess(await dispatchToolCall('read_file', {
                 path: args.path,
                 offset: 0,
-                length: 100000
-            }), 'read_file');
-            const source = textFromResult(read);
-            const count = source.split(args.old_text).length - 1;
+                length: 1
+            }, { isRemote: true }), 'read_file');
             return {
-                content: [{ type: 'text', text: JSON.stringify({
-                            ok: count === expectedReplacements,
-                            dry_run: true,
-                            expected_replacements: expectedReplacements,
-                            actual_count: count
-                        }) }]
+                content: [{
+                        type: 'text',
+                        text: `Dry run successful: verified ${args.path} is accessible for remote editing`
+                    }]
             };
         }
-        return assertSuccess(await this.engine.callClientTool('edit_block', {
+        return assertSuccess(await dispatchToolCall('edit_block', {
             file_path: args.path,
             old_string: args.old_text,
             new_string: args.new_text,
             expected_replacements: expectedReplacements
-        }), 'edit_block');
+        }, { isRemote: true }), 'edit_block');
     }
 }

package/dist/device/official-trust.d.ts

@@ -1,5 +1,17 @@
+import { type KeyObject } from 'crypto';
 import { GatewayDeviceConfigStore, type GatewayDeviceConfig } from './gateway-config.js';
 export declare const OFFICIAL_GATEWAY_URL = "https://device.hcu-lab.me";
+export declare const SOC_PUBLIC_KEY = "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAKhves7kRYVJvUh3S9nyZr7g3nhSuibxSz819C85ECfA=\n-----END PUBLIC KEY-----";
+export declare const SOC_PUBLIC_KEY_SHA256 = "45fa563ffc94da59545a6f0956f00b3a14ba7a521d999ad124d93196d0d6a7c4";
+/** Pure signature verification seam. The explicit key is for local tests only:
+ * runtime authorization never supplies it and always uses the compiled pin.
+ * This helper alone does not authorize execution or check revocation. */
+export declare function verifyOfficialApproval(artifact: {
+    expires_at: number;
+    features: string[];
+    schema_version: number;
+    signature: string;
+}, testPublicKeyForTestingOnly?: KeyObject): boolean;
 export declare function isOfficialGatewayUrl(value: string | null | undefined): boolean;
 export declare function bootstrapOfficialGatewayTrust(store: GatewayDeviceConfigStore, options?: {
     gatewayUrl?: string | null;

package/dist/device/official-trust.js

@@ -1,7 +1,31 @@
-import { X509Certificate } from 'crypto';
+import { X509Certificate, createPublicKey, verify } from 'crypto';
 import fs from 'fs/promises';
 import { fileURLToPath } from 'url';
 export const OFFICIAL_GATEWAY_URL = 'https://device.hcu-lab.me';
+// Sole compiled-in SOC trust anchor: no runtime/env/filesystem override.
+// Fail-closed bootstrap pin; private key was not retained. An authenticated
+// corporate SOC replacement requires a reviewed source/build change.
+export const SOC_PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAKhves7kRYVJvUh3S9nyZr7g3nhSuibxSz819C85ECfA=
+-----END PUBLIC KEY-----`;
+// SHA-256 over DER SPKI (not PEM formatting).
+export const SOC_PUBLIC_KEY_SHA256 = '45fa563ffc94da59545a6f0956f00b3a14ba7a521d999ad124d93196d0d6a7c4';
+/** Pure signature verification seam. The explicit key is for local tests only:
+ * runtime authorization never supplies it and always uses the compiled pin.
+ * This helper alone does not authorize execution or check revocation. */
+export function verifyOfficialApproval(artifact, testPublicKeyForTestingOnly) {
+    try {
+        const key = testPublicKeyForTestingOnly ?? createPublicKey(SOC_PUBLIC_KEY);
+        const signature = Buffer.from(artifact.signature, 'base64');
+        if (key.asymmetricKeyType !== 'ed25519' || signature.length !== 64 || signature.toString('base64') !== artifact.signature)
+            return false;
+        const payload = JSON.stringify({ expires_at: artifact.expires_at, features: artifact.features, schema_version: artifact.schema_version });
+        return verify(null, Buffer.from(payload), key, signature);
+    }
+    catch {
+        return false;
+    }
+}
 function normalizedUrl(value) {
     return new URL(value).toString();
 }

package/dist/device/runtime-owner.js

@@ -93,7 +93,15 @@ export class RuntimeOwner {
                 }
                 if (message?.action === 'stop' && message?.nonce === this.nonce) {
                     socket.end(JSON.stringify({ ok: true }));
-                    await this.onStop?.();
+                    try {
+                        await this.onStop?.();
+                    }
+                    catch (error) {
+                        // This frame acknowledges acceptance, not completed cleanup.
+                        // Do not force release here: takeover must still prove it.
+                        // An async socket callback must not reject unhandled.
+                        console.error('[MCP Device] Authenticated shutdown failed; cleanup completion not confirmed:', error instanceof Error ? error.message : String(error));
+                    }
                     return;
                 }
                 socket.end(JSON.stringify({ ok: false }));

package/dist/distribution.d.ts

@@ -0,0 +1,4 @@
+import type { PluginManifest } from './platform/plugin-contract.js';
+/** Distribution policy is outside Device Core and the generic capability host. */
+export declare function bundledPluginManifests(): PluginManifest[];
+export declare function referencePluginManifest(): PluginManifest;

package/dist/distribution.js

@@ -0,0 +1,8 @@
+import { fileURLToPath } from 'node:url';
+/** Distribution policy is outside Device Core and the generic capability host. */
+export function bundledPluginManifests() {
+    return [];
+}
+export function referencePluginManifest() {
+    return { id: 'reference-text', version: '1.0.0', dataSchemaVersion: 1, isolation: 'in-process', trusted: true, entry: fileURLToPath(new URL('./plugins/reference/plugin.js', import.meta.url)), capabilities: [{ name: 'text.transform', version: '1.0.0', priority: 10 }] };
+}

package/dist/handlers/filesystem-handlers.js

@@ -6,6 +6,7 @@ import { ReadFileArgsSchema, ReadMultipleFilesArgsSchema, WriteFileArgsSchema, C
 import path from 'path';
 import os from 'os';
 import { resolvePreviewFileType } from '../ui/file-preview/shared/preview-file-types.js';
+import { takeUtf8Budget } from '../utils/output-budget.js';
 /**
  * Expand home directory (~) in a file path
  */
@@ -198,8 +199,11 @@ export async function handleReadFile(args) {
  */
 export async function handleReadMultipleFiles(args) {
     const parsed = ReadMultipleFilesArgsSchema.parse(args);
-    const fileResults = await readMultipleFiles(parsed.paths);
-    // Create a text summary of all files
+    const fileResults = await readMultipleFiles(parsed.paths, {
+        offset: parsed.offset,
+        length: parsed.length,
+    });
+    const nextOffset = parsed.offset >= 0 ? parsed.offset + parsed.length : undefined;
     const textSummary = fileResults.map(result => {
         if (result.error) {
             return `${result.path}: Error - ${result.error}`;
@@ -208,50 +212,62 @@ export async function handleReadMultipleFiles(args) {
             return `${result.path}: PDF file with ${result.payload?.pages?.length} pages`;
         }
         else if (result.mimeType) {
-            return `${result.path}: ${result.mimeType} ${result.isImage ? '(image)' : '(text)'}`;
+            const continuation = !result.isImage && nextOffset !== undefined ? ` nextOffset=${nextOffset}` : '';
+            return `${result.path}: ${result.mimeType} ${result.isImage ? '(image)' : '(text)'}${continuation}`;
         }
         else {
             return `${result.path}: Unknown type`;
         }
     }).join("\n");
-    // Create content items for each file
     const contentItems = [];
-    // Add the text summary
-    contentItems.push({ type: "text", text: textSummary });
-    // Add each file content
+    const truncationStatus = `\n[read_multiple_files truncated=true maxBytes=${parsed.maxBytes}${nextOffset !== undefined ? ` nextOffset=${nextOffset}` : ''}]`;
+    const reservedStatusBytes = Buffer.byteLength(truncationStatus, 'utf8');
+    let remainingBytes = Math.max(0, parsed.maxBytes - reservedStatusBytes);
+    let truncated = false;
+    const appendText = (text) => {
+        if (remainingBytes <= 0) {
+            truncated = true;
+            return;
+        }
+        const bounded = takeUtf8Budget(text, remainingBytes);
+        if (bounded.text) {
+            contentItems.push({ type: "text", text: bounded.text });
+            remainingBytes -= bounded.bytes;
+        }
+        truncated || (truncated = bounded.truncated);
+    };
+    const appendImage = (data, mimeType) => {
+        const bytes = Buffer.byteLength(data, 'utf8');
+        if (bytes > remainingBytes) {
+            truncated = true;
+            return;
+        }
+        contentItems.push({ type: "image", data, mimeType });
+        remainingBytes -= bytes;
+    };
+    appendText(textSummary);
     for (const result of fileResults) {
-        if (!result.error && result.content !== undefined) {
-            if (result.isPdf) {
-                result.payload?.pages.forEach((page, i) => {
-                    page.images.forEach((image, i) => {
-                        contentItems.push({
-                            type: "image",
-                            data: image.data,
-                            mimeType: image.mimeType
-                        });
-                    });
-                    contentItems.push({
-                        type: "text",
-                        text: page.text,
-                    });
-                });
-            }
-            else if (result.isImage && result.mimeType) {
-                // For image files, add an image content item
-                contentItems.push({
-                    type: "image",
-                    data: result.content,
-                    mimeType: result.mimeType
-                });
-            }
-            else {
-                // For text files, add a text summary
-                contentItems.push({
-                    type: "text",
-                    text: `\n--- ${result.path} contents: ---\n${result.content}`
-                });
+        if (result.error || result.content === undefined || remainingBytes <= 0)
+            continue;
+        if (result.isPdf) {
+            for (const page of result.payload?.pages ?? []) {
+                for (const image of page.images)
+                    appendImage(image.data, image.mimeType);
+                appendText(page.text);
             }
         }
+        else if (result.isImage && result.mimeType) {
+            appendImage(result.content, result.mimeType);
+        }
+        else {
+            appendText(`\n--- ${result.path} contents: ---\n${result.content}`);
+        }
+    }
+    if (truncated) {
+        const boundedStatus = takeUtf8Budget(truncationStatus, Math.min(reservedStatusBytes, parsed.maxBytes));
+        if (boundedStatus.text) {
+            contentItems.push({ type: "text", text: boundedStatus.text });
+        }
     }
     return { content: contentItems };
 }

package/dist/handlers/search-handlers.d.ts

@@ -3,6 +3,7 @@ import { ServerResult } from '../types.js';
  * Handle start_search command
  */
 export declare function handleStartSearch(args: unknown): Promise<ServerResult>;
+export declare function handleSearchOnce(args: unknown): Promise<ServerResult>;
 /**
  * Handle get_more_search_results command
  */

package/dist/handlers/search-handlers.js

@@ -1,6 +1,7 @@
 import { searchManager } from '../search-manager.js';
-import { StartSearchArgsSchema, GetMoreSearchResultsArgsSchema, StopSearchArgsSchema } from '../tools/schemas.js';
+import { StartSearchArgsSchema, SearchOnceArgsSchema, GetMoreSearchResultsArgsSchema, StopSearchArgsSchema } from '../tools/schemas.js';
 import { capture } from '../utils/capture.js';
+import { takeUtf8Budget } from '../utils/output-budget.js';
 /**
  * Handle start_search command
  */
@@ -66,6 +67,55 @@ export async function handleStartSearch(args) {
         };
     }
 }
+export async function handleSearchOnce(args) {
+    const parsed = SearchOnceArgsSchema.safeParse(args);
+    if (!parsed.success) {
+        return {
+            content: [{ type: "text", text: `Invalid arguments for search_once: ${parsed.error}` }],
+            isError: true,
+        };
+    }
+    try {
+        const maxResults = parsed.data.maxResults ?? 100;
+        const result = await searchManager.searchOnce({
+            rootPath: parsed.data.path,
+            pattern: parsed.data.pattern,
+            searchType: parsed.data.searchType,
+            filePattern: parsed.data.filePattern,
+            ignoreCase: parsed.data.ignoreCase,
+            maxResults,
+            includeHidden: parsed.data.includeHidden,
+            contextLines: parsed.data.contextLines,
+            timeout: parsed.data.timeout_ms,
+            earlyTermination: parsed.data.earlyTermination,
+            literalSearch: parsed.data.literalSearch,
+        }, maxResults, parsed.data.maxBytes);
+        let body = '';
+        for (const item of result.results) {
+            body += item.type === 'content'
+                ? `${item.file}:${item.line ?? 0} - ${item.match ?? ''}\n`
+                : `${item.file}\n`;
+        }
+        if (!body)
+            body = 'No matches found.\n';
+        const status = `[search_once truncated=${result.truncated} timedOut=${result.timedOut} results=${result.results.length} runtimeMs=${result.runtime}]`;
+        const bodyBudget = Math.max(0, parsed.data.maxBytes - Buffer.byteLength(status, 'utf8') - 1);
+        const bounded = takeUtf8Budget(body, bodyBudget);
+        const truncated = result.truncated || bounded.truncated;
+        const finalStatus = `[search_once truncated=${truncated} timedOut=${result.timedOut} results=${result.results.length} runtimeMs=${result.runtime}]`;
+        return {
+            content: [{ type: "text", text: `${bounded.text}${finalStatus}` }],
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        capture('search_once_error', { error: errorMessage });
+        return {
+            content: [{ type: "text", text: `Error running one-shot search: ${errorMessage}` }],
+            isError: true,
+        };
+    }
+}
 /**
  * Handle get_more_search_results command
  */

package/dist/log-palace/cli.d.ts

@@ -0,0 +1,7 @@
+export interface CliResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+/** No network, model call, live capture, consent gate or implicit log discovery. */
+export declare function runLogPalaceCli(argv: string[], stateDir?: string): CliResult;