@eyeauras/insight-cli 0.0.0-stage → 0.2.0

package/dist/src/store.d.ts

@@ -0,0 +1,33 @@
+import { type Batch, type Binding, type FindingRecord, type State, type Target } from './model.js';
+export declare class Store {
+    readonly directory: string;
+    readonly profile: string;
+    readonly server: string;
+    static pending(directory: string): boolean;
+    private db;
+    constructor(directory: string, profile: string, server: string);
+    close(): void;
+    private transaction;
+    register(value: unknown): Target;
+    target(id: string): Target;
+    targets(): Target[];
+    submit(value: unknown): FindingRecord;
+    getFinding(id: string): FindingRecord;
+    findings(targetId?: string): FindingRecord[];
+    begin(targetId: string): Batch | undefined;
+    batch(id: string): Batch;
+    batches(): Batch[];
+    update(id: string, state: State, patch?: Partial<Omit<Batch, 'id' | 'targetId' | 'findings'>>): Batch;
+    conflicts(id: string, conflicts: unknown): void;
+    private event;
+    events(id: string): {
+        seq: import("node:sqlite").SQLOutputValue | undefined;
+        state: import("node:sqlite").SQLOutputValue | undefined;
+        data: any;
+    }[];
+    worker(id: string): Binding;
+    putWorker(id: string, targetId: string, binding: Binding): void;
+    updateReader(id: string, binding: Binding): void;
+    workers(): any[];
+    removeWorker(id: string): void;
+}

package/dist/src/store.js

