@eyeauras/insight-cli 0.0.0-stage → 0.1.0

package/dist/src/sync-policy.d.ts

@@ -0,0 +1,22 @@
+import { type CommandDefinition, type CommandContext } from '@eyeauras/cli-factory';
+import { Research } from './research.js';
+import { Workspace, type Scope, type SyncPolicy } from './workspace.js';
+export declare const manualPolicy: SyncPolicy;
+export declare function syncPolicy(value: unknown): SyncPolicy;
+export declare class Synchronization {
+    readonly workspace: Workspace;
+    readonly research: Research;
+    private readonly authorize;
+    constructor(workspace: Workspace, research: Research, authorize?: () => Promise<void>);
+    get(selected: Scope): {
+        publish: "manual" | "after-edit" | "after-save";
+        refresh: "manual" | "before-edit";
+        session: string;
+        target: string;
+    };
+    set(selected: Scope, policy: SyncPolicy, callerId?: string): Promise<unknown>;
+    /** The outer command queue spans refresh, the durable local intent and publication. Inner
+     * research queues remain unchanged, including their cross-context ordering and shared lane. */
+    execute(selected: Scope, path: string, input: Record<string, unknown>, run: (requestId: string) => Promise<unknown>): Promise<unknown>;
+}
+export declare function synchronizationCommands(service: (c: CommandContext) => Synchronization): CommandDefinition[];

package/dist/src/sync-policy.js

