@eyeauras/insight-cli 0.1.0 → 0.2.1

package/dist/src/server.d.ts

@@ -10,6 +10,17 @@ export interface ServerBinding {
     readerSecret: string;
     publisherSecret: string;
 }
+interface LocalServer extends ServerBinding {
+    toolProcessId?: string;
+    mode: 'local';
+    instance: string;
+    port: number;
+    identityPort: number;
+    keySecret: string;
+    tokenSecret: string;
+    phase: 'seeded' | 'initialized' | 'running' | 'stopped';
+    pid?: number;
+}
 /** Own local startup; external profiles connect without taking ownership of their server. */
 export declare class GhidraServer {
     readonly directory: string;
@@ -42,3 +53,7 @@ export declare class GhidraServer {
     private identity;
     stop(): Promise<void>;
 }
+export declare function serverIdentity(local: LocalServer, c: CommandContext): Promise<Record<string, unknown>>;
+/** Stop only the authenticated owned server recorded below this workspace/probe root. */
+export declare function stopLocalServer(directory: string, c: CommandContext): Promise<void>;
+export {};

package/dist/src/server.js

@@ -1,5 +1,6 @@
+import { launchProcess, terminateProcess } from './tool-runtime/supervisor.js';
+import { runTool } from './tool-runtime/run.js';
 import { randomUUID, randomBytes, createHash } from 'node:crypto';
-import { spawn } from 'node:child_process';
 import { readFile, mkdir, open, rename, readdir, stat, chmod, realpath } from 'node:fs/promises';
 import { delimiter, dirname, join, resolve } from 'node:path';
 import { createServer } from 'node:net';
@@ -73,48 +74,19 @@ export class GhidraServer {
     async run(label, main, args, environment = {}, input, acceptedCodes = [0], timeoutMilliseconds = 120000) {
         const root = join(this.root(), 'calls', label + '-' + randomUUID());
         await mkdir(root, { recursive: true, mode: 0o700 });
-        const classes = await nativeHelpers(this.directory, this.inputs);
-        const log = await open(join(root, 'diagnostic.log'), 'a', 0o600);
-        const child = spawn(this.inputs.java, ['-Djava.awt.headless=true', '-Dghidra.home=' + this.inputs.ghidraHome,
-            ...nativeJvmDirectories(root), ...nativeExtensionArguments(this.inputs), '-cp', classes + delimiter + this.inputs.classpath, main, ...args], { cwd: root, windowsHide: true, env: { PATH: this.c.environment.PATH ?? process.env.PATH, HOME: root, TMPDIR: root, ...environment }, stdio: ['pipe', 'pipe', log.fd] });
-        const exited = new Promise((resolve, reject) => { child.once('error', reject); child.once('exit', resolve); });
-        exited.catch(() => { });
-        await log.close();
-        let output = '', overflow = false;
-        child.stdout.on('data', chunk => { if (!overflow)
-            output += chunk.toString(); if (Buffer.byteLength(output) > 1024 * 1024) {
-            overflow = true;
-            child.kill('SIGTERM');
-        } });
-        const abort = () => child.kill('SIGTERM');
-        this.c.signal.addEventListener('abort', abort, { once: true });
-        const timer = setTimeout(abort, timeoutMilliseconds);
-        const force = setTimeout(() => { if (child.exitCode === null && child.signalCode === null)
-            child.kill('SIGKILL'); }, timeoutMilliseconds + 5000);
+        const classes = await nativeHelpers(this.directory, this.inputs, this.c);
+        const output = await runTool(this.c, { tool: 'ghidra', role: label, installation: this.inputs.fingerprint, executable: this.inputs.java, arguments: ['-Djava.awt.headless=true', '-Dghidra.home=' + this.inputs.ghidraHome,
+                ...nativeJvmDirectories(root), ...nativeExtensionArguments(this.inputs), '-cp', classes + delimiter + this.inputs.classpath, main, ...args], cwd: root, environment, input, acceptedCodes, timeoutMs: timeoutMilliseconds, maxOutputBytes: 1024 * 1024 });
+        let result;
         try {
-            child.stdin.on('error', () => { });
-            child.stdin.end(input);
-            if (this.c.signal.aborted)
-                abort();
-            const code = await exited;
-            if (code === null || !acceptedCodes.includes(code) || overflow)
-                fail('authorization', 'Native server operation could not be verified; its owned diagnostic stage is retained.');
-            let result;
-            try {
-                result = object(parseDomainJson(output));
-            }
-            catch {
-                fail('malformed', 'Native server operation returned malformed content.');
-            }
-            if (result.error || result.state === 'failed')
-                fail('authorization', 'Native server operation did not establish its outcome.');
-            return result;
+            result = object(parseDomainJson(output.stdout));
         }
-        finally {
-            clearTimeout(timer);
-            clearTimeout(force);
-            this.c.signal.removeEventListener('abort', abort);
+        catch {
+            fail('malformed', 'Native server operation returned malformed content.');
         }
+        if (result.error || result.state === 'failed')
+            fail('authorization', 'Native server operation did not establish its outcome.');
+        return result;
     }
     async credentials(binding, role) {
         const url = new URL(binding.origin);
@@ -186,6 +158,10 @@ export class GhidraServer {
             await mkdir(this.root(), { recursive: true, mode: 0o700 });
             await durable(connection, { enabled: true });
         }
+        if (operation === 'stop') {
+            await this.stop();
+            return { connected: false, mode: this.c.profile.values.server ? 'external' : 'local', state: 'stopped' };
+        }
         if (operation === 'disconnect') {
             await this.stop();
             await mkdir(this.root(), { recursive: true, mode: 0o700 });
@@ -354,20 +330,21 @@ export class GhidraServer {
             await this.run('certificate', 'InsightKeytool', [keystore], { INSIGHT_KEYSTORE_PASSWORD: await this.c.secrets.require(local.keySecret) });
             await chmod(keystore, 0o600);
         }
-        const classes = await nativeHelpers(this.directory, this.inputs);
+        const classes = await nativeHelpers(this.directory, this.inputs, this.c);
         const processRoot = join(root, 'processes', randomUUID());
         await mkdir(processRoot, { recursive: true, mode: 0o700 });
         const log = await open(join(processRoot, 'runtime.log'), 'a', 0o600);
-        const child = spawn(this.inputs.java, ['-Djava.awt.headless=true', '-Dghidra.home=' + this.inputs.ghidraHome,
+        const child = await launchProcess(this.c.appArguments.AppDataDirectory, { tool: 'ghidra', role: 'server', installation: this.inputs.fingerprint, metadata: { serverDirectory: this.directory } }, this.inputs.java, ['-Djava.awt.headless=true', '-Dghidra.home=' + this.inputs.ghidraHome,
             ...nativeJvmDirectories(processRoot), '-cp', classes + delimiter + (this.inputs.serverClasspath ?? this.inputs.classpath),
             'InsightServerMain', data, String(local.port), String(local.identityPort), local.instance, keystore], { cwd: processRoot, detached: true, windowsHide: true, env: { PATH: this.c.environment.PATH ?? process.env.PATH, HOME: processRoot, TMPDIR: processRoot,
-                INSIGHT_KEYSTORE_PASSWORD: await this.c.secrets.require(local.keySecret), INSIGHT_SERVER_TOKEN: await this.c.secrets.require(local.tokenSecret) }, stdio: ['ignore', log.fd, log.fd] });
+                INSIGHT_KEYSTORE_PASSWORD: await this.c.secrets.require(local.keySecret), INSIGHT_SERVER_TOKEN: await this.c.secrets.require(local.tokenSecret) }, stdio: ['ignore', log.fd, log.fd] }, { signal: this.c.signal });
         child.on('error', () => { });
         child.unref();
         await log.close();
         if (!child.pid)
             fail('launch', 'Owned local Ghidra server could not be started.');
         this.state.child = child;
+        local.toolProcessId = child.toolProcessId;
         local.pid = child.pid;
         local.phase = 'running';
         await durable(saved, local);
@@ -394,62 +371,66 @@ export class GhidraServer {
             throw error;
         }
     }
-    async identity(local) {
-        const token = await this.c.secrets.require(local.tokenSecret);
-        const response = await this.c.fetch(`http://127.0.0.1:${local.identityPort}/identity`, { redirect: 'error',
-            signal: AbortSignal.timeout(1000), headers: { Authorization: 'Bearer ' + token } });
-        if (!response.ok || Number(response.headers.get('content-length')) > 4096)
-            fail('binding', 'Owned server identity was not verified.');
-        const reader = response.body?.getReader();
-        if (!reader)
-            fail('binding', 'Owned server identity has no body.');
-        const chunks = [];
-        let size = 0;
-        try {
-            for (;;) {
-                const next = await reader.read();
-                if (next.done)
-                    break;
-                size += next.value.byteLength;
-                if (size > 4096)
-                    fail('binding', 'Owned server identity exceeded its bound.');
-                chunks.push(next.value);
-            }
-        }
-        finally {
-            await reader.cancel().catch(() => { });
+    identity(local) { return serverIdentity(local, this.c); }
+    async stop() { await stopLocalServer(this.directory, this.c); this.state.child = undefined; this.state.initializing = undefined; }
+}
+export async function serverIdentity(local, c) {
+    const token = await c.secrets.require(local.tokenSecret);
+    const response = await c.fetch(`http://127.0.0.1:${local.identityPort}/identity`, { redirect: 'error',
+        signal: AbortSignal.timeout(1000), headers: { Authorization: 'Bearer ' + token } });
+    if (!response.ok || Number(response.headers.get('content-length')) > 4096)
+        fail('binding', 'Owned server identity was not verified.');
+    const reader = response.body?.getReader();
+    if (!reader)
+        fail('binding', 'Owned server identity has no body.');
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const next = await reader.read();
+            if (next.done)
+                break;
+            size += next.value.byteLength;
+            if (size > 4096)
+                fail('binding', 'Owned server identity exceeded its bound.');
+            chunks.push(next.value);
         }
-        const value = Buffer.concat(chunks).toString('utf8');
-        const result = object(JSON.parse(value));
-        if (result.instance !== local.instance || result.port !== local.port || !Number.isSafeInteger(result.pid) || Number(result.pid) < 1 ||
-            local.pid !== undefined && result.pid !== local.pid)
-            fail('binding', 'Server endpoint no longer belongs to the recorded owned process.');
-        return result;
     }
-    async stop() {
-        let local;
-        try {
-            local = JSON.parse(await readFile(join(this.root(), 'local.json'), 'utf8'));
-        }
-        catch (error) {
-            if (error.code === 'ENOENT')
-                return;
-            throw error;
-        }
-        if (!local.pid)
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+    const value = Buffer.concat(chunks).toString('utf8');
+    const result = object(JSON.parse(value));
+    if (result.instance !== local.instance || result.port !== local.port || !Number.isSafeInteger(result.pid) || Number(result.pid) < 1 ||
+        local.pid !== undefined && result.pid !== local.pid)
+        fail('binding', 'Server endpoint no longer belongs to the recorded owned process.');
+    return result;
+}
+/** Stop only the authenticated owned server recorded below this workspace/probe root. */
+export async function stopLocalServer(directory, c) {
+    let local;
+    try {
+        local = JSON.parse(await readFile(join(directory, 'server', 'local.json'), 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
             return;
-        if (live(local.pid)) {
-            await this.identity(local);
+        throw error;
+    }
+    if (!local.pid)
+        return;
+    if (live(local.pid)) {
+        await serverIdentity(local, c);
+        if (local.toolProcessId)
+            await terminateProcess(c.appArguments.AppDataDirectory, local.toolProcessId, false, async (r) => Number((await serverIdentity(local, c)).pid) === r.pid);
+        else
             process.kill(local.pid, 'SIGTERM');
-            for (let i = 0; i < 100 && live(local.pid); i++)
-                await delay(50);
-            if (live(local.pid))
-                fail('busy', 'Owned server did not stop; its receipt is retained.');
-        }
-        local.phase = 'stopped';
-        delete local.pid;
-        await durable(join(this.root(), 'local.json'), local);
-        this.state.child = undefined;
-        this.state.initializing = undefined;
+        for (let i = 0; i < 100 && live(local.pid); i++)
+            await delay(50);
+        if (live(local.pid))
+            fail('busy', 'Owned server did not stop; its receipt is retained.');
     }
+    local.phase = 'stopped';
+    delete local.pid;
+    await durable(join(directory, 'server', 'local.json'), local);
 }

package/dist/src/sevenzip.d.ts

@@ -0,0 +1,15 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import { ToolInstaller } from './tool-runtime/installer.js';
+import type { Workspace } from './workspace.js';
+export interface ArchiveEntry {
+    path: string;
+    directory: boolean;
+    size: number;
+    encrypted: boolean;
+    attributes: string;
+}
+/** Technical listing is bounded, not a general line-escaping format. Extraction never trusts native paths. */
+export declare function parseArchiveListing(content: string): ArchiveEntry[];
+export declare function safeArchivePath(path: string): string;
+export declare function sevenzipInstaller(c: CommandContext): ToolInstaller;
+export declare function sevenzipCommands(workspace: (c: CommandContext) => Workspace): CommandDefinition[];

package/dist/src/sevenzip.js

@@ -0,0 +1,119 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { join, resolve, dirname } from 'node:path';
+import { mkdir, lstat } from 'node:fs/promises';
+import { ToolInstaller } from './tool-runtime/installer.js';
+import { defineTool, lifecycleCommands } from './tool-runtime/definition.js';
+import { catalogArtifact } from './tool-runtime/catalog.js';
+import { runTool } from './tool-runtime/run.js';
+import { fail, text, id } from './model.js';
+import { number } from './research.js';
+const archiveSha = '7bb52641f2e0dc9b8f5b180be4b0ab46b6d3127361a4e817938175603850c714';
+/** Technical listing is bounded, not a general line-escaping format. Extraction never trusts native paths. */
+export function parseArchiveListing(content) {
+    const entries = [];
+    for (const block of content.replaceAll('\r\n', '\n').trim().split(/\n\n+/)) {
+        if (!block)
+            continue;
+        const fields = new Map();
+        for (const line of block.split('\n')) {
+            const at = line.indexOf(' = ');
+            if (at < 1)
+                fail('unsupported', 'Archive listing contains a multiline or unsupported field.');
+            const key = line.slice(0, at);
+            if (fields.has(key))
+                fail('unsupported', 'Archive listing contains ambiguous fields.');
+            fields.set(key, line.slice(at + 3));
+        }
+        if (['Symbolic Link', 'Hard Link', 'Reparse'].some(key => fields.has(key)))
+            fail('unsupported', 'Archive links are not supported for ordinary-file recovery.');
+        const path = fields.get('Path'), size = Number(fields.get('Size'));
+        if (!path || !Number.isSafeInteger(size) || size < 0 || !['+', '-'].includes(fields.get('Folder') ?? ''))
+            fail('unsupported', 'Archive entry omitted its path, size or kind.');
+        if (entries.length >= 10000)
+            fail('limit', 'Archive inventory exceeds 10000 entries.');
+        entries.push({ path, size, directory: fields.get('Folder') === '+', encrypted: fields.get('Encrypted') === '+', attributes: fields.get('Attributes') ?? '' });
+    }
+    return entries;
+}
+export function safeArchivePath(path) {
+    if (!path || /[\\\x00-\x1f\x7f:]/.test(path) || path.startsWith('/') || path.split('/').some(p => !p || p === '.' || p === '..') || path.length > 2048)
+        fail('invalid', 'Archive entry has an unsafe or unsupported output path.');
+    return path;
+}
+export function sevenzipInstaller(c) {
+    return new ToolInstaller(c, { id: 'sevenzip', primary: 'sevenzip', components: () => {
+            if (process.platform !== 'darwin' || !['arm64', 'x64'].includes(process.arch))
+                fail('unsupported', 'Managed 7-Zip is currently provided for macOS ARM64/x64; select an external 7zz 26.04 on another host.');
+            return { sevenzip: catalogArtifact(archiveSha) };
+        }, launch: roots => ({ executable: join(roots.sevenzip, '7zz'), arguments: [], environment: {} }),
+        probe: async (launch, context) => {
+            const r = await runTool(context, { tool: 'sevenzip', role: 'version', executable: launch.executable, arguments: [...launch.arguments, 'i'], environment: launch.environment, maxOutputBytes: 65536, timeoutMs: 30000 });
+            if (!/7-Zip \(z\) 26\.04 /.test(r.stdout))
+                fail('configuration', 'The selected executable must provide 7zz 26.04.');
+            return { version: '26.04' };
+        } });
+}
+export function sevenzipCommands(workspace) {
+    const definition = defineTool({ id: 'sevenzip', description: 'Inventory, verify and recover files from containers', components: [{ id: 'sevenzip', version: '26.04', artifacts: [] }], lifecycle: {
+            download: (o, c) => sevenzipInstaller(c).download(Boolean(o.offline)), install: (o, c) => sevenzipInstaller(c).install(o), uninstall: (o, c) => sevenzipInstaller(c).uninstall(Boolean(o.purgeCache)), doctor: (_o, c) => sevenzipInstaller(c).doctor(), status: (_o, c) => sevenzipInstaller(c).status()
+        } });
+    const common = [{ flags: '--target <id>', description: 'Reuse an immutable input target' }, { flags: '--timeout-seconds <seconds>', description: 'Per-process deadline (1–600)', defaultValue: 120 }];
+    const operation = (name) => command(name + ' [input]', name === 'list' ? 'Inspect a bounded archive inventory' : name === 'test' ? 'Check container integrity without extracting' : 'Recover regular files into a new ordinary directory', async ({ args, options: o }, c) => {
+        if (Boolean(args.input) === Boolean(o.target))
+            fail('invalid', 'Supply exactly one input path or --target.');
+        const w = workspace(c), target = args.input ? await w.importTarget(resolve(c.cwd, text(args.input, 4096))) : w.target(id(o.target));
+        const input = await w.artifacts.verify(target.input), timeoutMs = number(o.timeoutSeconds, 600, 1) * 1000;
+        return sevenzipInstaller(c).use(async (selected) => {
+            const invoke = (role, parameters, extra = {}) => runTool(c, { tool: 'sevenzip', role, installation: selected.id, executable: selected.executable, arguments: [...selected.arguments, ...parameters], environment: selected.environment, target: target.id, timeoutMs, ...extra });
+            if (name === 'test') {
+                const result = await invoke('test', ['t', '-bd', '-y', '-p', '--', input]);
+                return { state: 'verified', target: target.id, inputSha256: target.binarySha256, process: result.process, elapsedMs: result.elapsedMs, diagnostics: result.diagnostics, content: result.stdout };
+            }
+            const listing = await invoke('inventory', ['l', '-slt', '-ba', '-sccUTF-8', '-p', '--', input]);
+            const entries = parseArchiveListing(listing.stdout);
+            const base = { target: target.id, inputSha256: target.binarySha256, process: listing.process, diagnostics: listing.diagnostics, total: entries.length };
+            if (name === 'list') {
+                const limit = number(o.limit, 100, 1), offset = number(o.offset, 10000, 0);
+                return { ...base, items: entries.slice(offset, offset + limit), limit, offset, truncated: offset + limit < entries.length };
+            }
+            const chosen = o.entry ? entries.filter(e => e.path === text(o.entry, 2048)) : entries;
+            if (!chosen.length)
+                fail('notFound', 'No matching archive entry.');
+            if (chosen.length > 512)
+                fail('limit', 'Select an entry; bulk recovery is limited to 512 entries.');
+            const paths = new Set();
+            let bytes = 0;
+            for (const entry of chosen) {
+                safeArchivePath(entry.path);
+                const key = entry.path.normalize('NFC').toLowerCase();
+                if (paths.has(key))
+                    fail('unsupported', 'Archive output paths collide.');
+                paths.add(key);
+                if (entry.encrypted)
+                    fail('unsupported', 'Encrypted recovery is not supported by this adapter.');
+                if (entry.size > 64 * 1024 ** 2 || (bytes += entry.size) > 256 * 1024 ** 2)
+                    fail('limit', 'Recovery exceeds its 64-MiB per-file/256-MiB total bound.');
+                if (/(?:^|\s)[bclps][rwx-]{9}/.test(entry.attributes))
+                    fail('unsupported', 'Only ordinary archive files and directories can be recovered.');
+            }
+            const output = resolve(c.cwd, text(o.output, 4096));
+            await mkdir(dirname(output), { recursive: true, mode: 0o700 });
+            await mkdir(output, { mode: 0o700 });
+            const files = [];
+            for (const entry of chosen) {
+                const destination = join(output, entry.path);
+                if (entry.directory) {
+                    await mkdir(destination, { recursive: true, mode: 0o700 });
+                    continue;
+                }
+                await mkdir(dirname(destination), { recursive: true, mode: 0o700 });
+                const result = await invoke('recover', ['x', '-so', '-spd', '-bd', '-y', '-p', '--', input, entry.path], { maxOutputBytes: Math.max(65536, entry.size + 65536), outputFile: destination });
+                if ((await lstat(destination)).size !== entry.size)
+                    fail('binding', 'Recovered file size differs from the inventory; retained partial output requires inspection.');
+                files.push({ path: entry.path, size: entry.size, process: result.process });
+            }
+            return { ...base, state: 'extracted', outputDirectory: output, files, bytes, publication: 'ordinary files; no shared analysis merge' };
+        });
+    }, { permission: Permission.Update, options: [...common, ...(name === 'list' ? [{ flags: '--limit <count>', description: 'Page size (1–100)', defaultValue: 50 }, { flags: '--offset <count>', description: 'Skip entries', defaultValue: 0 }] : name === 'extract' ? [{ flags: '--entry <path>', description: 'Recover one exact regular entry' }, { flags: '--output <directory>', description: 'New output directory', required: true }] : [])] });
+    return [command('sevenzip', definition.description, [...lifecycleCommands(definition), operation('list'), operation('test'), operation('extract')])];
+}

package/dist/src/strace.d.ts

@@ -0,0 +1,10 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import { ToolInstaller } from './tool-runtime/installer.js';
+import type { Workspace } from './workspace.js';
+export declare function straceInstaller(c: CommandContext): ToolInstaller;
+export declare function stracePlan(o: Record<string, unknown>): {
+    events: string[];
+    arguments: string[];
+    programArguments: string[];
+};
+export declare function straceCommands(workspace: (c: CommandContext) => Workspace): CommandDefinition[];

package/dist/src/strace.js

@@ -0,0 +1,71 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { dirname, join, resolve } from 'node:path';
+import { mkdir, writeFile, open, copyFile, chmod } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { ToolInstaller } from './tool-runtime/installer.js';
+import { defineTool, lifecycleCommands } from './tool-runtime/definition.js';
+import { catalogArtifact } from './tool-runtime/catalog.js';
+import { runTool } from './tool-runtime/run.js';
+import { fileSha256 } from './tool-runtime/archives.js';
+import { fail, text, id } from './model.js';
+import { number } from './research.js';
+// Exact binary from the reviewed reproducible Linux source build.
+const archiveSha = '3f01b360952f9c81dee07b640916115f937685df6d3004f5a3227cb0582d8ca3';
+function supported() { if (process.platform !== 'linux' || process.arch !== 'x64')
+    fail('unsupported', 'The strace facade requires Linux x64, glibc 2.35+ and permission to trace its owned child.'); }
+export function straceInstaller(c) {
+    return new ToolInstaller(c, { id: 'strace', primary: 'strace', components: () => { supported(); return { strace: catalogArtifact(archiveSha) }; }, launch: roots => ({ executable: join(roots.strace, 'bin/strace'), arguments: [], environment: {} }), probe: async (launch, context) => {
+            supported();
+            const r = await runTool(context, { tool: 'strace', role: 'version', executable: launch.executable, arguments: ['--version'], maxOutputBytes: 65536, timeoutMs: 10000, nativeDeadline: true });
+            if (!/strace -- version 7\.2\b/.test(r.stdout + '\n' + r.stderr))
+                fail('configuration', 'Select strace 7.2 with --kill-on-exit support.');
+            return { version: '7.2', ownedChildOnly: true, killOnExit: true, kernelOwnerDeadline: true };
+        } });
+}
+export function stracePlan(o) {
+    const requested = text(o.events ?? 'file,process,io', 128).split(','), groups = { file: '%file', process: '%process', network: '%network', io: 'read,write,readv,writev' };
+    if (!requested.length || requested.length > 4 || requested.some(x => !groups[x]) || new Set(requested).size !== requested.length)
+        fail('invalid', '--events must contain unique file, process, network or io categories.');
+    const args = o.arg === undefined ? [] : Array.isArray(o.arg) ? o.arg : [o.arg];
+    if (args.length > 64)
+        fail('limit', 'At most 64 literal program arguments are supported.');
+    return { events: requested, arguments: ['--kill-on-exit', '-f', '-yy', '-s', String(number(o.stringBytes ?? 128, 1024, 1)), '-e', 'trace=' + requested.map(x => groups[x]).join(','), ...(o.path ? ['-P', resolve(text(o.path, 4096))] : [])], programArguments: args.map(v => text(v, 4096)) };
+}
+export function straceCommands(workspace) {
+    const definition = defineTool({ id: 'strace', description: 'Observe file, process, I/O and network syscalls in an owned native Linux launch', components: [{ id: 'strace', version: '7.2', artifacts: [] }], lifecycle: { download: (o, c) => straceInstaller(c).download(Boolean(o.offline)), install: (o, c) => straceInstaller(c).install(o), uninstall: (o, c) => straceInstaller(c).uninstall(Boolean(o.purgeCache)), doctor: (_o, c) => straceInstaller(c).doctor(), status: (_o, c) => straceInstaller(c).status() } });
+    return [command('strace', definition.description, [...lifecycleCommands(definition), command('trace [input]', 'Run an authorized owned ELF copy and retain bounded syscall observations', async ({ args, options: o }, c) => {
+                supported();
+                if (Boolean(args.input) === Boolean(o.target))
+                    fail('invalid', 'Supply exactly one executable input or --target.');
+                if (o.path)
+                    o = { ...o, path: resolve(c.cwd, text(o.path, 4096)) };
+                const plan = stracePlan(o), limit = number(o.limit ?? 200, 1000, 1), offset = number(o.offset ?? 0, 1000000), timeoutMs = number(o.timeoutSeconds ?? 30, 600, 1) * 1000;
+                const w = workspace(c), target = args.input ? await w.importTarget(resolve(c.cwd, text(args.input, 4096))) : w.target(id(o.target)), input = await w.artifacts.verify(target.input), header = Buffer.alloc(64), handle = await open(input, 'r');
+                try {
+                    const { bytesRead } = await handle.read(header, 0, 64, 0);
+                    if (bytesRead < 64 || header.subarray(0, 4).toString('hex') !== '7f454c46' || header[4] !== 2 || header[5] !== 1 || header.readUInt16LE(18) !== 62)
+                        fail('unsupported', 'An owned launch requires a native little-endian x64 ELF executable.');
+                }
+                finally {
+                    await handle.close();
+                }
+                const directory = join(c.appArguments.AppDataDirectory, 'runtime/strace/subjects', randomUUID()), subject = join(directory, 'subject');
+                await mkdir(directory, { recursive: true, mode: 0o700 });
+                await copyFile(input, subject, constants.COPYFILE_EXCL);
+                await chmod(subject, 0o700);
+                if (await fileSha256(subject) !== target.binarySha256)
+                    fail('binding', 'Owned ELF bytes differ from the immutable target.');
+                return straceInstaller(c).use(async (selected) => {
+                    const result = await runTool(c, { tool: 'strace', role: 'trace', installation: selected.id, executable: selected.executable, arguments: [...plan.arguments, '--', subject, ...plan.programArguments], cwd: c.cwd, target: target.id, timeoutMs, nativeDeadline: true, metadata: { inputSha256: target.binarySha256, events: plan.events } }), lines = result.stderr.trimEnd().split(/\r?\n/);
+                    const base = { state: 'completed', target: target.id, inputSha256: target.binarySha256, process: result.process, elapsedMs: result.elapsedMs, diagnostics: result.diagnostics, events: plan.events, programStdout: result.stdout, coverage: 'Observed syscalls from one owned launch and its traced descendants. Native trace and program stderr share the stderr stream. Strings and category/path filters are bounded; unobserved operations are unknown. Application side effects require authorization; adjacent executable sidecars are not copied.' };
+                    if (o.output) {
+                        const output = resolve(c.cwd, text(o.output, 4096)), content = JSON.stringify({ ...base, lines }, null, 2) + '\n';
+                        await mkdir(dirname(output), { recursive: true, mode: 0o700 });
+                        await writeFile(output, content, { flag: 'wx', mode: 0o600 });
+                        return { ...base, output, bytes: Buffer.byteLength(content), totalLines: lines.length };
+                    }
+                    return { ...base, lines: lines.slice(offset, offset + limit), offset, limit, totalLines: lines.length, truncated: offset + limit < lines.length };
+                });
+            }, { permission: Permission.Update, options: [{ flags: '--target <id>', description: 'Reuse an immutable captured native ELF' }, { flags: '--arg <literal...>', description: 'Literal arguments, without shell expansion' }, { flags: '--events <categories>', description: 'Comma-separated file, process, io or network', defaultValue: 'file,process,io' }, { flags: '--path <path>', description: 'Optional literal path filter; combines with selected categories' }, { flags: '--string-bytes <bytes>', description: 'Maximum native string bytes (1–1024)', defaultValue: 128 }, { flags: '--output <file>', description: 'Save bounded trace and program stdout to a new ordinary JSON file' }, { flags: '--limit <count>', description: 'Maximum trace lines (1–1000)', defaultValue: 200 }, { flags: '--offset <count>', description: 'Skip trace lines', defaultValue: 0 }, { flags: '--timeout-seconds <seconds>', description: 'Owned launch deadline (1–600)', defaultValue: 30 }] })])];
+}

package/dist/src/text-window.d.ts

@@ -0,0 +1,11 @@
+/** Public text coordinates are Unicode code points, never native bytes or UTF-16 halves. */
+export declare function textWindow(source: string, limit: number, offset: number, sourceTruncated?: boolean): {
+    content: string;
+    textSha256: string;
+    totalCharacters: number;
+    limit: number;
+    offset: number;
+    sourceTruncated: boolean;
+    truncated: boolean;
+    coordinates: string;
+};

package/dist/src/text-window.js

@@ -0,0 +1,6 @@
+import { createHash } from 'node:crypto';
+/** Public text coordinates are Unicode code points, never native bytes or UTF-16 halves. */
+export function textWindow(source, limit, offset, sourceTruncated = false) {
+    const characters = Array.from(source);
+    return { content: characters.slice(offset, offset + limit).join(''), textSha256: createHash('sha256').update(source).digest('hex'), totalCharacters: characters.length, limit, offset, sourceTruncated, truncated: sourceTruncated || offset + limit < characters.length, coordinates: 'Unicode characters in the returned native text; hash binds that text, which may itself be a truncated prefix' };
+}

package/dist/src/tool-runtime/archives.d.ts

@@ -0,0 +1,10 @@
+import type { ToolArtifact } from './definition.js';
+export declare function fileSha256(path: string, signal?: AbortSignal): Promise<string>;
+export declare function archiveName(name: string): string;
+export declare function extractArchive(file: string, destination: string, format: 'tgz' | 'zip', signal?: AbortSignal): Promise<void>;
+export declare function cacheArtifact(artifact: ToolArtifact, cache: string, fetcher: typeof fetch, signal: AbortSignal, offline?: boolean, vendorDirect?: boolean): Promise<string>;
+/** Consume local input once; extraction never races later edits to the caller's archive. */
+export declare function consumeArchive(path: string, cache: string, artifact: ToolArtifact, checksum?: string, signal?: AbortSignal): Promise<{
+    path: string;
+    artifact: ToolArtifact;
+}>;