@hcu-lab.me/mcp-device 1.0.8 → 1.0.10

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/mcp-device.d.ts

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export {};
+import './bootstrap.js';

package/dist/mcp-device.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
+import './bootstrap.js';
 // MCP Device publishes only the authenticated device runtime surface.
 if (process.argv[2] !== 'remote')
     process.argv.splice(2, 0, 'remote');
 const { runRemote } = await import('./npm-scripts/remote.js');
 await runRemote();
-export {};

package/dist/search-manager.d.ts

@@ -51,6 +51,12 @@ export interface SearchSessionOptions {
         totalResults: number;
         runtime: number;
     }>;
+    searchOnce(options: SearchSessionOptions, maxResults?: number, maxBytes?: number): Promise<{
+        results: SearchResult[];
+        runtime: number;
+        truncated: boolean;
+        timedOut: boolean;
+    }>;
     /**
      * Read search results with offset-based pagination (like read_file)
      * Supports both range reading and tail behavior

package/dist/search-manager.js

@@ -142,6 +142,129 @@ import PizZip from 'pizzip';
             runtime: Date.now() - session.startTime
         };
     }
+    async searchOnce(options, maxResults = 100, maxBytes = 256 * 1024) {
+        const startTime = Date.now();
+        const validPath = await validatePath(options.rootPath);
+        const args = this.buildRipgrepArgs({
+            ...options,
+            rootPath: validPath,
+            maxResults: maxResults + 1,
+        });
+        const rgPath = await getRipgrepPath();
+        return new Promise((resolve, reject) => {
+            const child = spawn(rgPath, args, { windowsHide: true });
+            const results = [];
+            const pendingContext = [];
+            let buffered = '';
+            let capturedBytes = 0;
+            let matchCount = 0;
+            let truncated = false;
+            let timedOut = false;
+            let settled = false;
+            let timer;
+            const stopForTruncation = () => {
+                truncated = true;
+                if (!child.killed)
+                    child.kill('SIGTERM');
+            };
+            const flushPendingContext = (reservedBytes = 0) => {
+                let dropped = false;
+                for (const item of pendingContext) {
+                    if (capturedBytes + item.bytes + reservedBytes > maxBytes) {
+                        dropped = true;
+                        continue;
+                    }
+                    results.push(item.result);
+                    capturedBytes += item.bytes;
+                }
+                pendingContext.length = 0;
+                return dropped;
+            };
+            const finish = () => {
+                if (settled)
+                    return;
+                if (pendingContext.length > 0 && matchCount > 0) {
+                    if (flushPendingContext())
+                        truncated = true;
+                }
+                settled = true;
+                if (timer)
+                    clearTimeout(timer);
+                resolve({
+                    results,
+                    runtime: Date.now() - startTime,
+                    truncated,
+                    timedOut,
+                });
+            };
+            const fail = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timer)
+                    clearTimeout(timer);
+                reject(error);
+            };
+            const acceptLine = (line) => {
+                if (!line.trim() || truncated)
+                    return;
+                const result = this.parseLine(line, options.searchType);
+                if (!result)
+                    return;
+                const resultBytes = Buffer.byteLength(`${result.file}\n${result.match ?? ''}\n`, 'utf8');
+                const isContext = options.searchType === 'content' && line.includes('"type":"context"');
+                if (isContext) {
+                    pendingContext.push({ result, bytes: resultBytes });
+                    return;
+                }
+                if (matchCount >= maxResults) {
+                    pendingContext.length = 0;
+                    stopForTruncation();
+                    return;
+                }
+                if (capturedBytes + resultBytes > maxBytes) {
+                    pendingContext.length = 0;
+                    stopForTruncation();
+                    return;
+                }
+                const droppedContext = flushPendingContext(resultBytes);
+                results.push(result);
+                capturedBytes += resultBytes;
+                matchCount++;
+                if (droppedContext) {
+                    stopForTruncation();
+                }
+            };
+            child.stdout?.on('data', (data) => {
+                buffered += data.toString();
+                const lines = buffered.split(/\r?\n/);
+                buffered = lines.pop() ?? '';
+                for (const line of lines)
+                    acceptLine(line);
+            });
+            let stderr = '';
+            child.stderr?.on('data', (data) => {
+                stderr += data.toString();
+            });
+            child.once('error', fail);
+            child.once('close', code => {
+                if (buffered)
+                    acceptLine(buffered);
+                if (code && code !== 1 && !truncated && !timedOut) {
+                    fail(new Error(stderr.trim() || `ripgrep exited with code ${code}`));
+                    return;
+                }
+                finish();
+            });
+            const timeoutMs = options.timeout ?? 5000;
+            timer = setTimeout(() => {
+                timedOut = true;
+                truncated = true;
+                if (!child.killed)
+                    child.kill('SIGTERM');
+            }, timeoutMs);
+        });
+    }
     /**
      * Read search results with offset-based pagination (like read_file)
      * Supports both range reading and tail behavior

package/dist/server.d.ts

@@ -39,8 +39,21 @@ declare let currentClient: {
     version: string;
 };
 declare let currentCallIsRemote: boolean;
+/**
+ * Set whether the current tool call is from a remote device.
+ * Called once per tool call by the CallTool handler.
+ */
+export declare function setCurrentCallIsRemote(isRemote: boolean): void;
 declare let currentRemoteClient: {
     name?: string;
     version?: string;
 } | null;
