@eyeauras/insight-cli 0.1.0 → 0.2.1

package/dist/src/toolbox.d.ts

@@ -0,0 +1,84 @@
+import { type CommandDefinition } from '@eyeauras/cli-factory';
+interface PackagedSkill {
+    name: string;
+    title: string;
+    path: string;
+    resources: Record<string, string>;
+}
+interface Capability {
+    id: string;
+    namespace: string;
+    kind: 'analytical' | 'supporting' | 'capability';
+    skill: string;
+    purpose: string;
+    evaluationCase: {
+        id: string;
+        inputFamily: string;
+        task: string;
+        modes: string[];
+        requiredObservations: string[];
+    };
+    inputs: string[];
+    tasks: string[];
+    platforms: string[];
+    dependencies: string[];
+    workflowCommands: string[];
+    limitations: string[];
+}
+export interface Toolbox {
+    schema: 1;
+    skills: PackagedSkill[];
+    tools: Capability[];
+}
+export declare const toolbox: Toolbox;
+export declare function locateSkill(name?: string): {
+    version: string;
+    name: string;
+    bundlePath: string;
+    path: string;
+    skills: string[];
+};
+export declare function describeTool(id: string): {
+    status: string;
+    version: string;
+    skill: {
+        version: string;
+        name: string;
+        bundlePath: string;
+        path: string;
+        skills: string[];
+    };
+    runtime: {
+        required: boolean;
+        providedByNamespace: string;
+        dependencies: string[];
+        readiness?: undefined;
+        statusCommand?: undefined;
+    } | {
+        required: boolean;
+        readiness: string;
+        statusCommand: string[];
+        providedByNamespace?: undefined;
+        dependencies?: undefined;
+    };
+    id: string;
+    namespace: string;
+    kind: "analytical" | "supporting" | "capability";
+    purpose: string;
+    evaluationCase: {
+        id: string;
+        inputFamily: string;
+        task: string;
+        modes: string[];
+        requiredObservations: string[];
+    };
+    inputs: string[];
+    tasks: string[];
+    platforms: string[];
+    dependencies: string[];
+    workflowCommands: string[];
+    limitations: string[];
+};
+export declare function skillCommand(): CommandDefinition;
+export declare function toolboxCommands(): CommandDefinition[];
+export {};

package/dist/src/toolbox.js

@@ -0,0 +1,35 @@
+import { localCommand, CliError, tableView, recordView } from '@eyeauras/cli-factory';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { packageVersion } from './package-version.js';
+const packageRoot = new URL('../../', import.meta.url);
+export const toolbox = JSON.parse(readFileSync(new URL('runtime/toolbox.json', packageRoot), 'utf8'));
+export function locateSkill(name = 'insight-cli') {
+    const skill = toolbox.skills.find(s => s.name === name);
+    if (!skill)
+        throw new CliError(`Unknown skill '${name}'.`, { code: 'toolbox.skillNotFound', next: [['tools', 'list']] });
+    return { version: packageVersion, name, bundlePath: fileURLToPath(new URL('skill-bundle', packageRoot)), path: fileURLToPath(new URL(skill.path, packageRoot)), skills: toolbox.skills.map(s => s.name) };
+}
+export function describeTool(id) {
+    const tool = toolbox.tools.find(t => t.id === id);
+    if (!tool)
+        throw new CliError(`Unknown tool '${id}'.`, { code: 'toolbox.notFound', next: [['tools', 'list']] });
+    return { ...tool, status: 'available', version: packageVersion, skill: locateSkill(tool.skill),
+        runtime: tool.kind !== 'analytical' ? { required: false, providedByNamespace: tool.namespace, dependencies: tool.dependencies } : { required: true, readiness: 'notChecked', statusCommand: ['insight-cli', tool.namespace, 'status', '--json'] } };
+}
+export function skillCommand() {
+    return localCommand('skill [name]', 'Locate packaged tool instructions', ({ args }) => locateSkill(args.name === undefined ? undefined : String(args.name)), {
+        view: recordView({ fields: [{ label: 'Skill', value: x => x.name }, { label: 'Version', value: x => x.version }, { label: 'Path', value: x => x.path }] })
+    });
+}
+export function toolboxCommands() {
+    return [
+        localCommand('list', 'List shipped research capabilities', () => ({ version: packageVersion, items: toolbox.tools.map(t => ({ id: t.id, namespace: t.namespace, kind: t.kind, purpose: t.purpose, inputs: t.inputs, tasks: t.tasks, platforms: t.platforms, skill: t.skill, status: 'available' })) }), {
+            view: tableView({ rows: x => x.items, columns: [{ header: 'Tool', value: x => x.id }, { header: 'Purpose', value: x => x.purpose }, { header: 'Skill', value: x => x.skill }] })
+        }),
+        localCommand('show <tool>', 'Describe tasks and tool preparation', ({ args }) => describeTool(String(args.tool)), {
+            view: recordView({ fields: [{ label: 'Tool', value: x => x.id }, { label: 'Purpose', value: x => x.purpose }, { label: 'Kind', value: x => x.kind }, { label: 'Platforms', value: x => x.platforms.join(', ') }, { label: 'Dependencies', value: x => x.dependencies.join(', ') || 'none' }, { label: 'Skill', value: x => x.skill.path }],
+                sections: [{ title: () => 'Tasks', lines: x => x.tasks }, { title: () => 'Limitations', lines: x => x.limitations }], next: x => [['skill', x.skill.name]] })
+        }),
+    ];
+}

