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

package/dist/platform/state-backup.js

@@ -0,0 +1,399 @@
+import { closeSync, constants, copyFileSync, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, writeFileSync, chmodSync } from 'node:fs';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { acquireServerLease } from './runtime-lease.js';
+import { probeRuntimeOwner } from '../device/runtime-owner.js';
+const EXCLUDED = ['server-runtime.lock', 'plugins/registry.lock'];
+const MAX_FILES = 100000, MAX_BYTES = 32 * 1024 * 1024 * 1024;
+function digest(value) { return createHash('sha256').update(JSON.stringify(value)).digest('hex'); }
+function fail(message) { throw new Error(message); }
+function relativePath(value) {
+    if (typeof value !== 'string' || !value || value.includes('\\') || value.includes(':') || value.includes('\0') ||
+        path.posix.isAbsolute(value) || path.win32.isAbsolute(value) || value.split('/').some(x => !x || x === '.' || x === '..'))
+        fail('UNSAFE_BACKUP_PATH');
+    return value;
+}
+function noSymlinkAncestors(input) {
+    const absolute = path.resolve(input), parsed = path.parse(absolute);
+    let current = parsed.root;
+    for (const segment of absolute.slice(parsed.root.length).split(path.sep).filter(Boolean)) {
+        current = path.join(current, segment);
+        try {
+            if (lstatSync(current).isSymbolicLink())
+                fail('SYMLINK_STATE_PATH');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                break;
+            throw error;
+        }
+    }
+    return absolute;
+}
+function sourceRoot(input) {
+    const root = noSymlinkAncestors(input);
+    if (root === path.parse(root).root || !existsSync(root) || !lstatSync(root).isDirectory())
+        fail('STATE_SOURCE_DIRECTORY_REQUIRED');
+    return root;
+}
+function absentTarget(input) {
+    const target = noSymlinkAncestors(input);
+    if (target === path.parse(target).root || existsSync(target))
+        fail('STATE_TARGET_MUST_NOT_EXIST');
+    return target;
+}
+function contained(a, b) { const r = path.relative(a, b); return r === '' || (!r.startsWith('..' + path.sep) && r !== '..' && !path.isAbsolute(r)); }
+function separate(...roots) {
+    for (let i = 0; i < roots.length; i++)
+        for (let j = i + 1; j < roots.length; j++)
+            if (contained(roots[i], roots[j]) || contained(roots[j], roots[i]))
+                fail('STATE_ROOTS_OVERLAP');
+}
+async function assertStopped(root, ownedLease = false) {
+    const owner = await probeRuntimeOwner({ root, identity: path.join(root, 'gateway-identity.json'), config: path.join(root, 'gateway-config.json'),
+        status: path.join(root, 'gateway-status.json'), runtime: path.join(root, 'runtime'), update: path.join(root, 'update') });
+    if (owner)
+        fail('DEVICE_RUNTIME_ACTIVE');
+    if (existsSync(path.join(root, 'runtime-control.json')))
+        fail('DEVICE_RUNTIME_STOP_NOT_PROVEN');
+    const registry = path.join(root, 'plugins', 'registry.lock');
+    if (existsSync(registry))
+        fail('PLUGIN_REGISTRY_BUSY');
+    const lease = path.join(root, 'server-runtime.lock');
+    if (!ownedLease && existsSync(lease)) {
+        let pid;
+        try {
+            pid = JSON.parse(readFileSync(lease, 'utf8')).pid;
+        }
+        catch {
+            fail('STATE_RUNTIME_LEASE_UNREADABLE');
+        }
+        if (!Number.isSafeInteger(pid) || pid <= 0)
+            fail('STATE_RUNTIME_LEASE_UNREADABLE');
+        try {
+            process.kill(pid, 0);
+            fail('STATE_RUNTIME_ACTIVE');
+        }
+        catch (error) {
+            if (error.code !== 'ESRCH')
+                throw error;
+        }
+    }
+}
+function fileRecord(root, relative) {
+    relativePath(relative);
+    const full = path.join(root, ...relative.split('/'));
+    noSymlinkAncestors(full);
+    const before = lstatSync(full);
+    if (!before.isFile() || before.isSymbolicLink())
+        fail('NONREGULAR_STATE_FILE');
+    if (before.size > MAX_BYTES)
+        fail('STATE_BACKUP_TOO_LARGE');
+    const fd = openSync(full, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    const hasher = createHash('sha256'), buffer = Buffer.allocUnsafe(64 * 1024);
+    let offset = 0;
+    try {
+        if (!fstatSync(fd).isFile())
+            fail('NONREGULAR_STATE_FILE');
+        for (;;) {
+            const size = readSync(fd, buffer, 0, buffer.length, offset);
+            if (!size)
+                break;
+            hasher.update(buffer.subarray(0, size));
+            offset += size;
+        }
+        const after = fstatSync(fd);
+        if (offset !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ino !== before.ino)
+            fail('STATE_CHANGED_DURING_BACKUP');
+    }
+    finally {
+        closeSync(fd);
+    }
+    return { path: relative, bytes: offset, sha256: hasher.digest('hex'), mode: before.mode & 0o777 };
+}
+function inventory(root, options = {}) {
+    const files = [], directories = [];
+    let totalBytes = 0;
+    const names = new Set();
+    const visit = (directory, prefix = '') => {
+        for (const entry of readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            const rel = relativePath(prefix ? prefix + '/' + entry.name : entry.name);
+            if (options.excludeLocks !== false && EXCLUDED.includes(rel))
+                continue;
+            // An ancestor lease does not stop a nested Device/server or its plugin writer.
+            if (options.excludeLocks !== false && rel.includes('/') &&
+                (['server-runtime.lock', 'runtime-control.json'].includes(entry.name) || rel.endsWith('/plugins/registry.lock')))
+                fail('NESTED_RUNTIME_REQUIRES_SEPARATE_STOPPED_BACKUP');
+            const key = rel.toLocaleLowerCase('en-US');
+            if (names.has(key))
+                fail('CASE_COLLIDING_STATE_PATH');
+            names.add(key);
+            const full = path.join(directory, entry.name), stat = lstatSync(full);
+            if (stat.isSymbolicLink())
+                fail('SYMLINK_STATE_PATH');
+            if (stat.isDirectory()) {
+                directories.push(rel);
+                visit(full, rel);
+                continue;
+            }
+            if (!stat.isFile())
+                fail('NONREGULAR_STATE_FILE');
+            if (options.rejectWal !== false && /(?:-wal|-journal)$/i.test(rel) && stat.size > 0)
+                fail('SQLITE_CHECKPOINT_REQUIRED');
+            if (files.length >= MAX_FILES)
+                fail('STATE_FILE_LIMIT');
+            const file = fileRecord(root, rel);
+            files.push(file);
+            totalBytes += file.bytes;
+            if (totalBytes > MAX_BYTES)
+                fail('STATE_BACKUP_TOO_LARGE');
+        }
+    };
+    visit(root);
+    files.sort((a, b) => a.path.localeCompare(b.path));
+    directories.sort();
+    return { files, directories, totalBytes, sourceDigest: digest({ files: files.map(({ mode, ...file }) => file), directories, totalBytes }) };
+}
+function flushFile(file) {
+    const mode = lstatSync(file).mode & 0o777;
+    chmodSync(file, mode | 0o600);
+    const fd = openSync(file, 'r+');
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+        chmodSync(file, mode);
+    }
+}
+function writeJson(file, value) { writeFileSync(file, JSON.stringify(value, null, 2) + '\n', { mode: 0o600, flag: 'wx' }); flushFile(file); }
+function copyInventory(from, to, items) {
+    mkdirSync(to, { recursive: false, mode: 0o700 });
+    for (const directory of items.directories)
+        mkdirSync(path.join(to, ...relativePath(directory).split('/')), { recursive: true, mode: 0o700 });
+    for (const file of items.files) {
+        const destination = path.join(to, ...relativePath(file.path).split('/'));
+        mkdirSync(path.dirname(destination), { recursive: true, mode: 0o700 });
+        copyFileSync(path.join(from, ...file.path.split('/')), destination, constants.COPYFILE_EXCL);
+        chmodSync(destination, file.mode);
+        flushFile(destination);
+        if (fileRecord(to, file.path).sha256 !== file.sha256)
+            fail('STATE_CHANGED_DURING_BACKUP');
+    }
+}
+function stageFor(target) {
+    mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+    noSymlinkAncestors(path.dirname(target));
+    const stage = path.join(path.dirname(target), '.' + path.basename(target) + '.' + randomUUID() + '.staging');
+    mkdirSync(stage, { mode: 0o700 });
+    return stage;
+}
+function publish(stage, target) { absentTarget(target); renameSync(stage, target); }
+async function destinationGuard(target, operation) {
+    mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+    noSymlinkAncestors(path.dirname(target));
+    const guard = path.join(path.dirname(target), '.' + path.basename(target) + '.state-operation.lock');
+    let fd;
+    try {
+        fd = openSync(guard, 'wx', 0o600);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            fail('STATE_OPERATION_BUSY');
+        throw error;
+    }
+    try {
+        writeFileSync(fd, JSON.stringify({ pid: process.pid, token: randomUUID() }));
+        return await operation();
+    }
+    finally {
+        closeSync(fd);
+        rmSync(guard, { force: true });
+    }
+}
+function manifestFor(root, items) {
+    const base = { schemaVersion: 1, kind: 'mcp-device-state-backup', createdAt: new Date().toISOString(),
+        sourceRoot: root, ...items, excluded: [...EXCLUDED] };
+    return { ...base, manifestHash: digest(base) };
+}
+function writeBundle(root, destination, items) {
+    mkdirSync(destination, { mode: 0o700 });
+    copyInventory(root, path.join(destination, 'data'), items);
+    const manifest = manifestFor(root, items);
+    writeJson(path.join(destination, 'manifest.json'), manifest);
+    return manifest;
+}
+function verifyBundle(root) {
+    sourceRoot(root);
+    const manifestPath = path.join(root, 'manifest.json');
+    noSymlinkAncestors(manifestPath);
+    if (lstatSync(manifestPath).size > 32 * 1024 * 1024)
+        fail('BACKUP_MANIFEST_TOO_LARGE');
+    const parsed = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    if (parsed.schemaVersion !== 1 || parsed.kind !== 'mcp-device-state-backup' || !Array.isArray(parsed.files) ||
+        !Array.isArray(parsed.directories) || parsed.files.length > MAX_FILES)
+        fail('INVALID_BACKUP_MANIFEST');
+    const { manifestHash, ...body } = parsed;
+    if (digest(body) !== manifestHash)
+        fail('BACKUP_MANIFEST_HASH_MISMATCH');
+    for (const file of parsed.files) {
+        relativePath(file.path);
+        if (!Number.isSafeInteger(file.bytes) || file.bytes < 0 || !Number.isSafeInteger(file.mode) || file.mode < 0 || file.mode > 0o777 ||
+            !/^[a-f0-9]{64}$/.test(file.sha256))
+            fail('INVALID_BACKUP_MANIFEST');
+    }
+    for (const directory of parsed.directories)
+        relativePath(directory);
+    const data = sourceRoot(path.join(root, 'data')), actual = inventory(data, { excludeLocks: false, rejectWal: false });
+    if (actual.sourceDigest !== parsed.sourceDigest || actual.totalBytes !== parsed.totalBytes ||
+        digest(actual.files.map(({ mode, ...file }) => file)) !== digest(parsed.files.map(({ mode, ...file }) => file)) || digest(actual.directories) !== digest(parsed.directories))
+        fail('BACKUP_CONTENT_HASH_MISMATCH');
+    const extras = readdirSync(root).filter(name => !['data', 'manifest.json'].includes(name));
+    if (extras.length)
+        fail('UNMANIFESTED_BACKUP_FILE');
+    return parsed;
+}
+export async function planStateBackup(options) {
+    const root = sourceRoot(options.sourceRoot), backupRoot = absentTarget(options.backupRoot);
+    separate(root, backupRoot);
+    await assertStopped(root);
+    return { schemaVersion: 1, kind: 'mcp-device-state-backup-plan', sourceRoot: root, backupRoot, dryRun: true, excluded: [...EXCLUDED], ...inventory(root) };
+}
+export async function createStateBackup(options) {
+    const root = sourceRoot(options.sourceRoot), backupRoot = absentTarget(options.backupRoot);
+    separate(root, backupRoot);
+    return destinationGuard(backupRoot, async () => {
+        const release = await acquireServerLease(root);
+        let stage;
+        try {
+            await assertStopped(root, true);
+            const items = inventory(root);
+            stage = stageFor(backupRoot);
+            const bundle = path.join(stage, 'bundle');
+            const manifest = writeBundle(root, bundle, items);
+            await assertStopped(root, true);
+            if (inventory(root).sourceDigest !== items.sourceDigest)
+                fail('STATE_CHANGED_DURING_BACKUP');
+            verifyBundle(bundle);
+            publish(bundle, backupRoot);
+            return { backupRoot, manifest };
+        }
+        finally {
+            if (stage)
+                rmSync(stage, { recursive: true, force: true });
+            await release();
+        }
+    });
+}
+export async function verifyStateBackup(options) {
+    const backupRoot = sourceRoot(options.backupRoot);
+    return { valid: true, backupRoot, manifest: verifyBundle(backupRoot) };
+}
+export async function restoreStateBackup(options) {
+    const backupRoot = sourceRoot(options.backupRoot), targetRoot = absentTarget(options.targetRoot);
+    separate(backupRoot, targetRoot);
+    return destinationGuard(targetRoot, async () => {
+        const manifest = verifyBundle(backupRoot);
+        const stage = stageFor(targetRoot), restored = path.join(stage, 'state');
+        try {
+            copyInventory(path.join(backupRoot, 'data'), restored, manifest);
+            if (inventory(restored, { excludeLocks: false, rejectWal: false }).sourceDigest !== manifest.sourceDigest)
+                fail('RESTORE_HASH_MISMATCH');
+            verifyBundle(backupRoot);
+            publish(restored, targetRoot);
+            return { targetRoot, files: manifest.files.length, bytes: manifest.totalBytes, sourceDigest: manifest.sourceDigest };
+        }
+        finally {
+            rmSync(stage, { recursive: true, force: true });
+        }
+    });
+}
+function collisionCheck(device, gateway) {
+    const files = new Set(device.files.map(f => f.path.toLowerCase())), dirs = new Set(device.directories.map(d => d.toLowerCase()));
+    for (const file of gateway.files)
+        if (files.has(file.path.toLowerCase()) || dirs.has(file.path.toLowerCase()))
+            fail('MIGRATION_PATH_COLLISION:' + file.path);
+    for (const directory of gateway.directories)
+        if (files.has(directory.toLowerCase()))
+            fail('MIGRATION_PATH_COLLISION:' + directory);
+}
+export async function planLegacyMigration(options) {
+    const deviceRoot = sourceRoot(options.deviceRoot), gatewayRoot = sourceRoot(options.gatewayRoot), targetRoot = absentTarget(options.targetRoot), backupRoot = absentTarget(options.backupRoot);
+    separate(deviceRoot, gatewayRoot, targetRoot, backupRoot);
+    await assertStopped(deviceRoot);
+    await assertStopped(gatewayRoot);
+    const device = inventory(deviceRoot), gateway = inventory(gatewayRoot);
+    collisionCheck(device, gateway);
+    if (!gateway.files.some(file => file.path === 'gateway.sqlite'))
+        fail('LEGACY_GATEWAY_DATABASE_REQUIRED');
+    const mappings = [
+        ...device.files.map(file => ({ source: 'device', path: file.path, targetPath: file.path })),
+        ...gateway.files.map(file => ({ source: 'gateway', path: file.path, targetPath: file.path }))
+    ];
+    const base = { schemaVersion: 1, kind: 'mcp-device-legacy-migration-plan', dryRun: options.dryRun !== false,
+        deviceRoot, gatewayRoot, targetRoot, backupRoot, device, gateway, mappings };
+    return { ...base, planHash: digest(base) };
+}
+export async function applyLegacyMigration(options) {
+    const plan = options.plan, { planHash, ...body } = plan;
+    if (plan.schemaVersion !== 1 || plan.kind !== 'mcp-device-legacy-migration-plan' || digest(body) !== planHash)
+        fail('MIGRATION_PLAN_HASH_MISMATCH');
+    const fresh = await planLegacyMigration(plan);
+    if (fresh.planHash !== plan.planHash)
+        fail('MIGRATION_PLAN_STALE');
+    return destinationGuard(plan.targetRoot, async () => destinationGuard(plan.backupRoot, async () => {
+        const releases = [];
+        let backupStage, targetStage;
+        try {
+            for (const root of [plan.deviceRoot, plan.gatewayRoot].sort())
+                releases.push(await acquireServerLease(root));
+            await assertStopped(plan.deviceRoot, true);
+            await assertStopped(plan.gatewayRoot, true);
+            const device = inventory(plan.deviceRoot), gateway = inventory(plan.gatewayRoot);
+            collisionCheck(device, gateway);
+            if (device.sourceDigest !== plan.device.sourceDigest || gateway.sourceDigest !== plan.gateway.sourceDigest)
+                fail('MIGRATION_PLAN_STALE');
+            backupStage = stageFor(plan.backupRoot);
+            const bundle = path.join(backupStage, 'backup');
+            mkdirSync(bundle, { mode: 0o700 });
+            writeBundle(plan.deviceRoot, path.join(bundle, 'device'), device);
+            writeBundle(plan.gatewayRoot, path.join(bundle, 'gateway'), gateway);
+            writeJson(path.join(bundle, 'migration-plan.json'), plan);
+            verifyBundle(path.join(bundle, 'device'));
+            verifyBundle(path.join(bundle, 'gateway'));
+            if (inventory(plan.deviceRoot).sourceDigest !== device.sourceDigest || inventory(plan.gatewayRoot).sourceDigest !== gateway.sourceDigest)
+                fail('MIGRATION_PLAN_STALE');
+            publish(bundle, plan.backupRoot);
+            targetStage = stageFor(plan.targetRoot);
+            const target = path.join(targetStage, 'state');
+            const combined = { files: [...device.files, ...gateway.files].sort((a, b) => a.path.localeCompare(b.path)),
+                directories: [...new Set([...device.directories, ...gateway.directories])].sort(),
+                totalBytes: device.totalBytes + gateway.totalBytes, sourceDigest: '' };
+            combined.sourceDigest = digest({ files: combined.files.map(({ mode, ...file }) => file), directories: combined.directories, totalBytes: combined.totalBytes });
+            mkdirSync(target, { mode: 0o700 });
+            for (const directory of combined.directories)
+                mkdirSync(path.join(target, ...directory.split('/')), { recursive: true, mode: 0o700 });
+            for (const [name, items] of [['device', device], ['gateway', gateway]])
+                for (const file of items.files) {
+                    const destination = path.join(target, ...file.path.split('/'));
+                    mkdirSync(path.dirname(destination), { recursive: true, mode: 0o700 });
+                    copyFileSync(path.join(plan.backupRoot, name, 'data', ...file.path.split('/')), destination, constants.COPYFILE_EXCL);
+                    chmodSync(destination, file.mode);
+                    flushFile(destination);
+                }
+            if (inventory(target, { excludeLocks: false, rejectWal: false }).sourceDigest !== combined.sourceDigest)
+                fail('MIGRATION_RESTORE_HASH_MISMATCH');
+            publish(target, plan.targetRoot);
+            return { targetRoot: plan.targetRoot, backupRoot: plan.backupRoot, files: combined.files.length, sourceDigest: combined.sourceDigest,
+                rollback: { deviceBackup: path.join(plan.backupRoot, 'device'), gatewayBackup: path.join(plan.backupRoot, 'gateway') } };
+        }
+        finally {
+            if (backupStage)
+                rmSync(backupStage, { recursive: true, force: true });
+            if (targetStage)
+                rmSync(targetStage, { recursive: true, force: true });
+            for (const release of releases.reverse())
+                await release();
+        }
+    }));
+}