@@ -0,0 +1,123 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { scope } from './research.js';
+import { fail, id, object, text } from './model.js';
+import { selectedOptions } from './arguments.js';
+export const manualPolicy = { publish: 'manual', refresh: 'manual' };
+export function syncPolicy(value) {
+    const p = object(value);
+    if (Object.keys(p).some(k => !['publish', 'refresh'].includes(k)) || !['manual', 'after-edit', 'after-save'].includes(String(p.publish)) || !['manual', 'before-edit'].includes(String(p.refresh)))
+        fail('invalid', 'Policy requires publish manual/after-edit/after-save and refresh manual/before-edit.');
+    return { publish: p.publish, refresh: p.refresh };
+}
+export class Synchronization {
+    workspace;
+    research;
+    authorize;
+    constructor(workspace, research, authorize = async () => { }) {
+        this.workspace = workspace;
+        this.research = research;
+        this.authorize = authorize;
+    }
+    get(selected) { return { ...selected, ...(this.workspace.context(selected).syncPolicy ?? manualPolicy) }; }
+    async set(selected, policy, callerId) {
+        const reserved = this.workspace.reserveRequest(selected, 'ghidra.sync-policy.set', policy, callerId);
+        return this.research.ordered(selected, async () => {
+            const request = this.workspace.request(reserved.request.id);
+            if (reserved.replay && request.state === 'applied')
+                return request.result;
+            if (request.state !== 'accepted')
+                fail('unknown', 'Policy change has a retained outcome.');
+            if (this.workspace.unresolved(selected).length)
+                fail('blocked', 'Reconcile the context outcome before changing its synchronization policy.');
+            const current = this.workspace.context(selected), result = { ...selected, state: 'configured', ...policy };
+            this.workspace.startRequest(request.id);
+            this.workspace.completeSavedRequest(selected, request.id, current.generation, { syncPolicy: policy }, result);
+            return result;
+        });
+    }
+    /** The outer command queue spans refresh, the durable local intent and publication. Inner
+     * research queues remain unchanged, including their cross-context ordering and shared lane. */
+    async execute(selected, path, input, run) {
+        const configured = this.workspace.context(selected).syncPolicy ?? manualPolicy;
+        const caller = input.requestId === undefined ? undefined : id(input.requestId);
+        const previous = caller ? this.workspace.administrationByCaller(caller) : undefined;
+        if (!previous && (configured.publish === 'manual' && configured.refresh === 'manual' || input.requestId !== undefined && this.workspace.requestByCaller(id(input.requestId))))
+            return run(input.requestId === undefined ? '' : id(input.requestId));
+        if (previous && previous.operation !== 'ghidra.automatic')
+            fail('idempotency', 'Request ID already identifies another profile administration operation.');
+        const policy = previous ? syncPolicy(object(object(previous.intent).parameters).policy) : configured;
+        const reserved = this.workspace.reserveAdministration('ghidra.automatic', { ...selected, path, input, policy }, caller);
+        const request = this.workspace.administration(reserved.request.id), requestId = 'auto-local-' + request.id;
+        if (reserved.replay && request.state === 'applied')
+            return request.result;
+        if (reserved.replay && request.state === 'failed')
+            fail(String(object(request.result ?? {}).failureCode ?? 'coordinator.conflict').replace(/^coordinator\./, ''), 'This automatic workflow retains its original failed result.', request.result);
+        if (policy.refresh === 'before-edit' && path !== 'ghidra save' || policy.publish === 'after-edit' || policy.publish === 'after-save' && path === 'ghidra save')
+            await this.authorize();
+        let progress = object(request.result ?? { phase: 'accepted' });
+        const remember = (patch) => { progress = { ...progress, ...patch }; this.workspace.administrationState(request.id, 'unknown', progress); };
+        try {
+            // Re-entering a dispatched local command always uses its original request identity.
+            // A lost merge reply is reconciled by merge itself; no check-in is re-dispatched.
+            if (progress.phase === 'accepted' && policy.refresh === 'before-edit' && path !== 'ghidra save') {
+                remember({ phase: 'refresh' });
+                const incoming = object(await this.research.refresh(selected, 'auto-refresh-' + request.id));
+                remember({ incoming, phase: 'ready' });
+                if (incoming.state === 'conflict') {
+                    const result = { ...selected, state: 'conflict', phase: 'refresh', localApplied: false, automatic: { refresh: incoming } };
+                    this.workspace.administrationState(request.id, 'failed', result);
+                    fail('conflict', 'Automatic refresh retained conflicts; the requested edit was not started.', result);
+                }
+            }
+            else if (progress.phase === 'refresh') {
+                // Refresh's candidate/context commit is already durable or explicitly unresolved.
+                const incoming = object(await this.research.refresh(selected, 'auto-refresh-' + request.id));
+                remember({ incoming, phase: 'ready' });
+                if (incoming.state === 'conflict')
+                    fail('conflict', 'Automatic refresh retained conflicts; the edit was not started.', { ...selected, state: 'conflict', localApplied: false, automatic: { refresh: incoming } });
+            }
+            let local = progress.local === undefined ? undefined : object(progress.local);
+            if (!local) {
+                remember({ phase: 'local' });
+                local = object(await run(requestId));
+                if (!['applied', 'saved', 'preview'].includes(String(local.state)))
+                    fail('unknown', 'The local command has no verified saved acknowledgment.', local);
+                remember({ local, phase: 'saved' });
+            }
+            const automatic = { ...(progress.incoming ? { refresh: progress.incoming } : {}) };
+            const publish = (policy.publish === 'after-save' && path === 'ghidra save' || policy.publish === 'after-edit') &&
+                (path === 'ghidra save' || local.sharedState === 'pending') && Number(local.pendingChanges) > 0;
+            if (publish) {
+                remember({ phase: 'publish' });
+                automatic.publication = await this.research.merge(selected, 'auto-merge-' + request.id);
+            }
+            const current = this.workspace.context(selected), result = { ...local, pendingChanges: current.scalars.length + current.complexChanges.length,
+                ...(local.sharedState !== undefined ? { sharedState: current.scalars.length || current.complexChanges.length ? 'pending' : 'shared' } : {}), automatic };
+            this.workspace.administrationState(request.id, 'applied', result);
+            return result;
+        }
+        catch (error) {
+            if (this.workspace.administration(request.id).state === 'failed')
+                throw error;
+            const code = String(error.code ?? 'coordinator.unknown'), detail = error.result, child = this.workspace.requestByCaller(requestId);
+            const notStarted = progress.phase === 'local' && (!child || child.state === 'accepted'), rejected = progress.phase === 'local' && child?.state === 'failed' && object(child.result ?? {}).state === 'rejected';
+            const knownRejection = rejected || notStarted && code.endsWith('.invalid');
+            // Retain the local acknowledgment alongside a failed/uncertain publication. Its caller
+            // can distinguish successful editing from a publication that needs intervention.
+            const result = { ...selected, state: code.endsWith('.conflict') ? 'conflict' : knownRejection ? 'rejected' : 'unknown', failureCode: code, phase: progress.phase,
+                ...(progress.local ? { localApplied: true, local: progress.local } : notStarted || rejected ? { localApplied: false } : { localOutcome: progress.phase === 'local' ? 'unknown' : 'not_started' }), automatic: { ...(progress.incoming ? { refresh: progress.incoming } : {}), ...(detail ? { outcome: detail } : {}) } };
+            if (code.endsWith('.conflict') || knownRejection)
+                this.workspace.administrationState(request.id, 'failed', result);
+            else
+                this.workspace.administrationState(request.id, 'unknown', { ...progress, outcome: result });
+            fail(code.endsWith('.conflict') ? 'conflict' : knownRejection ? code.replace(/^coordinator\./, '') : 'unknown', 'Automatic synchronization did not complete; retained local effects are not replayed.', result);
+        }
+    }
+}
+export function synchronizationCommands(service) {
+    return [command('sync-policy', 'Configure opt-in synchronization for one saved tool context', [
+            command('get', 'Read the persisted policy; default is manual', ({ options: o }, c) => service(c).get(scope(o)), { permission: Permission.ReadOnly, options: selectedOptions }),
+            command('set', 'Choose manual, publication after edit/save and optional refresh before edit', ({ options: o }, c) => service(c).set(scope(o), syncPolicy({ publish: text(o.publish), refresh: text(o.refresh) }), o.requestId === undefined ? undefined : id(o.requestId)), { permission: Permission.Update, options: [...selectedOptions,
+                    { flags: '--publish <mode>', description: 'manual, after-edit or after-save', required: true }, { flags: '--refresh <mode>', description: 'manual or before-edit', required: true }, { flags: '--request-id <id>', description: 'Retrieve the recorded policy change' }] }),
+        ])];
+}