package/dist/src/tshark.d.ts

@@ -0,0 +1,23 @@
+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 tsharkInstaller(c: CommandContext): ToolInstaller;
+export type PacketFields = Record<string, string[]>;
+export declare function tsharkRows(value: string): PacketFields[];
+export declare function tsharkStreams(rows: PacketFields[]): {
+    frames: number[];
+    sources: string[];
+    destinations: string[];
+    transport: string;
+    stream: number;
+}[];
+export declare function tsharkFollow(output: string, transport: string, stream: number): {
+    nodes: string[];
+    chunks: {
+        node: number;
+        hex: string;
+        bytes: number;
+    }[];
+    totalBytes: number;
+};
+export declare function tsharkCommands(workspace: (c: CommandContext) => Workspace): CommandDefinition[];

package/dist/src/tshark.js

@@ -0,0 +1,174 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { join, resolve, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readFile, mkdir, copyFile, lstat, open, writeFile } 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 { fileSha256, archiveName } from './tool-runtime/archives.js';
+import { runTool } from './tool-runtime/run.js';
+import { digest, fail, id, text } from './model.js';
+import { number } from './research.js';
+const archive = '90a4f106033c74eef38f52985fc168c99a293ae35c9d3d7d1b157558a94d5261', relativeExecutable = 'Wireshark.app/Contents/MacOS/tshark';
+const layout = JSON.parse(await readFile(fileURLToPath(new URL('../../runtime/native/tshark-layout.json', import.meta.url)), 'utf8'));
+function supported() { if (process.platform !== 'darwin' || process.arch !== 'arm64')
+    fail('unsupported', 'TShark currently requires native macOS ARM64, macOS 14+ for the owned deadline launcher. Offline PCAP analysis requires no live-capture privileges.'); }
+function externalRoot(executable) { if (basename(executable) !== 'tshark' || basename(dirname(executable)) !== 'MacOS' || basename(resolve(dirname(executable), '../..')) !== 'Wireshark.app')
+    fail('configuration', 'Select the pinned Wireshark.app/Contents/MacOS/tshark or our extracted console runtime.'); return resolve(dirname(executable), '../../..'); }
+async function verifyFamily(executable) { supported(); const root = externalRoot(executable); for (const entry of layout.entries) {
+    archiveName(entry.path);
+    const path = join(root, entry.path), info = await lstat(path);
+    if (!info.isFile() || info.size !== entry.size || await fileSha256(path) !== entry.sha256)
+        fail('binding', 'TShark runtime family differs from the pinned 4.6.9 console subset.', { component: entry.path });
+} return { runtimeFamily: digest(layout.entries) }; }
+const safeArguments = ['-n', '-o', 'capture.no_extcap:TRUE', '-o', 'nameres.maxmind_geoip:FALSE'];
+export function tsharkInstaller(c) { return new ToolInstaller(c, { id: 'tshark', primary: 'tshark', preparationId: 'console-subset-v1', components: () => { supported(); return { tshark: catalogArtifact(archive) }; }, launch: roots => ({ executable: join(roots.tshark, relativeExecutable), arguments: [], environment: {} }), externalInputs: verifyFamily, prepareExternal: async (executable, stage) => { const root = externalRoot(executable), owned = join(stage, 'execution'); for (const entry of layout.entries) {
+        const target = join(owned, entry.path);
+        await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+        await copyFile(join(root, entry.path), target, constants.COPYFILE_EXCL);
+        if (await fileSha256(target) !== entry.sha256)
+            fail('binding', 'Copied TShark runtime differs.');
+    } return { executable: join(owned, relativeExecutable), arguments: [], environment: {} }; }, probe: async (launch, context) => { supported(); const result = await runTool(context, { tool: 'tshark', role: 'version', executable: launch.executable, arguments: ['--version'], maxOutputBytes: 65536, timeoutMs: 10000, nativeDeadline: true }); if (!/^TShark \(Wireshark\) 4\.6\.9\b/.test(result.stdout))
+        fail('configuration', 'Select TShark 4.6.9.'); return { version: '4.6.9', offlineCaptureOnly: true, privateSettings: true, consoleSubset: true, systemCaptureHelperRequired: false }; } }); }
+const fields = ['frame.number', 'frame.time_epoch', 'frame.len', 'frame.protocols', 'ip.src', 'ip.dst', 'ipv6.src', 'ipv6.dst', 'tcp.srcport', 'tcp.dstport', 'tcp.stream', 'udp.srcport', 'udp.dstport', 'udp.stream', '_ws.col.Protocol', 'http.request.method', 'http.request.full_uri', 'http.request.uri', 'http.response.code', 'dns.qry.name', 'tls.handshake.extensions_server_name'];
+export function tsharkRows(value) { let rows; try {
+    rows = JSON.parse(value);
+}
+catch {
+    fail('partial', 'TShark did not return a complete bounded JSON document.');
+} if (!Array.isArray(rows) || rows.length > 10001)
+    fail('partial', 'Unexpected bounded packet inventory.'); return rows.map(row => { const layers = row?._source?.layers; if (!layers || typeof layers !== 'object' || Array.isArray(layers))
+    fail('partial', 'Packet fields are unavailable.'); for (const [key, values] of Object.entries(layers)) {
+    if (key.length > 256 || !Array.isArray(values) || values.length > 65536 || values.some(v => typeof v !== 'string' || v.length > 65536))
+        fail('partial', 'Packet fields exceed their typed bounds.');
+} if (!/^\d+$/.test(layers['frame.number']?.[0] ?? ''))
+    fail('partial', 'Packet has no frame identity.'); return layers; }); }
+export function tsharkStreams(rows) { const streams = new Map(); for (const row of rows)
+    for (const transport of ['tcp', 'udp'])
+        for (const value of row[transport + '.stream'] ?? []) {
+            if (!/^\d+$/.test(value))
+                fail('partial', 'Invalid native stream identity.');
+            const key = transport + ':' + value, stream = streams.get(key) ?? { transport, stream: Number(value), frames: [], sources: new Set(), destinations: new Set() };
+            stream.frames.push(Number(row['frame.number'][0]));
+            for (const ip of [...(row['ip.src'] ?? []), ...(row['ipv6.src'] ?? [])])
+                stream.sources.add(ip);
+            for (const ip of [...(row['ip.dst'] ?? []), ...(row['ipv6.dst'] ?? [])])
+                stream.destinations.add(ip);
+            streams.set(key, stream);
+        } return [...streams.values()].map(v => ({ ...v, frames: [...new Set(v.frames)], sources: [...v.sources], destinations: [...v.destinations] })); }
+export function tsharkFollow(output, transport, stream) { const lines = output.trim().split(/\r?\n/), nodes = [], chunks = []; if (!lines.includes('Follow: ' + transport + ',raw') || !lines.includes('Filter: ' + transport + '.stream eq ' + stream))
+    fail('partial', 'Follow output does not match the selected native stream.'); for (const line of lines) {
+    const node = /^Node ([01]): (.*)$/.exec(line);
+    if (node) {
+        nodes[Number(node[1])] = node[2];
+        continue;
+    }
+    if (/^\t?[0-9a-f]+$/i.test(line)) {
+        const hex = line.trim();
+        if (hex.length % 2)
+            fail('partial', 'Follow output has an incomplete byte.');
+        chunks.push({ node: line.startsWith('\t') ? 1 : 0, hex, bytes: hex.length / 2 });
+    }
+} if (nodes.length !== 2)
+    fail('partial', 'Follow output has no endpoint pair.'); return { nodes, chunks, totalBytes: chunks.reduce((n, v) => n + v.bytes, 0) }; }
+export function tsharkCommands(workspace) {
+    const definition = defineTool({ id: 'tshark', description: 'Inspect an immutable offline capture, packet fields and reconstructed TCP/UDP streams', components: [{ id: 'tshark', version: '4.6.9', artifacts: [] }], lifecycle: { download: (o, c) => tsharkInstaller(c).download(Boolean(o.offline)), install: (o, c) => tsharkInstaller(c).install(o), status: (_o, c) => tsharkInstaller(c).status(), doctor: (_o, c) => tsharkInstaller(c).doctor(), uninstall: (o, c) => tsharkInstaller(c).uninstall(Boolean(o.purgeCache)) } });
+    return [command('tshark', definition.description, [...lifecycleCommands(definition), command('inspect [input]', 'Read bounded protocol evidence from a captured PCAP/PCAPNG', async ({ args, options: o }, c) => {
+                supported();
+                if (Boolean(args.input) === Boolean(o.target))
+                    fail('invalid', 'Supply one PCAP path or --target.');
+                const view = text(o.view ?? 'overview', 32);
+                if (!['overview', 'packets', 'packet', 'streams', 'follow'].includes(view))
+                    fail('invalid', 'Use overview, packets, packet, streams or follow.');
+                const limit = number(o.limit ?? 50, 1000, 1), offset = number(o.offset ?? 0, 1000000), frame = o.frame === undefined ? undefined : number(o.frame, 1000000, 1), filter = o.filter === undefined ? undefined : text(o.filter, 4096);
+                if ((view === 'packet') !== (frame !== undefined))
+                    fail('invalid', 'Only packet view requires --frame.');
+                if ((o.stream !== undefined || o.transport !== undefined) !== (view === 'follow'))
+                    fail('invalid', 'Only follow view requires --stream and --transport.');
+                if (view === 'packet' && filter)
+                    fail('invalid', 'Packet detail uses its exact --frame without a display filter.');
+                if (view === 'follow' && (o.stream === undefined || o.transport === undefined || filter))
+                    fail('invalid', 'Follow requires --stream and --transport, without --filter.');
+                const transport = view === 'follow' ? text(o.transport, 8) : undefined, stream = view === 'follow' ? number(o.stream, 1000000) : undefined;
+                if (transport && !['tcp', 'udp'].includes(transport))
+                    fail('invalid', 'Follow transport must be tcp or udp.');
+                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);
+                if (target.input.size > 64 * 1024 ** 2)
+                    fail('limit', 'Capture input exceeds 64 MiB.');
+                const file = await open(input, 'r'), header = Buffer.alloc(4);
+                try {
+                    await file.read(header, 0, 4, 0);
+                }
+                finally {
+                    await file.close();
+                }
+                if (!['d4c3b2a1', 'a1b2c3d4', '4d3cb2a1', 'a1b23c4d', '0a0d0d0a'].includes(header.toString('hex')))
+                    fail('unsupported', 'Input is not a PCAP/PCAPNG capture.');
+                const directory = join(c.appArguments.AppDataDirectory, 'runtime/tshark/queries', randomUUID()), home = join(directory, 'home');
+                await mkdir(home, { recursive: true, mode: 0o700 });
+                return tsharkInstaller(c).use(async (selected) => {
+                    const runs = [], run = async (arguments_, maxOutputBytes = 16 * 1024 ** 2, acceptedCodes = [0]) => { const r = await runTool(c, { tool: 'tshark', role: view, installation: selected.id, executable: selected.executable, arguments: [...safeArguments, '-r', input, ...arguments_], environment: { HOME: home, XDG_CONFIG_HOME: join(home, 'config'), XDG_DATA_HOME: join(home, 'data'), WIRESHARK_CONFIG_DIR: join(home, 'config/wireshark') }, target: target.id, nativeDeadline: true, timeoutMs: 60000, maxOutputBytes, acceptedCodes, metadata: { inputSha256: target.binarySha256, view } }); runs.push({ process: r.process, diagnostics: r.diagnostics, elapsedMs: r.elapsedMs, exitCode: r.exitCode, stderr: r.stderr }); return r; };
+                    let data, total, items, complete = true, scannedFrames;
+                    if (view === 'packet') {
+                        const r = await run(['-c', String(frame), '-Y', 'frame.number == ' + frame, '-T', 'json', '--no-duplicate-keys']);
+                        try {
+                            data = JSON.parse(r.stdout);
+                        }
+                        catch {
+                            fail('partial', 'Native packet detail is incomplete.', { diagnostics: r.diagnostics });
+                        }
+                        if (!Array.isArray(data) || data.length > 1)
+                            fail('partial', 'Packet detail did not preserve one frame identity.');
+                        if (!data.length)
+                            fail('notFound', 'Selected packet was not found before the capture ended.');
+                    }
+                    else {
+                        const r = await run(['-c', '10001', '-T', 'json', '--no-duplicate-keys', ...fields.flatMap(f => ['-e', f])], 16 * 1024 ** 2, [0, 2]), observed = tsharkRows(r.stdout);
+                        complete = r.exitCode === 0 && observed.length < 10001;
+                        const rows = observed.slice(0, 10000);
+                        scannedFrames = rows.length;
+                        let selectedRows = rows;
+                        if (filter) {
+                            const f = await run(['-c', '10000', '-Y', filter, '-T', 'fields', '-e', 'frame.number'], 1024 ** 2), matches = f.stdout.trim() ? f.stdout.trim().split(/\r?\n/) : [];
+                            if (matches.some(v => !/^\d+$/.test(v)))
+                                fail('partial', 'Filtered native frame identities are invalid.');
+                            const ids = new Set(matches);
+                            selectedRows = rows.filter(p => ids.has(p['frame.number'][0]));
+                        }
+                        if (view === 'follow') {
+                            if (!tsharkStreams(rows).some(s => s.transport === transport && s.stream === stream))
+                                fail(complete ? 'notFound' : 'partial', 'Selected stream is absent from the inspected capture prefix; no follow is fabricated.');
+                            const followed = await run(['-c', '10000', '-q', '-z', 'follow,' + transport + ',raw,' + stream], 2 * 1024 ** 2, [0, 2]);
+                            complete &&= followed.exitCode === 0;
+                            data = tsharkFollow(followed.stdout, transport, stream);
+                        }
+                        else if (view === 'packets')
+                            items = selectedRows;
+                        else if (view === 'streams')
+                            items = tsharkStreams(selectedRows);
+                        else {
+                            const protocols = {};
+                            for (const row of selectedRows) {
+                                const protocol = row['_ws.col.protocol']?.[0] ?? 'unknown';
+                                protocols[protocol] = (protocols[protocol] ?? 0) + 1;
+                            }
+                            data = { matchingFrames: selectedRows.length, protocols, streams: tsharkStreams(selectedRows).length, firstFrame: selectedRows[0]?.['frame.number']?.[0], lastFrame: selectedRows.at(-1)?.['frame.number']?.[0] };
+                        }
+                    }
+                    if (await fileSha256(input) !== target.binarySha256)
+                        fail('binding', 'Immutable capture changed during inspection.');
+                    if (items)
+                        total = items.length;
+                    const base = { state: complete ? 'completed' : 'partial', complete, target: target.id, inputSha256: target.binarySha256, view, filter, scannedFrames, coverage: view === 'packet' ? 'One selected frame; packet existence is verified, whole-capture coverage is not claimed.' : complete ? 'All frames reached EOF in the bounded inventory; native protocol evidence is limited by packet content and dissector behavior.' : 'Only the first 10000 frames or a readable prefix were inspected; later packets, missing streams and absent matches remain unknown.', runs, diagnostics: directory };
+                    if (o.output) {
+                        const output = resolve(c.cwd, text(o.output, 4096)), content = JSON.stringify({ ...base, ...(items ? { items, total } : { data }) }, 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), total };
+                    }
+                    return { ...base, ...(items ? { items: items.slice(offset, offset + limit), total, limit, offset, truncated: offset + limit < items.length } : { data }) };
+                });
+            }, { permission: Permission.Update, options: [{ flags: '--target <id>', description: 'Reuse an immutable captured PCAP' }, { flags: '--view <kind>', description: 'overview, packets, packet, streams or follow', defaultValue: 'overview' }, { flags: '--filter <expression>', description: 'Native Wireshark display filter within the inspected prefix' }, { flags: '--frame <number>', description: 'Required for packet view; decimal frame number, up to one million' }, { flags: '--transport <kind>', description: 'Required for follow: tcp or udp' }, { flags: '--stream <index>', description: 'Required for follow: zero-based native stream ID' }, { flags: '--limit <count>', description: 'Return up to 1000 packet/stream rows', defaultValue: 50 }, { flags: '--offset <count>', description: 'Skip matching rows after filtering', defaultValue: 0 }, { flags: '--output <file>', description: 'Save the complete bounded view to a new ordinary JSON file' }] })])];
+}