package/dist/plugins/reference/plugin.d.ts

@@ -0,0 +1,3 @@
+import type { PluginContext, PluginInstance } from '../../platform/plugin-contract.js';
+/** Small unrelated extension used to exercise the public plugin contract. */
+export declare function createPlugin(context: PluginContext): PluginInstance;

package/dist/plugins/reference/plugin.js

@@ -0,0 +1,13 @@
+/** Small unrelated extension used to exercise the public plugin contract. */
+export function createPlugin(context) {
+    return {
+        invoke(capability, input) {
+            if (capability !== 'text.transform')
+                throw Object.assign(new Error('Unsupported capability'), { code: 'CAPABILITY_UNSUPPORTED' });
+            const value = input;
+            if (typeof value?.text !== 'string' || value.text.length > 8192)
+                throw Object.assign(new Error('text must be at most 8192 characters'), { code: 'INVALID_ARGUMENT' });
+            return { text: value.mode === 'upper' ? value.text.toUpperCase() : value.mode === 'lower' ? value.text.toLowerCase() : value.text, deviceId: context.deviceId };
+        }
+    };
+}

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

@@ -17,6 +17,7 @@ import { trackToolCall } from './utils/trackTools.js';
 import { usageTracker } from './utils/usageTracker.js';
 import { processDockerPrompt } from './utils/dockerPrompt.js';
 import { toolHistory } from './utils/toolHistory.js';