@@ -0,0 +1,178 @@
+import { DatabaseSync } from 'node:sqlite';
+import { mkdirSync, chmodSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { assertIdentity, digest, fail, finding, identity, stable } from './model.js';
+export class Store {
+    directory;
+    profile;
+    server;
+    static pending(directory) {
+        const path = join(directory, 'coordinator.sqlite');
+        if (!existsSync(path))
+            return false;
+        const db = new DatabaseSync(path, { readOnly: true });
+        try {
+            return Number(db.prepare("SELECT COUNT(*) AS count FROM findings WHERE state != 'published_verified'").get()?.count) > 0;
+        }
+        finally {
+            db.close();
+        }
+    }
+    db;
+    constructor(directory, profile, server) {
+        this.directory = directory;
+        this.profile = profile;
+        this.server = server;
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+        const path = join(directory, 'coordinator.sqlite');
+        this.db = new DatabaseSync(path);
+        chmodSync(path, 0o600);
+        this.db.exec(`PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL; PRAGMA foreign_keys=ON; PRAGMA busy_timeout=5000;
+      CREATE TABLE IF NOT EXISTS targets(id TEXT PRIMARY KEY, lane TEXT NOT NULL UNIQUE, data TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS findings(id TEXT PRIMARY KEY, request_id TEXT NOT NULL UNIQUE, hash TEXT NOT NULL, target_id TEXT NOT NULL REFERENCES targets(id), state TEXT NOT NULL, batch_id TEXT, data TEXT NOT NULL, conflict TEXT);
+      CREATE TABLE IF NOT EXISTS batches(id TEXT PRIMARY KEY, target_id TEXT NOT NULL REFERENCES targets(id), state TEXT NOT NULL, owner_pid INTEGER NOT NULL, data TEXT NOT NULL);
+      CREATE UNIQUE INDEX IF NOT EXISTS active_lane ON batches(target_id) WHERE state IN ('applying','staged','checking_in','publication_unknown','failed');
+      CREATE TABLE IF NOT EXISTS events(seq INTEGER PRIMARY KEY AUTOINCREMENT, batch_id TEXT NOT NULL, state TEXT NOT NULL, data TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS workers(id TEXT PRIMARY KEY, target_id TEXT NOT NULL, data TEXT NOT NULL);
+      PRAGMA user_version=1;`);
+    }
+    close() { this.db.close(); }
+    transaction(action) {
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const result = action();
+            this.db.exec('COMMIT');
+            return result;
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    register(value) {
+        const selected = identity(value);
+        if (selected.profile !== this.profile || selected.server !== this.server)
+            fail('binding', 'Target must match the selected profile and server.');
+        const lane = digest([selected.profile, selected.server, selected.repository, selected.programPath]);
+        const target = { ...selected, id: 't-' + digest(selected).slice(0, 24), lane };
+        return this.transaction(() => {
+            const existing = this.db.prepare('SELECT data FROM targets WHERE lane=?').get(lane);
+            if (existing) {
+                const t = JSON.parse(String(existing.data));
+                assertIdentity(t, target);
+                return t;
+            }
+            this.db.prepare('INSERT INTO targets VALUES(?,?,?)').run(target.id, lane, stable(target));
+            return target;
+        });
+    }
+    target(id) {
+        const row = this.db.prepare('SELECT data FROM targets WHERE id=?').get(id);
+        if (!row)
+            fail('notFound', 'Target was not found in the selected profile.');
+        const target = JSON.parse(String(row.data));
+        if (target.profile !== this.profile || target.server !== this.server)
+            fail('binding', 'Registered target belongs to a different profile or server.');
+        return target;
+    }
+    targets() { return this.db.prepare('SELECT data FROM targets ORDER BY id LIMIT 100').all().map(r => this.target(JSON.parse(String(r.data)).id)); }
+    submit(value) {
+        const f = finding(value);
+        assertIdentity(f.identity, this.target(f.targetId));
+        return this.transaction(() => {
+            const previous = this.db.prepare('SELECT id,hash FROM findings WHERE request_id=? OR id=?').all(f.requestId, f.findingId);
+            if (previous.length) {
+                if (previous.length !== 1 || previous[0]?.hash !== digest(f))
+                    fail('idempotency', 'Request or finding ID was already used with different content.');
+                return this.getFinding(String(previous[0].id));
+            }
+            const worker = this.worker(f.workerId);
+            assertIdentity(worker.identity, f.identity);
+            if (worker.role !== 'reader' || worker.version !== f.baselineVersion)
+                fail('binding', 'Finding does not match its registered reader baseline.');
+            if (f.resolves) {
+                const previous = this.getFinding(f.resolves);
+                if (previous.state !== 'conflict_pending' || previous.targetId !== f.targetId || previous.address !== f.address || previous.kind !== f.kind)
+                    fail('conflict', 'Resolution must reference a conflicting finding for the same scoped comment.');
+            }
+            this.db.prepare('INSERT INTO findings(id,request_id,hash,target_id,state,data) VALUES(?,?,?,?,?,?)').run(f.findingId, f.requestId, digest(f), f.targetId, 'queued', stable(f));
+            return this.getFinding(f.findingId);
+        });
+    }
+    getFinding(id) {
+        const row = this.db.prepare('SELECT * FROM findings WHERE id=?').get(id);
+        if (!row)
+            fail('notFound', 'Finding was not found.');
+        return { ...JSON.parse(String(row.data)), state: row.state, ...(row.batch_id ? { batchId: row.batch_id } : {}), ...(row.conflict ? { conflict: JSON.parse(String(row.conflict)) } : {}) };
+    }
+    findings(targetId) {
+        if (targetId)
+            this.target(targetId);
+        const rows = targetId ? this.db.prepare('SELECT id FROM findings WHERE target_id=? ORDER BY rowid LIMIT 100').all(targetId) : this.db.prepare('SELECT id FROM findings ORDER BY rowid LIMIT 100').all();
+        return rows.map(r => this.getFinding(String(r.id)));
+    }
+    begin(targetId) {
+        this.target(targetId);
+        return this.transaction(() => {
+            const active = this.db.prepare("SELECT id FROM batches WHERE target_id=? AND state IN ('applying','staged','checking_in','publication_unknown','failed')").get(targetId);
+            if (active)
+                fail('blocked', 'Publication lane requires recovery before new integration.', this.batch(String(active.id)));
+            const rows = this.db.prepare("SELECT id FROM findings WHERE target_id=? AND state='queued' ORDER BY rowid LIMIT 100").all(targetId);
+            if (!rows.length)
+                return undefined;
+            const id = 'b-' + randomUUID();
+            const batch = { id, targetId, state: 'applying', ownerPid: process.pid, findings: rows.map(r => this.getFinding(String(r.id))) };
+            this.db.prepare('INSERT INTO batches VALUES(?,?,?,?,?)').run(id, targetId, batch.state, process.pid, stable({}));
+            for (const row of rows)
+                this.db.prepare("UPDATE findings SET state='applying',batch_id=? WHERE id=?").run(id, row.id);
+            this.event(id, 'applying', {});
+            return this.batch(id);
+        });
+    }
+    batch(id) {
+        const row = this.db.prepare('SELECT * FROM batches WHERE id=?').get(id);
+        if (!row)
+            fail('notFound', 'Publication batch was not found.');
+        this.target(String(row.target_id));
+        return { ...JSON.parse(String(row.data)), id: String(row.id), targetId: String(row.target_id), state: String(row.state), ownerPid: Number(row.owner_pid), findings: this.db.prepare('SELECT id FROM findings WHERE batch_id=? ORDER BY rowid').all(id).map(r => this.getFinding(String(r.id))) };
+    }
+    batches() { return this.db.prepare('SELECT id FROM batches ORDER BY rowid DESC LIMIT 100').all().map(r => this.batch(String(r.id))); }
+    update(id, state, patch = {}) {
+        return this.transaction(() => {
+            const current = this.batch(id);
+            const { findings: _findings, id: _id, targetId: _targetId, ...data } = { ...current, ...patch, state };
+            this.db.prepare('UPDATE batches SET state=?,data=? WHERE id=?').run(state, stable(data), id);
+            this.db.prepare('UPDATE findings SET state=? WHERE batch_id=?').run(state, id);
+            this.event(id, state, patch);
+            return this.batch(id);
+        });
+    }
+    conflicts(id, conflicts) {
+        this.db.prepare('UPDATE findings SET conflict=? WHERE batch_id=?').run(stable(conflicts), id);
+    }
+    event(id, state, data) { this.db.prepare('INSERT INTO events(batch_id,state,data) VALUES(?,?,?)').run(id, state, stable(data)); }
+    events(id) { return this.db.prepare('SELECT seq,state,data FROM events WHERE batch_id=? ORDER BY seq').all(id).map(r => ({ seq: r.seq, state: r.state, data: JSON.parse(String(r.data)) })); }
+    worker(id) {
+        const row = this.db.prepare('SELECT data,target_id FROM workers WHERE id=?').get(id);
+        if (!row)
+            fail('notFound', 'Worker was not found.');
+        this.target(String(row.target_id));
+        return JSON.parse(String(row.data));
+    }
+    putWorker(id, targetId, binding) {
+        assertIdentity(binding.identity, this.target(targetId));
+        if (this.db.prepare('SELECT id FROM workers WHERE id=?').get(id))
+            fail('workerExists', 'Worker ID is already registered.');
+        this.db.prepare('INSERT INTO workers VALUES(?,?,?)').run(id, targetId, stable(binding));
+    }
+    updateReader(id, binding) {
+        const previous = this.worker(id);
+        assertIdentity(binding.identity, previous.identity);
+        if (previous.pid !== binding.pid || previous.endpoint !== binding.endpoint || previous.version !== binding.version || previous.projectDirectory !== binding.projectDirectory || previous.role !== 'reader' || binding.role !== 'reader' || previous.readEpoch && previous.readEpoch !== binding.readEpoch)
+            fail('binding', 'Reader update changed its immutable binding.');
+        this.db.prepare('UPDATE workers SET data=? WHERE id=?').run(stable(binding), id);
+    }
+    workers() { return this.db.prepare('SELECT id,target_id,data FROM workers ORDER BY id LIMIT 100').all().map(r => ({ id: r.id, targetId: r.target_id, ...JSON.parse(String(r.data)) })); }
+    removeWorker(id) { this.db.prepare('DELETE FROM workers WHERE id=?').run(id); }
+}

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[];