package/dist/src/windbg.d.ts

@@ -0,0 +1,14 @@
+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 windbgInstaller(c: CommandContext): ToolInstaller;
+export declare function windbgPlan(o: Record<string, unknown>, nonce: string): {
+    view: "modules" | "registers" | "memory" | "threads" | "overview" | "stack" | "disassembly";
+    commands: string;
+};
+export declare function windbgSnapshot(stdout: string, nonce: string): {
+    lines: string[];
+    complete: boolean;
+    warnings: string[];
+};
+export declare function windbgCommands(workspace: (c: CommandContext) => Workspace): CommandDefinition[];

package/dist/src/windbg.js

@@ -0,0 +1,119 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { basename, dirname, join, resolve } from 'node:path';
+import { mkdir, writeFile, open, copyFile, readdir, rm } 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, extractArchive } from './tool-runtime/archives.js';
+import { treeFingerprint } from './tool-runtime/store.js';
+import { fail, text, id } from './model.js';
+import { number } from './research.js';
+const bundleSha = '4662ae17bc0dc77db987b89cccea32c30058baa06268f861d09e0ab4e4f45c20';
+function supported() { if (process.platform !== 'win32' || process.arch !== 'x64')
+    fail('unsupported', 'This WinDbg facade requires Windows x64. It inspects Windows user-mode minidumps without launching or attaching their original process.'); }
+export function windbgInstaller(c) {
+    return new ToolInstaller(c, { id: 'windbg', primary: 'windbg', components: () => { supported(); return { windbg: catalogArtifact(bundleSha) }; }, prepare: async (roots, context) => {
+            const root = roots.windbg, inner = join(root, 'windbg_win-x64.msix');
+            if (await fileSha256(inner, context.signal) !== '959c4ec033e2d00f7ed75646e4d352cc7cff6de33f494fd5dccb83819fe64e7a')
+                fail('binding', 'WinDbg x64 nested package differs from the pinned distribution.');
+            await extractArchive(inner, join(root, 'payload'), 'zip', context.signal);
+            for (const name of await readdir(root))
+                if (name.endsWith('.msix'))
+                    await rm(join(root, name));
+        }, launch: roots => ({ executable: join(roots.windbg, 'payload/amd64/cdb.exe'), arguments: [], environment: {} }), externalInputs: async (executable) => {
+            supported();
+            if (basename(executable).toLowerCase() !== 'cdb.exe')
+                fail('configuration', 'Select the WinDbg bundle amd64/cdb.exe console executable.');
+            const root = dirname(executable);
+            for (const name of ['dbgeng.dll', 'dbghelp.dll', 'dbgmodel.dll'])
+                await fileSha256(join(root, name));
+            return { consoleFamily: await treeFingerprint(root) };
+        }, probe: async (launch, context) => { supported(); const r = await runTool(context, { tool: 'windbg', role: 'version', executable: launch.executable, arguments: ['-version'], maxOutputBytes: 65536, timeoutMs: 15000, nativeDeadline: true }); if (!/\b(?:cdb(?:\.exe)?|debugger)\s+(?:version\s+)?10\.[0-9.]+/i.test(r.stdout + '\n' + r.stderr))
+            fail('configuration', 'Select a compatible Microsoft CDB 10.x console debugger with its adjacent runtime.', { nativeVersion: (r.stdout + '\n' + r.stderr).trim(), diagnostics: r.diagnostics }); return { packageVersion: '1.2610.1001.0', consoleVersion: (r.stdout + '\n' + r.stderr).trim(), ownedJob: true, mode: 'read-only-user-minidump' }; } });
+}
+export function windbgPlan(o, nonce) {
+    const view = text(o.view ?? 'overview', 32), commands = [];
+    if (o.thread !== undefined)
+        commands.push('~' + number(o.thread, 65535) + 's');
+    switch (view) {
+        case 'overview':
+            commands.push('vertarget', '~', 'kp 0n' + number(o.frames ?? 32, 128, 1), 'r', 'lm');
+            break;
+        case 'stack':
+            commands.push('kp 0n' + number(o.frames ?? 32, 128, 1));
+            break;
+        case 'threads':
+            commands.push('~');
+            break;
+        case 'registers':
+            commands.push('r');
+            break;
+        case 'modules':
+            commands.push('lm');
+            break;
+        case 'memory':
+        case 'disassembly': {
+            const address = text(o.address, 32);
+            if (!/^0x[0-9a-fA-F]{1,16}$/.test(address))
+                fail('invalid', 'A hexadecimal runtime --address is required.');
+            const count = number(o.count ?? (view === 'memory' ? 64 : 16), view === 'memory' ? 4096 : 256, 1);
+            commands.push((view === 'memory' ? 'db ' : 'u ') + address + ' L0x' + count.toString(16));
+            break;
+        }
+        default: fail('invalid', 'Choose overview, stack, threads, registers, modules, memory or disassembly.');
+    }
+    if (!['memory', 'disassembly'].includes(view) && (o.address !== undefined || o.count !== undefined))
+        fail('invalid', '--address and --count require memory or disassembly.');
+    if (!['stack', 'overview'].includes(view) && o.frames !== undefined)
+        fail('invalid', '--frames requires stack or overview.');
+    return { view, commands: ['.echo INSIGHT_BEGIN_' + nonce, ...commands, '.echo INSIGHT_END_' + nonce, 'q'].join('; ') };
+}
+export function windbgSnapshot(stdout, nonce) {
+    const output = stdout.split(/\r?\n/), start = output.findIndex(line => line.trim() === 'INSIGHT_BEGIN_' + nonce), end = output.findIndex((line, index) => index > start && line.trim() === 'INSIGHT_END_' + nonce);
+    if (start < 0 || end < 0)
+        fail('partial', 'CDB did not complete the selected dump query; inspect retained diagnostics.');
+    const lines = output.slice(start + 1, end);
+    const diagnostics = stdout.split(/\r?\n/).filter(line => /error|warning|unable to|could not|not found|couldn't|memory access|\?{4,}|syntax error|invalid thread/i.test(line));
+    return { lines, complete: diagnostics.length === 0, warnings: diagnostics.slice(0, 100) };
+}
+export function windbgCommands(workspace) {
+    const definition = defineTool({ id: 'windbg', description: 'Inspect Windows native user-mode dump stacks, registers, modules and memory', vendorDirect: true, components: [{ id: 'windbg', version: '1.2610.1001.0', artifacts: [] }], lifecycle: { download: (o, c) => windbgInstaller(c).download(Boolean(o.offline), Boolean(o.vendorDirect)), install: (o, c) => windbgInstaller(c).install(o), uninstall: (o, c) => windbgInstaller(c).uninstall(Boolean(o.purgeCache)), doctor: (_o, c) => windbgInstaller(c).doctor(), status: (_o, c) => windbgInstaller(c).status() } });
+    return [command('windbg', definition.description, [...lifecycleCommands(definition), command('inspect [input]', 'Read a captured Windows minidump with bounded typed debugger queries', async ({ args, options: o }, c) => {
+                supported();
+                if (Boolean(args.input) === Boolean(o.target))
+                    fail('invalid', 'Supply exactly one dump path or --target.');
+                const nonce = randomUUID().replaceAll('-', ''), plan = windbgPlan(o, nonce), 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(32), handle = await open(input, 'r');
+                try {
+                    const { bytesRead } = await handle.read(header, 0, 32, 0);
+                    if (bytesRead < 32 || header.subarray(0, 4).toString('ascii') !== 'MDMP')
+                        fail('unsupported', 'WinDbg inspect requires a Windows user-mode minidump (MDMP).');
+                }
+                finally {
+                    await handle.close();
+                }
+                const directory = join(c.appArguments.AppDataDirectory, 'runtime/windbg/queries', randomUUID()), symbolDirectory = join(directory, 'symbols');
+                await mkdir(symbolDirectory, { recursive: true, mode: 0o700 });
+                const symbols = o.symbols ? await w.artifacts.capture(resolve(c.cwd, text(o.symbols, 4096)), 'input') : undefined;
+                if (symbols) {
+                    const name = basename(text(o.symbols, 4096));
+                    if (!/^[a-zA-Z0-9_. -]+\.pdb$/i.test(name))
+                        fail('invalid', 'Symbol companion must have an ordinary .pdb filename.');
+                    await copyFile(await w.artifacts.verify(symbols), join(symbolDirectory, name), constants.COPYFILE_EXCL);
+                }
+                return windbgInstaller(c).use(async (selected) => {
+                    const result = await runTool(c, { tool: 'windbg', role: 'inspect', installation: selected.id, executable: selected.executable, arguments: ['-sins', '-noshell', '-nosqm', '-netsyms:no', '-failinc', '-y', symbolDirectory, '-z', input, '-c', plan.commands], cwd: directory, target: target.id, timeoutMs, nativeDeadline: true, metadata: { dumpSha256: target.binarySha256, view: plan.view, ...(symbols ? { symbolsSha256: symbols.sha256 } : {}) } }), snapshot = windbgSnapshot(result.stdout, nonce);
+                    const base = { state: snapshot.complete ? 'completed' : 'partial', complete: snapshot.complete, target: target.id, inputSha256: target.binarySha256, ...(symbols ? { symbolsSha256: symbols.sha256 } : {}), view: plan.view, process: result.process, elapsedMs: result.elapsedMs, diagnostics: result.diagnostics, stderr: result.stderr, warnings: snapshot.warnings, coverage: 'Read-only dump observation. Runtime addresses and thread indices belong to this dump; missing memory or symbols are unknown. Local matching PDB only; no symbol server. No original process is launched or attached.' };
+                    if (o.output) {
+                        const output = resolve(c.cwd, text(o.output, 4096)), content = JSON.stringify({ ...base, lines: snapshot.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: snapshot.lines.length };
+                    }
+                    return { ...base, lines: snapshot.lines.slice(offset, offset + limit), offset, limit, totalLines: snapshot.lines.length, truncated: offset + limit < snapshot.lines.length };
+                });
+            }, { permission: Permission.Update, options: [{ flags: '--target <id>', description: 'Reuse a captured minidump target' }, { flags: '--view <kind>', description: 'overview, stack, threads, registers, modules, memory or disassembly', defaultValue: 'overview' }, { flags: '--thread <index>', description: 'Dump thread index (decimal)' }, { flags: '--frames <count>', description: 'Stack frames (1–128)' }, { flags: '--address <hex>', description: 'Required runtime 0x address for memory/disassembly' }, { flags: '--count <count>', description: 'Memory bytes (1–4096) or instructions (1–256)' }, { flags: '--symbols <file>', description: 'Capture a matching local PDB companion; network symbols are disabled' }, { flags: '--output <file>', description: 'Save the full bounded result to a new ordinary JSON file' }, { flags: '--limit <count>', description: 'Maximum native lines (1–1000)', defaultValue: 200 }, { flags: '--offset <count>', description: 'Skip native output lines', defaultValue: 0 }, { flags: '--timeout-seconds <seconds>', description: 'Owned debugger deadline (1–600)', defaultValue: 30 }] })])];
+}

package/dist/src/workspace.d.ts

@@ -138,6 +138,7 @@ export declare class Workspace {
     sessions(limit?: number, offset?: number): ResearchSession[];
     model(target: string): GhidraModel;
     context(scope: Scope): GhidraContext;
+    contextById(context: string): GhidraContext;
     contexts(session: string, limit?: number, offset?: number): GhidraContext[];
     private existingRequest;
     private insertRequest;

package/dist/src/workspace.js

@@ -183,6 +183,12 @@ export class Workspace {
             fail('notFound', 'No Ghidra context exists for this session and target; open it first.');
         return JSON.parse(String(row.data));
     }
+    contextById(context) {
+        const row = this.db.prepare('SELECT data FROM contexts WHERE id=?').get(id(context));
+        if (!row)
+            fail('notFound', 'Tool context was not found.');
+        return JSON.parse(String(row.data));
+    }
     contexts(session, limit = 100, offset = 0) {
         this.session(session);
         page(limit, offset);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eyeauras/insight-cli",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "Agent-facing durable sessions and isolated Ghidra research contexts",
   "main": "./dist/src/index.js",
@@ -13,19 +13,22 @@
     "dist/src",
     "SKILL.md",
     "skills",
+    "skill-bundle",
     "references",
     "runtime",
     "LICENSE",
     ".cli-package-build.json"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json && node ../../scripts/prepare-package.mjs",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json && node ../../scripts/prepare-package.mjs",
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@eyeauras/cli-factory": "0.4.1",
+    "@eyeauras/cli-factory": "https://raw.githubusercontent.com/iXab3r/insight-cli/73459aecc88da6f878988b64f71ab72b34a83c45/vendor/factory-core-74e7a64.tgz",
+    "@eyeauras/cli-factory-ipc": "https://raw.githubusercontent.com/iXab3r/insight-cli/f47f6d14e8aadc6b6778a6e3627bbb08909521d2/vendor/factory-ipc-7c403d8.tgz",
     "@modelcontextprotocol/sdk": "1.32.1",
-    "@eyeauras/cli-factory-ipc": "https://raw.githubusercontent.com/iXab3r/insight-cli/43f815a006711418bcffa47a7d99ef5c42424ca5/vendor/factory-ipc-a2094fb.tgz"
+    "tar": "7.5.22",
+    "yauzl": "3.4.0"
   },
   "engines": {
     "node": ">=24"

package/references/administration.md

@@ -22,7 +22,8 @@ changing that project stays blocked; read-only inspection remains available. Par
 export output does not prove success and is preserved. Retain receipts for continuation.
 
 `ghidra server` operates on the configured local or external server. `status` reports connection
-state; `connect` enables shared operations; `disconnect` releases the owned local server or the
+state, including a missing runtime before installation; `start/stop` manage the owned local
+server (stop requires closed contexts). `connect` enables shared operations; `disconnect` releases the owned local server or the
 external connection. Reconnect preserves repositories. Repository/file/history/checkout commands
 require the explicit repository and relevant path. Admin actions require actual server authority
 alongside Factory permissions. Changing ACLs preserves other users and anonymous access.

package/references/agent-execution.md

@@ -0,0 +1,36 @@
+# Agent host execution permissions
+
+Keep the user/project host policy and the selected profile. A sandbox can deny writes
+to runtime AppData or access to the local IPC endpoint, including during local help.
+This is a host execution boundary, not evidence that the tool or its inputs are absent.
+
+First retry only `insight-cli --help`, `tools list`, `skill`, or the selected application's
+read-only `status` using the host's normal permission escalation. In Codex, use the
+execution tool's `sandbox_permissions: "require_escalated"` with a scoped explanation
+that the installed CLI needs its existing profile storage/local IPC. Automatic approval
+review or the user decides that request; do not disable the sandbox or approval policy.
+
+Do not work around this by changing HOME/AppData/profile paths, creating another host,
+deleting owner/endpoint files, killing unrelated processes or claiming a missing runtime.
+After the read-only probe succeeds, use the approved execution route for the intended
+public CLI commands. An access refusal explicitly stating **no command was sent** is
+known not dispatched; it is safe to submit that authorized command through the approved
+route. This includes a mutation refused before dispatch. Do not mistake that definite
+pre-dispatch refusal for an unknown execution outcome. Downloads still require their explicit
+network access.
+
+A lost mutation response is different from a denied startup probe: inspect retained
+request/status/recovery evidence and use its request ID when supported. Never blindly
+repeat a publication, script or program run whose outcome is unknown. External-tool
+fallback is allowed by project rules, but record that the intended facade was not used
+and do not invent a successful checkpoint or native result.
+
+## Wait for the original execution
+
+A tool operation may outlast the host execution tool's initial wait. A returned running
+session/cell ID means that command is still in progress, not that the CLI returned no data.
+Use the host's session poll/wait facility until terminal exit and consume stdout/stderr
+before issuing a dependent command. In Codex, an `exec_command` session is continued with
+`write_stdin`; a yielded execution cell uses that host's cell wait. Do not launch a second
+open/install or repeat a CPU action just because the first chunk was empty. If the execution
+really loses its terminal result, use the CLI's request/status recovery as described above.