+import { observePublicInvocation, isCapturingInvocation } from './context/capture.js';
 import { handleWelcomePageOnboarding, skipWelcomePageOnboarding } from './utils/welcome-onboarding.js';
 import { VERSION } from './version.js';
 import { capture, capture_call_tool, runInUiOriginCallContext } from "./utils/capture.js";
@@ -83,7 +84,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 +97,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;
 }
 /**
@@ -1097,6 +1098,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     return handleCallToolRequest(request);
 });
 async function handleCallToolRequest(request) {
+    return observePublicInvocation({ tool: request.params.name, args: request.params.arguments }, () => executeCallToolRequest(request));
+}
+async function executeCallToolRequest(request) {
     const { name, arguments: args } = request.params;
     const startTime = Date.now();
     // Hoisted above the try so the finally block can read them when emitting the
@@ -1336,7 +1340,7 @@ async function handleCallToolRequest(request) {
             'get_recent_tool_calls',
             'track_ui_event'
         ];
-        if (!currentCallIsRemote && process.env.MCP_DEVICE_REMOTE !== 'true' && !EXCLUDED_TOOLS.includes(name)) {
+        if (!isCapturingInvocation() && !currentCallIsRemote && process.env.MCP_DEVICE_REMOTE !== 'true' && !EXCLUDED_TOOLS.includes(name)) {
             toolHistory.addCall(name, args, result, duration);
         }
         // Track success or failure based on result

package/dist/terminal-manager.d.ts

@@ -1,5 +1,6 @@
 import { TerminalSession, CommandExecutionResult, ActiveSession } from './types.js';
 interface CompletedSession {
+    executionId: string;
     pid: number;
     outputLines: string[];
     exitCode: number | null;
@@ -7,6 +8,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
@@ -31,6 +35,12 @@ export interface PaginatedOutputResult {
 export declare class TerminalManager {
     private sessions;
     private completedSessions;
+    private readonly runtimeGeneration;
+    processIdentity(pid: number): {
+        execution_id: string;
+        runtime_generation: `${string}-${string}-${string}-${string}-${string}`;
+        pid: number;
+    } | undefined;
     /**
      * Send input to a running process
      * @param pid Process ID
@@ -43,6 +53,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 +63,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