package/dist/src/transport.d.ts

@@ -0,0 +1,23 @@
+export interface Descriptor {
+    path: string;
+    method: string;
+    params: {
+        name: string;
+        source: string;
+    }[];
+}
+/** The pinned GhidraMCP HTTP side of a dedicated bridge. No discovery by project name. */
+export declare class HttpBridge {
+    readonly endpoint: string;
+    private fetch;
+    private signal?;
+    private token?;
+    private timeoutMilliseconds?;
+    private schema?;
+    constructor(endpoint: string, fetch?: typeof globalThis.fetch, signal?: AbortSignal | undefined, token?: string | undefined, timeoutMilliseconds?: number | undefined);
+    private request;
+    instance(): Promise<Record<string, unknown>>;
+    descriptor(path: string): Promise<Descriptor>;
+    call(path: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+export declare function decodeMcp(result: unknown): unknown;

package/dist/src/transport.js

@@ -0,0 +1,135 @@
+import { fail, object } from './model.js';
+import { parseDomainJson } from './json.js';
+import { CliError } from '@eyeauras/cli-factory';
+/** The pinned GhidraMCP HTTP side of a dedicated bridge. No discovery by project name. */
+export class HttpBridge {
+    endpoint;
+    fetch;
+    signal;
+    token;
+    timeoutMilliseconds;
+    schema;
+    constructor(endpoint, fetch = globalThis.fetch, signal, token, timeoutMilliseconds) {
+        this.endpoint = endpoint;
+        this.fetch = fetch;
+        this.signal = signal;
+        this.token = token;
+        this.timeoutMilliseconds = timeoutMilliseconds;
+        const url = new URL(endpoint);
+        if (url.protocol !== 'http:' || url.hostname !== '127.0.0.1' || !url.port || url.username || url.password || url.pathname !== '/')
+            fail('binding', 'Worker bridge must use an explicit loopback HTTP port.');
+        if (timeoutMilliseconds !== undefined && (!Number.isSafeInteger(timeoutMilliseconds) || timeoutMilliseconds < 1 || timeoutMilliseconds > 1800000))
+            fail('invalid', 'Bridge timeout is outside the supported bound.');
+    }
+    async request(path, method, query, body) {
+        const url = new URL(path, this.endpoint);
+        // Import includes synchronous auto-analysis. Keep discovery/ordinary requests short,
+        // while allowing a real executable to finish its first analysis without losing the reply.
+        const timeoutMilliseconds = this.timeoutMilliseconds ?? (path === '/import_file' ? 600000 : 30000);
+        const signal = this.signal ? AbortSignal.any([this.signal, AbortSignal.timeout(timeoutMilliseconds)]) : AbortSignal.timeout(timeoutMilliseconds);
+        const transportFailure = () => {
+            if (this.signal?.aborted)
+                fail('cancelled', `Ghidra request ${path} was cancelled; its outcome may require reconciliation.`, { operation: path });
+            if (signal.aborted)
+                fail('timeout', `Ghidra request ${path} exceeded ${timeoutMilliseconds / 1000} seconds; its outcome may require reconciliation.`, { operation: path, timeoutMilliseconds });
+            fail('transport', `Ghidra request ${path} did not complete; its outcome may require reconciliation.`, { operation: path });
+        };
+        for (const [name, value] of Object.entries(query))
+            url.searchParams.set(name, String(value));
+        let response;
+        try {
+            response = await this.fetch(url, { method, redirect: 'error', signal, headers: { ...(this.token ? { Authorization: 'Bearer ' + this.token } : {}), ...(method === 'POST' ? { 'Content-Type': 'application/json' } : {}) }, ...(method === 'POST' ? { body: JSON.stringify(body) } : {}) });
+        }
+        catch {
+            return transportFailure();
+        }
+        if (!response.ok)
+            fail('remote', 'Ghidra bridge rejected the operation.');
+        // Bound even a chunked/malformed service response; never persist raw payloads as logs.
+        const reader = response.body?.getReader();
+        if (!reader)
+            fail('malformed', 'Ghidra bridge returned an empty body.');
+        const chunks = [];
+        let length = 0;
+        try {
+            for (;;) {
+                const next = await reader.read();
+                if (next.done)
+                    break;
+                length += next.value.byteLength;
+                if (length > 1024 * 1024)
+                    fail('limit', 'Ghidra response exceeded one MiB.');
+                chunks.push(next.value);
+            }
+        }
+        catch (error) {
+            if (error instanceof CliError)
+                throw error;
+            return transportFailure();
+        }
+        finally {
+            await reader.cancel().catch(() => { });
+        }
+        const text = Buffer.concat(chunks).toString('utf8');
+        let result;
+        try {
+            result = parseDomainJson(text);
+        }
+        catch {
+            result = text;
+        }
+        if (result && typeof result === 'object' && !Array.isArray(result)) {
+            const o = object(result);
+            if (o.error || o.success === false || o.status === 'error') {
+                const reason = typeof o.error === 'string' && o.error.length <= 1024 && !o.error.includes('\0') ? o.error : undefined;
+                fail('remote', reason ? 'Ghidra: ' + reason : 'Ghidra operation failed.');
+            }
+        }
+        return result;
+    }
+    async instance() { return object(await this.request('/mcp/instance_info', 'GET', {}, {})); }
+    async descriptor(path) {
+        if (!this.schema) {
+            const schema = object(await this.request('/mcp/schema', 'GET', {}, {}));
+            if (!Array.isArray(schema.tools))
+                fail('malformed', 'Ghidra schema omitted its tool descriptors.');
+            this.schema = new Map(schema.tools.map(value => { const d = object(value); return [d.path, d]; }));
+        }
+        const tool = this.schema.get(path);
+        if (!tool || !['GET', 'POST'].includes(tool.method) || !Array.isArray(tool.params))
+            fail('schema', 'Required Ghidra operation is missing from the observed schema.');
+        return tool;
+    }
+    async call(path, params = {}) {
+        const tool = await this.descriptor(path);
+        const query = {}, body = {};
+        for (const [name, value] of Object.entries(params)) {
+            const param = tool.params.find(p => p.name === name);
+            if (!param)
+                fail('schema', 'Required Ghidra operation parameter is missing from the observed schema.');
+            (param.source === 'body' ? body : query)[name] = value;
+        }
+        return this.request(path, tool.method, query, body);
+    }
+}
+export function decodeMcp(result) {
+    const r = object(result);
+    if (r.isError === true || !Array.isArray(r.content))
+        fail('remote', 'MCP bridge reported failure or malformed content.');
+    const content = r.content.filter(x => x && typeof x === 'object' && x.type === 'text');
+    if (content.length !== 1 || typeof content[0]?.text !== 'string' || content[0].text.length > 1024 * 1024)
+        fail('malformed', 'Expected one bounded MCP text result.');
+    let value;
+    try {
+        value = parseDomainJson(content[0].text);
+    }
+    catch {
+        value = content[0].text;
+    }
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        const o = object(value);
+        if (o.error || o.success === false)
+            fail('remote', 'MCP result content reports failure.');
+    }
+    return value;
+}

package/dist/src/ui-results.d.ts

@@ -0,0 +1,2 @@
+import type { Scope } from './workspace.js';
+export declare function uiResult(operation: string, p: Record<string, unknown>, raw: unknown, selected: Scope, program: string, label: string, nativeName?: string): Record<string, unknown>;

package/dist/src/ui-results.js

@@ -0,0 +1,80 @@
+import { object, fail, text } from './model.js';
+import { address, publicAddress } from './research.js';
+export function uiResult(operation, p, raw, selected, program, label, nativeName) {
+    const value = object(raw), check = (value) => { if (value !== program && value !== program.slice(program.lastIndexOf('/') + 1) && !(nativeName !== undefined && value === nativeName))
+        fail('binding', 'UI selected an undeclared program.'); };
+    if (operation === 'tools') {
+        if (!Array.isArray(value.tools) || value.tools.length > 100 || value.count !== value.tools.length)
+            fail('partial', 'UI tool inventory has inconsistent counts.');
+        const tools = value.tools.map(raw => {
+            const row = object(raw);
+            text(row.name);
+            if (typeof row.has_program_manager !== 'boolean')
+                fail('partial', 'UI tool omitted its program-manager capability.');
+            if (row.current_program !== undefined)
+                check(row.current_program);
+            if (row.has_program_manager && (!Array.isArray(row.open_programs) || row.open_programs.length > 100))
+                fail('partial', 'UI tool omitted its open programs.');
+            const open = Array.isArray(row.open_programs) ? row.open_programs.map(value => { check(value); return selected; }) : [];
+            return { name: row.name, hasProgramManager: row.has_program_manager, current: row.current_program === undefined ? null : selected, open };
+        });
+        return { tools, count: tools.length };
+    }
+    if (operation === 'goto') {
+        if (value.success !== true || address(value.address) !== address(p.address))
+            fail('partial', 'Navigation did not acknowledge the requested address.');
+        return { address: publicAddress(value.address), ...(typeof value.function === 'string' ? { function: value.function } : {}) };
+    }
+    if (operation === 'prompt_policy') {
+        if (typeof value.enabled !== 'boolean' || !Number.isSafeInteger(value.remaining_ms) || Number(value.remaining_ms) < 0 || typeof value.reason !== 'string' || !Array.isArray(value.actions) || value.actions.length > 1000)
+            fail('partial', 'Prompt policy status is incomplete.');
+        if (p.action === 'enable' && value.enabled !== true || p.action === 'disable' && value.enabled !== false)
+            fail('partial', 'Prompt policy did not establish the requested state.');
+        return value;
+    }
+    if (operation === 'cursor') {
+        const result = {};
+        for (const facet of ['address', 'function', 'selection', 'program']) {
+            if (!Object.hasOwn(value, facet) && typeof value[facet + '_unavailable'] !== 'string')
+                fail('partial', 'Cursor omitted a requested facet.');
+            if (value[facet] === null || !Object.hasOwn(value, facet)) {
+                if (typeof value[facet + '_unavailable'] !== 'string')
+                    fail('partial', 'Unavailable cursor facet omitted its reason.');
+                result[facet] = null;
+                result[facet + '_unavailable'] = value[facet + '_unavailable'];
+                continue;
+            }
+            const row = object(value[facet]);
+            if (facet === 'program') {
+                check(row.path);
+                const { path, executable_path, name, ...metadata } = row;
+                for (const field of ['language', 'compiler', 'executable_format'])
+                    text(metadata[field]);
+                for (const field of ['function_count', 'symbol_count', 'data_type_count', 'memory_size'])
+                    if (!Number.isSafeInteger(metadata[field]) || Number(metadata[field]) < 0)
+                        fail('partial', 'Focused program metadata is incomplete.');
+                result.program = { ...metadata, ...selected, name: label };
+            }
+            else {
+                check(row.program);
+                const { program: route, ...data } = row;
+                if (facet === 'address')
+                    data.address = publicAddress(row.address);
+                if (facet === 'function') {
+                    text(row.function_name);
+                    text(row.signature);
+                    data.address = publicAddress(row.address);
+                }
+                if (facet === 'selection') {
+                    if (typeof row.is_empty !== 'boolean' || !Array.isArray(row.ranges) || row.ranges.length > 10000)
+                        fail('partial', 'Cursor selection is incomplete.');
+                    data.ranges = row.ranges.map(raw => { const range = object(raw); if (!Number.isSafeInteger(range.length) || Number(range.length) < 1)
+                        fail('partial', 'Cursor selection range is invalid.'); return { ...range, start: publicAddress(range.start), end: publicAddress(range.end) }; });
+                }
+                result[facet] = { ...data, ...selected };
+            }
+        }
+        return result;
+    }
+    fail('schema', 'UI operation lacks a result contract.');
+}

package/dist/src/ui.d.ts

@@ -0,0 +1,17 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import { Workspace, type Scope } from './workspace.js';
+import { Research, type ResearchBackend } from './research.js';
+export declare class UserInterface {
+    private readonly workspace;
+    private readonly research;
+    private readonly backend;
+    constructor(workspace: Workspace, research: Research, backend: () => Promise<ResearchBackend>);
+    read(selected: Scope, operation: 'cursor' | 'tools' | 'plugins_list', facet?: string): Promise<{
+        value: Record<string, unknown>;
+        session: string;
+        target: string;
+    }>;
+    change(selected: Scope, operation: 'goto' | 'prompt_policy' | 'plugins_set', p: Record<string, unknown>, callerId?: string): Promise<unknown>;
+}
+export declare function uiCommands(service: (c: CommandContext) => UserInterface): CommandDefinition[];
+export declare function pluginCommands(service: (c: CommandContext) => UserInterface): CommandDefinition[];

package/dist/src/ui.js

@@ -0,0 +1,88 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { scope, address, number } from './research.js';
+import { id, text, object, fail } from './model.js';
+import { selectedOptions } from './arguments.js';
+export class UserInterface {
+    workspace;
+    research;
+    backend;
+    constructor(workspace, research, backend) {
+        this.workspace = workspace;
+        this.research = research;
+        this.backend = backend;
+    }
+    async read(selected, operation, facet = 'all') {
+        return this.research.ordered(selected, async () => {
+            const backend = await this.backend();
+            await backend.open(selected);
+            if (operation === 'tools' || operation === 'plugins_list')
+                await backend.mode(selected, 'gui');
+            if (!backend.ui)
+                fail('configuration', 'Selected backend lacks the UI adapter.');
+            const value = await backend.ui(selected, operation, {});
+            return { ...selected, value: operation === 'cursor' && facet !== 'all' ? { [facet]: value[facet], ...(value[facet] === null ? { reason: value[facet + '_unavailable'] } : {}) } : value };
+        });
+    }
+    async change(selected, operation, p, callerId) {
+        const reserved = this.workspace.reserveRequest(selected, 'ghidra.ui.' + operation, p, callerId);
+        return this.research.ordered(selected, async () => {
+            const request = this.workspace.request(reserved.request.id);
+            if (reserved.replay && request.state !== 'accepted') {
+                if (request.state === 'applied')
+                    return request.result;
+                fail('unknown', 'UI effect is retained and is not repeated.', request.result);
+            }
+            const backend = await this.backend();
+            await backend.open(selected);
+            await backend.mode(selected, 'gui');
+            if (!backend.ui)
+                fail('configuration', 'Selected backend lacks the UI adapter.');
+            const context = this.workspace.context(selected);
+            this.workspace.startRequest(request.id, { kind: 'ui', operation, generation: context.generation });
+            try {
+                const value = await backend.ui(selected, operation, p);
+                if (operation === 'goto') {
+                    const cursor = await backend.ui(selected, 'cursor', {}), location = object(cursor.address);
+                    if (location.session !== selected.session || location.target !== selected.target || address(location.address) !== address(p.address))
+                        fail('partial', 'Cursor did not reach the requested context and address.');
+                }
+                const plugin = operation === 'plugins_set', snapshot = plugin ? await backend.saved(selected) : undefined;
+                const complexChanges = plugin ? [...context.complexChanges, request.id] : context.complexChanges;
+                const result = { ...selected, state: 'applied', value, ...(plugin ? { sharedState: 'pending', pendingChanges: context.scalars.length + complexChanges.length } : {}) };
+                this.workspace.completeSavedRequest(selected, request.id, context.generation, plugin ? { workingSnapshot: snapshot, complexChanges } : {}, result);
+                return result;
+            }
+            catch (error) {
+                this.workspace.recordRequest(request.id, 'unknown', { ...selected, state: 'unknown', operation });
+                throw error;
+            }
+        });
+    }
+}
+export function uiCommands(service) {
+    const request = { flags: '--request-id <id>', description: 'Retrieve the recorded UI result without repeating it' };
+    return [command('ui', 'Inspect and control the selected context interface', [
+            command('cursor', 'Read the focused address, function, selection and program', ({ options: o }, c) => {
+                const type = text(o.type);
+                if (!['all', 'address', 'function', 'selection', 'program'].includes(type))
+                    fail('invalid', 'Cursor type must be all, address, function, selection or program.');
+                return service(c).read(scope(o), 'cursor', type);
+            }, { permission: Permission.ReadOnly, options: [...selectedOptions, { flags: '--type <facet>', description: 'Cursor facet or all', defaultValue: 'all' }] }),
+            command('tools', 'Read tools in the owned GUI context', ({ options: o }, c) => service(c).read(scope(o), 'tools'), { permission: Permission.ReadOnly, options: selectedOptions }),
+            command('goto', 'Navigate the owned browser and verify the cursor', ({ options: o }, c) => service(c).change(scope(o), 'goto', { address: address(o.address) }, o.requestId === undefined ? undefined : id(o.requestId)), { permission: Permission.Update, options: [...selectedOptions, { flags: '--address <address>', description: 'Explicit address', required: true }, request] }),
+            command('prompt-policy', 'Temporarily control the owned GUI prompt policy', ({ options: o }, c) => {
+                const action = text(o.action);
+                if (!['status', 'enable', 'disable'].includes(action))
+                    fail('invalid', 'Prompt policy action must be status, enable or disable.');
+                return service(c).change(scope(o), 'prompt_policy', { action, reason: text(o.reason, 512), seconds: number(o.seconds, 300, 1) }, o.requestId === undefined ? undefined : id(o.requestId));
+            }, { permission: Permission.Update, options: [...selectedOptions, { flags: '--action <action>', description: 'status, enable or disable', defaultValue: 'status' },
+                    { flags: '--reason <text>', description: 'Recorded policy reason', defaultValue: 'automation' }, { flags: '--seconds <count>', description: 'Requested duration (1–300 seconds)', defaultValue: 120 }, request] }),
+        ])];
+}
+export function pluginCommands(service) {
+    return [command('plugins', 'Configure plugins from enabled managed modules in an owned GUI', [
+            command('list', 'Read enabled managed plugins in this GUI tool', ({ options: o }, c) => service(c).read(scope(o), 'plugins_list'), { permission: Permission.ReadOnly, options: selectedOptions }),
+            command('set', 'Enable or disable one installed managed plugin with immediate readback', ({ options: o }, c) => { if (o.enabled !== 'true' && o.enabled !== 'false')
+                fail('invalid', 'enabled must be true or false.'); return service(c).change(scope(o), 'plugins_set', { plugin: text(o.plugin, 512), enabled: o.enabled === 'true' }, o.requestId === undefined ? undefined : id(o.requestId)); }, { permission: 'Destructive', options: [...selectedOptions, { flags: '--plugin <class>', description: 'Managed plugin ID from extensions capabilities', required: true }, { flags: '--enabled <boolean>', description: 'true or false', required: true }, { flags: '--request-id <id>', description: 'Retrieve the original plugin outcome without replay' }] })
+        ])];
+}

package/dist/src/utility.d.ts

@@ -0,0 +1,14 @@
+import { type CommandDefinition } from '@eyeauras/cli-factory';
+/** Equivalent of the pinned unsigned 64-bit number conversion, without a tool process. */
+export declare function convertNumber(input: unknown, size?: unknown): {
+    input: string;
+    input_type: string;
+    size: number;
+    decimal_unsigned: string;
+    decimal_signed: string;
+    hexadecimal: string;
+    binary: string;
+    octal: string;
+    hex_padded: string;
+};
+export declare function utilityCommands(): CommandDefinition[];

package/dist/src/utility.js

@@ -0,0 +1,43 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { fail, text } from './model.js';
+/** Equivalent of the pinned unsigned 64-bit number conversion, without a tool process. */
+export function convertNumber(input, size = 4) {
+    const source = text(input, 128), width = Number(size);
+    if (!Number.isSafeInteger(width) || width < 1 || width > 8)
+        fail('invalid', 'Size must be 1–8 bytes.');
+    let value, inputType;
+    try {
+        if (/^0[xX][a-fA-F0-9]+$/.test(source)) {
+            value = BigInt(source);
+            inputType = 'hexadecimal';
+        }
+        else if (/^0[bB][01]+$/.test(source)) {
+            value = BigInt(source);
+            inputType = 'binary';
+        }
+        else if (/^0[0-7]+$/.test(source) && source.length > 1) {
+            value = BigInt('0o' + source);
+            inputType = 'octal';
+        }
+        else if (/^\+?\d+$/.test(source)) {
+            value = BigInt(source);
+            inputType = 'decimal';
+        }
+        else
+            throw Error();
+        if (value < 0n || value > 0xffffffffffffffffn)
+            throw Error();
+    }
+    catch {
+        fail('invalid', 'Number must be an unsigned 64-bit decimal, hexadecimal, binary or octal integer.');
+    }
+    const bits = BigInt(width * 8), masked = value & ((1n << bits) - 1n), signed = masked >= (1n << (bits - 1n)) ? masked - (1n << bits) : masked, hex = masked.toString(16).toUpperCase();
+    return { input: source, input_type: inputType, size: width, decimal_unsigned: masked.toString(), decimal_signed: signed.toString(),
+        hexadecimal: '0x' + hex, binary: '0b' + masked.toString(2), octal: '0' + masked.toString(8), hex_padded: '0x' + hex.padStart(width * 2, '0') };
+}
+export function utilityCommands() {
+    return [command('utility', 'Stateless research utilities', [
+            command('convert-number', 'Convert an unsigned 64-bit integer at an explicit byte width', ({ options: o }) => convertNumber(o.text, o.size), { permission: Permission.ReadOnly, options: [{ flags: '--text <number>', description: 'Decimal, 0x hexadecimal, 0b binary or leading-zero octal', required: true },
+                    { flags: '--size <bytes>', description: 'Output width, 1–8 bytes', defaultValue: 4 }] })
+        ])];
+}

package/dist/src/version-tracking.d.ts

@@ -0,0 +1,57 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import { Workspace, type Scope } from './workspace.js';
+import { Research, type ResearchBackend } from './research.js';
+/** A native VT object belongs to an existing research session; it is not another agent session. */
+export declare class VersionTracking {
+    private readonly workspace;
+    private readonly research;
+    private readonly backend;
+    private readonly tasks;
+    constructor(workspace: Workspace, research: Research, backend: () => Promise<ResearchBackend>, tasks: Map<string, Promise<unknown>>);
+    private ordered;
+    private root;
+    private owner;
+    private response;
+    private native;
+    list(selected: Scope, offset: number, limit: number): Promise<{
+        items: never[];
+        complete: boolean;
+        session: string;
+        target: string;
+    } | {
+        nextOffset?: number | undefined;
+        items: {
+            tracking: string;
+            source: Scope;
+            destination: Scope;
+            sourceSnapshotSha256: string;
+            destinationSnapshotSha256: string;
+        }[];
+        visited: number;
+        complete: boolean;
+        session: string;
+        target: string;
+    }>;
+    private decisionResult;
+    create(selected: Scope, source: Scope, callerId?: string): Promise<unknown>;
+    read(selected: Scope, tracking: string, operation: 'matches' | 'markup', p: Record<string, unknown>): Promise<{
+        tracking: string;
+        source: {
+            snapshotSha256: string;
+            session: string;
+            target: string;
+        };
+        destination: {
+            snapshotSha256: string;
+            session: string;
+            target: string;
+        };
+        sourceContextChanged: boolean;
+        destinationContextChanged: boolean;
+        value: unknown;
+        session: string;
+        target: string;
+    }>;
+    decide(selected: Scope, tracking: string, p: Record<string, unknown>, callerId?: string): Promise<unknown>;
+}
+export declare function trackingCommands(service: (c: CommandContext) => VersionTracking): CommandDefinition[];