+/**
+ * Set the remote caller's client for the current tool call (null when local).
+ * Called once per tool call by the CallTool handler.
+ */
+export declare function setCurrentRemoteClient(clientInfo: {
+    name?: string;
+    version?: string;
+} | null): void;
 export { currentClient, currentCallIsRemote, currentRemoteClient };

package/dist/server.js

@@ -83,7 +83,7 @@ let currentCallIsRemote = false;
  * Set whether the current tool call is from a remote device.
  * Called once per tool call by the CallTool handler.
  */
-function setCurrentCallIsRemote(isRemote) {
+export function setCurrentCallIsRemote(isRemote) {
     currentCallIsRemote = isRemote;
 }
 // The remote caller's client for the in-flight tool call (e.g. openai-mcp,
@@ -96,7 +96,7 @@ let currentRemoteClient = null;
  * Set the remote caller's client for the current tool call (null when local).
  * Called once per tool call by the CallTool handler.
  */
-function setCurrentRemoteClient(clientInfo) {
+export function setCurrentRemoteClient(clientInfo) {
     currentRemoteClient = clientInfo;
 }
 /**

package/dist/terminal-manager.d.ts

@@ -7,6 +7,9 @@ interface CompletedSession {
     endTime: Date;
     evictedLines: number;
     evictedChars: number;
+    lastReadIndex: number;
+    lastReadOffset: number;
+    bufferedChars: number;
 }
 /**
  * Output buffering caps. Without a cap, a process emitting enough output makes
@@ -43,6 +46,8 @@ export declare class TerminalManager {
      * Append text to a session's line buffer
      * Handles partial lines and newline splitting
      */
+    private notifyOutputProgress;
+    waitForOutputProgress(pid: number, sinceVersion: number, timeoutMs: number): Promise<void>;
     private appendToLineBuffer;
     /**
      * Read process output with pagination (like file reading)
@@ -51,6 +56,10 @@ export declare class TerminalManager {
      * @param length Max lines to return
      * @param updateReadIndex Whether to update lastReadIndex (default: true for offset=0)
      */
+    markOutputConsumed(pid: number, cursor?: {
+        lineIndex: number;
+        lineOffset: number;
+    }): void;
     readOutputPaginated(pid: number, offset?: number, length?: number): PaginatedOutputResult | null;
     /**
      * Internal helper to read from a line buffer with offset/length

package/dist/terminal-manager.js

@@ -129,6 +129,9 @@ export class TerminalManager {
         }
     }
     async executeCommand(command, timeoutMs = DEFAULT_COMMAND_TIMEOUT, shell, collectTiming = false, workingDirectory) {
+        const configuredWaitCap = Number(await configManager.getValue('maxProcessWaitMs'));
+        const waitCapMs = Number.isFinite(configuredWaitCap) && configuredWaitCap > 0 ? configuredWaitCap : 180000;
+        const effectiveWaitMs = Math.min(Math.max(0, timeoutMs), waitCapMs);
         // Get the shell from config if not specified
         let shellToUse = shell;
         if (!shellToUse) {
@@ -229,11 +232,31 @@ export class TerminalManager {
                 isBlocked: false
             };
         }
+        // PID collision / reuse stopgap (1.0.10 P2.1):
+        // If a session with this PID already exists:
+        // - Check active sessions: if still live, reject with an explicit error to prevent aliasing.
+        // - Check completed sessions: if stale completed session exists, evict it cleanly.
+        if (this.sessions.has(childProcess.pid)) {
+            try {
+                childProcess.kill();
+            }
+            catch (killErr) {
+                console.error(`Failed to kill conflicting child process ${childProcess.pid}:`, killErr);
+            }
+            throw new Error(`PID collision detected: process ${childProcess.pid} is already running under an active session.`);
+        }
+        if (this.completedSessions.has(childProcess.pid)) {
+            console.warn(`[PID Collision] Evicting stale completed session for PID ${childProcess.pid}`);
+            this.completedSessions.delete(childProcess.pid);
+        }
         const session = {
             pid: childProcess.pid,
             process: childProcess,
             outputLines: [], // Line-based buffer
             lastReadIndex: 0, // Track where "new" output starts
+            lastReadOffset: 0, // Character offset inside a partially consumed line
+            outputVersion: 0,
+            outputWaiters: new Set(),
             isBlocked: false,
             startTime: new Date(),
             bufferedChars: 0,
@@ -256,6 +279,10 @@ export class TerminalManager {
                 if (resolved)
                     return;
                 resolved = true;
+                if (session.outputLines.length > 0) {
+                    const lineIndex = session.outputLines.length - 1;
+                    result.deliveredCursor = { lineIndex, lineOffset: session.outputLines[lineIndex].length };
+                }
                 if (periodicCheck)
                     clearInterval(periodicCheck);
                 // Add timing info if requested
@@ -388,32 +415,35 @@ export class TerminalManager {
                     output,
                     isBlocked: true
                 });
-            }, timeoutMs);
+            }, effectiveWaitMs);
+            let processExitCode = null;
             childProcess.on('exit', (code) => {
-                if (childProcess.pid) {
-                    // Store completed session before removing active session
-                    this.completedSessions.set(childProcess.pid, {
-                        pid: childProcess.pid,
-                        outputLines: [...session.outputLines], // Copy line buffer
-                        exitCode: code,
-                        startTime: session.startTime,
-                        endTime: new Date(),
-                        evictedLines: session.evictedLines,
-                        evictedChars: session.evictedChars
-                    });
-                    // Keep only last 100 completed sessions
-                    if (this.completedSessions.size > 100) {
-                        const oldestKey = Array.from(this.completedSessions.keys())[0];
-                        this.completedSessions.delete(oldestKey);
-                    }
-                    this.sessions.delete(childProcess.pid);
-                }
+                processExitCode = code;
                 exitReason = 'process_exit';
-                resolveOnce({
+                resolveOnce({ pid: childProcess.pid, output, isBlocked: false });
+            });
+            // Finalize only after stdio has closed so fast-exit stdout/stderr cannot be lost.
+            childProcess.on('close', (code) => {
+                if (!childProcess.pid)
+                    return;
+                this.completedSessions.set(childProcess.pid, {
                     pid: childProcess.pid,
-                    output,
-                    isBlocked: false
+                    outputLines: [...session.outputLines],
+                    exitCode: processExitCode ?? code,
+                    startTime: session.startTime,
+                    endTime: new Date(),
+                    evictedLines: session.evictedLines,
+                    evictedChars: session.evictedChars,
+                    lastReadIndex: session.lastReadIndex,
+                    lastReadOffset: session.lastReadOffset,
+                    bufferedChars: session.bufferedChars
                 });
+                if (this.completedSessions.size > 100) {
+                    const oldestKey = Array.from(this.completedSessions.keys())[0];
+                    this.completedSessions.delete(oldestKey);
+                }
+                this.notifyOutputProgress(session);
+                this.sessions.delete(childProcess.pid);
             });
         });
     }
@@ -421,6 +451,27 @@ export class TerminalManager {
      * Append text to a session's line buffer
      * Handles partial lines and newline splitting
      */
+    notifyOutputProgress(session) {
+        session.outputVersion++;
+        for (const waiter of session.outputWaiters)
+            waiter();
+        session.outputWaiters.clear();
+    }
+    async waitForOutputProgress(pid, sinceVersion, timeoutMs) {
+        const session = this.sessions.get(pid);
+        if (!session || session.outputVersion !== sinceVersion)
+            return;
+        await new Promise((resolve) => {
+            let timer;
+            const done = () => {
+                session.outputWaiters.delete(done);
+                clearTimeout(timer);
+                resolve();
+            };
+            session.outputWaiters.add(done);
+            timer = setTimeout(done, timeoutMs);
+        });
+    }
     appendToLineBuffer(session, text) {
         if (!text)
             return;
@@ -469,6 +520,7 @@ export class TerminalManager {
             if (session.lastReadIndex > 0)
                 session.lastReadIndex--;
         }
+        this.notifyOutputProgress(session);
     }
     /**
      * Read process output with pagination (like file reading)
@@ -477,9 +529,33 @@ export class TerminalManager {
      * @param length Max lines to return
      * @param updateReadIndex Whether to update lastReadIndex (default: true for offset=0)
      */
+    markOutputConsumed(pid, cursor) {
+        if (!cursor)
+            return;
+        const session = this.sessions.get(pid);
+        if (session) {
+            session.lastReadIndex = Math.min(cursor.lineIndex, Math.max(0, session.outputLines.length - 1));
+            session.lastReadOffset = cursor.lineOffset;
+            return;
+        }
+        const completed = this.completedSessions.get(pid);
+        if (completed) {
+            completed.lastReadIndex = Math.min(cursor.lineIndex, Math.max(0, completed.outputLines.length - 1));
+            completed.lastReadOffset = cursor.lineOffset;
+        }
+    }
     readOutputPaginated(pid, offset = 0, length = 1000) {
         // First check active sessions
         const session = this.sessions.get(pid);
+        if (session && offset === 0 && session.outputLines.length > 0) {
+            const start = Math.min(session.lastReadIndex, session.outputLines.length - 1);
+            const first = session.outputLines[start].slice(session.lastReadOffset);
+            const tail = session.outputLines.slice(start + 1, start + length);
+            const lines = first || tail.length === 0 ? [first, ...tail] : tail;
+            session.lastReadIndex = Math.min(start + lines.length - 1, session.outputLines.length - 1);
+            session.lastReadOffset = session.outputLines[session.lastReadIndex].length;
+            return { lines, totalLines: session.outputLines.length, readFrom: start, readCount: lines.length, remaining: Math.max(0, session.outputLines.length - start - lines.length), isComplete: false, evictedLines: session.evictedLines };
+        }
         if (session) {
             const result = this.readFromLineBuffer(session.outputLines, offset, length, session.lastReadIndex, (newIndex) => { session.lastReadIndex = newIndex; }, false, undefined);
             result.evictedLines = session.evictedLines;
@@ -489,7 +565,7 @@ export class TerminalManager {
         const completedSession = this.completedSessions.get(pid);
         if (completedSession) {
             const runtimeMs = completedSession.endTime.getTime() - completedSession.startTime.getTime();
-            const result = this.readFromLineBuffer(completedSession.outputLines, offset, length, 0, // Completed sessions don't track read position
+            const result = this.readFromLineBuffer(completedSession.outputLines, offset, length, 0, // Protected baseline: completed sessions read from beginning and remain replayable
             () => { }, // No-op for completed sessions
             true, completedSession.exitCode, runtimeMs);
             result.evictedLines = completedSession.evictedLines;
@@ -588,17 +664,12 @@ export class TerminalManager {
      */
     captureOutputSnapshot(pid) {
         const session = this.sessions.get(pid);
-        if (session) {
-            const fullOutput = session.outputLines.join('\n');
-            return {
-                // Absolute since process start (includes evicted output), so the
-                // offset stays valid even if the cap evicts lines between
-                // snapshot and read.
-                totalChars: session.evictedChars + fullOutput.length,
-                lineCount: session.evictedLines + session.outputLines.length
-            };
-        }
-        return null;
+        if (!session)
+            return null;
+        return {
+            totalChars: session.evictedChars + session.bufferedChars,
+            lineCount: session.evictedLines + session.outputLines.length
+        };
     }
     /**
      * Get output that appeared since a snapshot was taken.
@@ -609,12 +680,12 @@ export class TerminalManager {
         // Check active session first
         const session = this.sessions.get(pid);
         if (session) {
-            return TerminalManager.outputSinceSnapshot(session.outputLines, session.evictedChars, snapshot.totalChars);
+            return TerminalManager.outputSinceSnapshot(session.outputLines, session.bufferedChars, session.evictedChars, snapshot.totalChars);
         }
         // Fallback to completed sessions - process may have finished between snapshot and poll
         const completedSession = this.completedSessions.get(pid);
         if (completedSession) {
-            return TerminalManager.outputSinceSnapshot(completedSession.outputLines, completedSession.evictedChars, snapshot.totalChars);
+            return TerminalManager.outputSinceSnapshot(completedSession.outputLines, completedSession.bufferedChars, completedSession.evictedChars, snapshot.totalChars);
         }
         return null;
     }
@@ -623,13 +694,27 @@ export class TerminalManager {
      * If eviction dropped part of the unseen output, returns what the buffer
      * still holds — the oldest unseen chars are lost to the cap.
      */
-    static outputSinceSnapshot(outputLines, evictedChars, snapshotTotalChars) {
-        const fullOutput = outputLines.join('\n');
-        const newChars = evictedChars + fullOutput.length - snapshotTotalChars;
-        if (newChars <= 0) {
-            return ''; // No new output
+    static outputSinceSnapshot(outputLines, bufferedChars, evictedChars, snapshotTotalChars) {
+        const newChars = evictedChars + bufferedChars - snapshotTotalChars;
+        if (newChars <= 0)
+            return '';
+        let remaining = newChars;
+        const parts = [];
+        for (let i = outputLines.length - 1; i >= 0 && remaining > 0; i--) {
+            const line = outputLines[i];
+            const separator = i < outputLines.length - 1 ? 1 : 0;
+            const available = line.length + separator;
+            if (remaining >= available) {
+                parts.push((separator ? '\n' : '') + line);
+                remaining -= available;
+            }
+            else {
+                const suffixLength = Math.max(0, remaining - separator);
+                parts.push((separator ? '\n' : '') + line.slice(Math.max(0, line.length - suffixLength)));
+                remaining = 0;
+            }
         }
-        return fullOutput.substring(Math.max(0, fullOutput.length - newChars));
+        return parts.reverse().join('');
     }
     /**
    * Get a session by PID

package/dist/tool-dispatcher.d.ts

@@ -0,0 +1,11 @@
+import { ServerResult } from './types.js';
+export interface DispatchToolOptions {
+    isRemote?: boolean;
+    clientInfo?: {
+        name?: string;
+        version?: string;
+    };
+    origin?: string;
+    metadata?: any;
+}
+export declare function dispatchToolCall(name: string, args: any, options?: DispatchToolOptions): Promise<ServerResult>;