@openvulcan/dsh-vulcancode 0.0.0-stage → 0.4.3

package/node_modules/@openvulcan/dsh-decision-guard/lib/panel.d.ts

@@ -0,0 +1,158 @@
+/**
+ * The Host side of the settings panel: the account status, cloud endpoints, runtime packs, local
+ * models and the decision log, served as exact `/api/vulcan-decision/*` routes inside dsh's authenticated
+ * connection. Only owner peers reach these routes.
+ *
+ * Signing in belongs to the OpenVulcan account plugin; the guard only reads the account through
+ * its service. Packs and models live under `$DSH_HOME/vulcan-decision/`.
+ */
+import { DecisionEngine, type AccountSource, type AccountStatus, type Credential, type DecisionHome, type DownloadSource, type EngineSettings, type EndpointSnapshot, type TestResult, type Verdict } from '@openvulcan/vulcan-decision';
+import { type DecisionRecord, type RecordExport, type RecordPage, type RecordStore } from './records.js';
+/** Prefix of every panel route, below dsh's `/api`. Also restated in `client/index.tsx`. */
+export declare const ROUTE_PREFIX = "/api/vulcan-decision/";
+/**
+ * The account the cloud backend signs with: the OpenVulcan account plugin's service, looked up on
+ * every use. The guard never injects the service, because a required one that is missing would
+ * leave the guard silently pending and its gate gone; without it, cloud judging fails as not
+ * signed in and the call is not allowed.
+ */
+export declare class ServiceAccount implements AccountSource {
+    private readonly service;
+    constructor(service: () => AccountSource | undefined);
+    /** Whether the account plugin is running. */
+    available(): boolean;
+    status(): Promise<AccountStatus>;
+    credential(): Promise<Credential>;
+}
+/** A long-running install the panel started; one runs at a time. */
+export interface Job {
+    readonly kind: 'pack' | 'model-download' | 'model-directory';
+    readonly target: string;
+    readonly phase: 'download' | 'unpack' | 'install' | 'probe' | 'verify' | 'done' | 'failed' | 'cancelled';
+    readonly done?: number;
+    readonly total?: number;
+    readonly error?: string;
+    readonly startedAt: number;
+}
+/** The panel's settings, as `src/index.ts` reads them for each request. */
+export interface PanelSettings {
+    readonly engine: () => EngineSettings;
+    readonly downloadSource: () => DownloadSource;
+    /** Whether the OpenVulcan account plugin is running; without it the cloud backend is signed out. */
+    readonly accountPlugin: () => boolean;
+}
+export declare class Panel {
+    readonly engine: DecisionEngine;
+    private readonly settings;
+    private readonly records;
+    private job;
+    private jobAbort;
+    constructor(engine: DecisionEngine, settings: PanelSettings, records: RecordStore);
+    get home(): DecisionHome;
+    /** Everything the panel shows, in one answer. */
+    state(): Promise<{
+        account: {
+            plugin: boolean;
+            signedIn: boolean;
+            site?: import("@openvulcan/vulcan-decision").Site;
+            authorizationId?: string;
+            expiresAt?: string;
+            reauthRequired?: boolean;
+        };
+        cloud: EndpointSnapshot;
+        hardware: {
+            gpus: {
+                generation?: import("@openvulcan/vulcan-decision").GpuGeneration;
+                name: string;
+                vendor: "nvidia" | "amd" | "intel" | "apple" | "other";
+                memoryBytes?: number;
+                computeCapability?: string;
+                driver?: string;
+            }[];
+            platform: NodeJS.Platform;
+            arch: string;
+            target?: import("@openvulcan/vulcan-decision").Target;
+            totalMemory: number;
+            cpus: number;
+            npus: readonly import("@openvulcan/vulcan-decision").NpuInfo[];
+        };
+        recommendation: import("@openvulcan/vulcan-decision").Recommendation;
+        packs: {
+            installed: {
+                outdated: boolean;
+                installedAt: string;
+            } | null;
+            needsDriver?: string;
+            bytes?: number;
+            id: "onnx-cpu" | "onnx-cuda" | "torch-cpu" | "torch-cu128";
+            backend: import("@openvulcan/vulcan-decision").Backend;
+            device: import("@openvulcan/vulcan-decision").Device;
+            fit: import("@openvulcan/vulcan-decision").PackFit;
+        }[];
+        planned: readonly [{
+            readonly id: "onnx-openvino";
+            readonly backend: "onnx";
+            readonly accelerator: "intel-npu";
+        }, {
+            readonly id: "onnx-qnn";
+            readonly backend: "onnx";
+            readonly accelerator: "qualcomm-npu";
+        }];
+        models: {
+            family?: "mini" | "flash" | "standard";
+            id: string;
+            name: string;
+            format: import("@openvulcan/vulcan-decision").ModelFormat;
+            bytes: number;
+            installedAt: string;
+        }[];
+        catalog: {
+            family: "mini" | "flash" | "standard";
+            name: string;
+            parameters: string;
+            format: import("@openvulcan/vulcan-decision").ModelFormat;
+            sources: ("huggingface" | "modelscope-intl" | "modelscope-cn")[];
+        }[];
+        local: import("@openvulcan/vulcan-decision").LocalStatus;
+        job: Job | null;
+        home: string;
+    }>;
+    /** The models OpenVulcan lists for this account; the first is the default. */
+    cloudModels(): Promise<string[]>;
+    /** The endpoint table of the saved (or default) model, without measuring. */
+    endpoints(): Promise<EndpointSnapshot>;
+    /** Measure the endpoints of the saved (or default) model now. */
+    probe(): Promise<EndpointSnapshot>;
+    /** Check an endpoint the user is about to lock against the model it will be saved with. */
+    checkLock(model: unknown, endpoint: unknown): Promise<void>;
+    /** Time five real judgements of a sample call on one endpoint. */
+    requestTest(endpoint: unknown, input: unknown): Promise<TestResult>;
+    installPack(pack: string | null, source: string | null): Job;
+    removePack(pack: string | null): boolean;
+    downloadModel(family: string | null, source: string | null): Job;
+    installModelDirectory(dir: unknown): Job;
+    removeModel(id: string | null): boolean;
+    cancelJob(): void;
+    /** Judge a sample call with the saved settings, so the user sees the backend answer. */
+    test(tool: unknown, args: unknown): Promise<Verdict>;
+    /** One page of the decision log, newest first. */
+    recordPage(url: URL): RecordPage;
+    /** Mark the label a record should have had, or clear the mark with null. */
+    markRecord(id: unknown, correction: unknown): DecisionRecord;
+    exportRecords(): RecordExport;
+    clearRecords(): void;
+    close(): void;
+    private source;
+    private assertIdle;
+    private running;
+    private run;
+    private update;
+    private finish;
+}
+/** Fetch-shaped handler of one panel route. */
+type Handler = (panel: Panel, request: Request, url: URL) => Promise<unknown>;
+/** Every panel route: method, path below {@link ROUTE_PREFIX}, handler. */
+export declare const ROUTES: readonly (readonly ['GET' | 'POST', string, Handler])[];
+/** Answer one panel request; failures carry their code, never a stack. */
+export declare function handle(panel: Panel, handler: Handler, request: Request): Promise<Response>;
+export {};

package/node_modules/@openvulcan/dsh-decision-guard/lib/panel.js

@@ -0,0 +1,340 @@
+/**
+ * The Host side of the settings panel: the account status, cloud endpoints, runtime packs, local
+ * models and the decision log, served as exact `/api/vulcan-decision/*` routes inside dsh's authenticated
+ * connection. Only owner peers reach these routes.
+ *
+ * Signing in belongs to the OpenVulcan account plugin; the guard only reads the account through
+ * its service. Packs and models live under `$DSH_HOME/vulcan-decision/`.
+ */
+import { DECISIONS, DecisionEngine, DecisionError, DOWNLOAD_SOURCES, MODEL_CATALOG, MODEL_FAMILIES, MODEL_SOURCES, PACK_IDS, PLANNED_PACKS, detectHardware, gpuGeneration, installModelFromDirectory, installPack, installedPack, isPackId, listModels, preferredPrecision, readLock, recommend, removeModel, removePack, downloadModel, sourcesOf, AccountError, } from '@openvulcan/vulcan-decision';
+import { PAGE_LIMIT_MAX } from './records.js';
+/** Prefix of every panel route, below dsh's `/api`. Also restated in `client/index.tsx`. */
+export const ROUTE_PREFIX = '/api/vulcan-decision/';
+/**
+ * The account the cloud backend signs with: the OpenVulcan account plugin's service, looked up on
+ * every use. The guard never injects the service, because a required one that is missing would
+ * leave the guard silently pending and its gate gone; without it, cloud judging fails as not
+ * signed in and the call is not allowed.
+ */
+export class ServiceAccount {
+    service;
+    constructor(service) {
+        this.service = service;
+    }
+    /** Whether the account plugin is running. */
+    available() {
+        return this.service() !== undefined;
+    }
+    async status() {
+        return (await this.service()?.status()) ?? { signedIn: false };
+    }
+    async credential() {
+        const service = this.service();
+        if (service === undefined)
+            throw new AccountError('the OpenVulcan account plugin is not running; enable it and sign in');
+        return await service.credential();
+    }
+}
+export class Panel {
+    engine;
+    settings;
+    records;
+    job;
+    jobAbort;
+    constructor(engine, settings, records) {
+        this.engine = engine;
+        this.settings = settings;
+        this.records = records;
+    }
+    get home() {
+        return this.engine.home;
+    }
+    /** Everything the panel shows, in one answer. */
+    async state() {
+        const hardware = detectHardware();
+        const recommendation = recommend(hardware);
+        const settings = this.settings.engine();
+        return {
+            account: { ...await this.engine.account.status(), plugin: this.settings.accountPlugin() },
+            cloud: this.engine.cloud.snapshot(settings.cloudModel === '' ? undefined : settings.cloudModel, settings.cloudEndpoint),
+            hardware: {
+                ...hardware,
+                gpus: hardware.gpus.map(gpu => ({
+                    ...gpu,
+                    ...gpu.computeCapability === undefined ? {} : { generation: gpuGeneration(gpu.computeCapability) },
+                })),
+            },
+            recommendation,
+            packs: PACK_IDS.map((pack) => {
+                const lock = readLock(pack);
+                const installed = installedPack(this.home, pack);
+                const fit = recommendation.packs.find(item => item.pack === pack);
+                return {
+                    id: pack, backend: lock.backend, device: lock.device, fit: fit.fit,
+                    ...fit.bytes === undefined ? {} : { bytes: fit.bytes },
+                    ...fit.needsDriver === undefined ? {} : { needsDriver: fit.needsDriver },
+                    installed: installed === undefined ? null : { outdated: installed.lock !== lock.id, installedAt: installed.installed_at },
+                };
+            }),
+            planned: PLANNED_PACKS,
+            models: listModels(this.home).map(model => ({
+                id: model.id, name: model.name, format: model.package_format, bytes: model.bytes, installedAt: model.installed_at,
+                ...model.family === undefined ? {} : { family: model.family },
+            })),
+            catalog: MODEL_CATALOG.map(model => ({
+                family: model.family, name: model.name, parameters: model.parameters, format: model.format,
+                sources: sourcesOf(model),
+            })),
+            local: this.engine.local.status(),
+            job: this.job ?? null,
+            home: this.home.root,
+        };
+    }
+    /** The models OpenVulcan lists for this account; the first is the default. */
+    async cloudModels() {
+        return await this.engine.cloud.models();
+    }
+    /** The endpoint table of the saved (or default) model, without measuring. */
+    async endpoints() {
+        const settings = this.settings.engine();
+        if (!(await this.engine.account.status()).signedIn)
+            return { mode: 'auto', endpoints: [] };
+        let model;
+        try {
+            model = await this.engine.cloud.resolveModel(settings.cloudModel);
+        }
+        catch (error) {
+            return { mode: 'auto', error: messageOf(error), endpoints: [] };
+        }
+        this.engine.cloud.refreshIfStale(model);
+        return this.engine.cloud.snapshot(model, settings.cloudEndpoint);
+    }
+    /** Measure the endpoints of the saved (or default) model now. */
+    async probe() {
+        const settings = this.settings.engine();
+        const model = await this.engine.cloud.resolveModel(settings.cloudModel);
+        try {
+            return await this.engine.cloud.probe(model, settings.cloudEndpoint);
+        }
+        catch (error) {
+            if (error instanceof DecisionError && error.code !== 'not_signed_in')
+                return this.engine.cloud.snapshot(model, settings.cloudEndpoint);
+            throw error;
+        }
+    }
+    /** Check an endpoint the user is about to lock against the model it will be saved with. */
+    async checkLock(model, endpoint) {
+        if (typeof endpoint !== 'string' || endpoint === '')
+            throw new DecisionError('invalid_request', 'endpoint is required');
+        await this.engine.cloud.checkEndpoint(await this.engine.cloud.resolveModel(typeof model === 'string' ? model : this.settings.engine().cloudModel), endpoint);
+    }
+    /** Time five real judgements of a sample call on one endpoint. */
+    async requestTest(endpoint, input) {
+        if (typeof endpoint !== 'string' || endpoint === '')
+            throw new DecisionError('invalid_request', 'endpoint is required');
+        if (typeof input !== 'object' || input === null)
+            throw new DecisionError('invalid_request', 'input is required');
+        const model = await this.engine.cloud.resolveModel(this.settings.engine().cloudModel);
+        return await this.engine.cloud.requestTest(model, endpoint, input);
+    }
+    installPack(pack, source) {
+        if (!isPackId(pack))
+            throw new DecisionError('invalid_request', `pack must be one of ${PACK_IDS.join(', ')}`);
+        const from = this.source(source);
+        return this.run('pack', pack, signal => installPack(this.home, pack, {
+            source: from, signal,
+            onProgress: progress => this.update(progress.phase === 'download'
+                ? { phase: 'download', done: progress.done, total: progress.total }
+                : { phase: progress.phase }),
+        }));
+    }
+    removePack(pack) {
+        if (!isPackId(pack))
+            throw new DecisionError('invalid_request', `pack must be one of ${PACK_IDS.join(', ')}`);
+        this.assertIdle();
+        // A running worker of this pack holds files open.
+        if (this.engine.local.status().selection?.pack === pack)
+            this.engine.local.stop();
+        return removePack(this.home, pack);
+    }
+    downloadModel(family, source) {
+        if (!MODEL_FAMILIES.includes(family))
+            throw new DecisionError('invalid_request', `model must be one of ${MODEL_FAMILIES.join(', ')}`);
+        if (!MODEL_SOURCES.includes(source))
+            throw new DecisionError('invalid_request', `source must be one of ${MODEL_SOURCES.join(', ')}`);
+        const model = MODEL_CATALOG.find(entry => entry.family === family);
+        const precision = preferredPrecision(model, recommend(detectHardware()).onnxPack);
+        if (precision === undefined)
+            throw new DecisionError('invalid_request', `${model.family} has no published package`);
+        return this.run('model-download', family, signal => downloadModel(this.home, model.family, precision, source, {
+            signal,
+            onProgress: (done, total) => this.update({ phase: 'download', done, total }),
+        }));
+    }
+    installModelDirectory(dir) {
+        if (typeof dir !== 'string' || dir.trim() === '')
+            throw new DecisionError('invalid_request', 'dir must name a model package directory');
+        return this.run('model-directory', dir, signal => installModelFromDirectory(this.home, dir.trim(), {
+            signal,
+            onProgress: (done, total) => this.update({ phase: 'verify', done, total }),
+        }));
+    }
+    removeModel(id) {
+        if (id === null || id === '')
+            throw new DecisionError('invalid_request', 'id is required');
+        this.assertIdle();
+        if (this.engine.local.status().selection?.model === id)
+            this.engine.local.stop();
+        return removeModel(this.home, id);
+    }
+    cancelJob() {
+        this.jobAbort?.abort(new DecisionError('invalid_request', 'cancelled'));
+    }
+    /** Judge a sample call with the saved settings, so the user sees the backend answer. */
+    async test(tool, args) {
+        if (typeof tool !== 'string' || tool === '' || typeof args !== 'object' || args === null || Array.isArray(args)) {
+            throw new DecisionError('invalid_request', 'tool must be a name and args an object');
+        }
+        return await this.engine.judge({ tool, arguments: args }, this.settings.engine());
+    }
+    /** One page of the decision log, newest first. */
+    recordPage(url) {
+        const param = (name) => {
+            const value = url.searchParams.get(name);
+            return value === null || value === '' ? undefined : value;
+        };
+        const limit = Number(param('limit') ?? PAGE_LIMIT_MAX);
+        if (!Number.isFinite(limit))
+            throw new DecisionError('invalid_request', 'limit must be a number');
+        const label = param('label');
+        const workspace = param('workspace');
+        const before = param('before');
+        return logged(() => this.records.page({
+            limit,
+            ...label === undefined ? {} : { label },
+            ...workspace === undefined ? {} : { workspace },
+            ...before === undefined ? {} : { before },
+            markedOnly: param('marked') === '1',
+        }));
+    }
+    /** Mark the label a record should have had, or clear the mark with null. */
+    markRecord(id, correction) {
+        if (typeof id !== 'string' || id === '')
+            throw new DecisionError('invalid_request', 'id is required');
+        if (correction !== null && !DECISIONS.includes(correction)) {
+            throw new DecisionError('invalid_request', `correction must be null or one of ${DECISIONS.join(', ')}`);
+        }
+        return logged(() => this.records.mark(id, correction));
+    }
+    exportRecords() {
+        return logged(() => this.records.export());
+    }
+    clearRecords() {
+        this.records.clear();
+    }
+    close() {
+        this.cancelJob();
+    }
+    source(value) {
+        if (value === null)
+            return this.settings.downloadSource();
+        if (!DOWNLOAD_SOURCES.includes(value))
+            throw new DecisionError('invalid_request', `source must be one of ${DOWNLOAD_SOURCES.join(', ')}`);
+        return value;
+    }
+    assertIdle() {
+        if (this.running())
+            throw new DecisionError('invalid_request', 'another install is running');
+    }
+    running() {
+        return this.job !== undefined && !['done', 'failed', 'cancelled'].includes(this.job.phase);
+    }
+    run(kind, target, work) {
+        this.assertIdle();
+        const abort = new AbortController();
+        this.jobAbort = abort;
+        this.job = { kind, target, phase: kind === 'model-directory' ? 'verify' : 'download', startedAt: Date.now() };
+        const job = this.job;
+        work(abort.signal).then(() => {
+            this.finish(job, { phase: 'done' });
+        }, (error) => {
+            this.finish(job, abort.signal.aborted ? { phase: 'cancelled' } : { phase: 'failed', error: messageOf(error) });
+        });
+        return job;
+    }
+    update(change) {
+        if (this.job !== undefined && this.running())
+            this.job = { ...this.job, ...change };
+    }
+    finish(started, change) {
+        if (this.job?.startedAt !== started.startedAt)
+            return;
+        const { done: _done, total: _total, ...rest } = this.job;
+        this.job = { ...rest, ...change };
+        this.jobAbort = undefined;
+    }
+}
+/** Every panel route: method, path below {@link ROUTE_PREFIX}, handler. */
+export const ROUTES = [
+    ['GET', 'state', panel => panel.state()],
+    ['GET', 'cloud/models', panel => panel.cloudModels()],
+    ['GET', 'cloud/endpoints', panel => panel.endpoints()],
+    ['POST', 'cloud/probe', panel => panel.probe()],
+    ['POST', 'cloud/check-lock', async (panel, request) => {
+            const body = await bodyOf(request);
+            return await panel.checkLock(body['model'], body['endpoint']);
+        }],
+    ['POST', 'cloud/test', async (panel, request) => {
+            const body = await bodyOf(request);
+            return await panel.requestTest(body['endpoint'], body['input']);
+        }],
+    ['POST', 'packs/install', async (panel, _request, url) => panel.installPack(url.searchParams.get('pack'), url.searchParams.get('source'))],
+    ['POST', 'packs/remove', async (panel, _request, url) => panel.removePack(url.searchParams.get('pack'))],
+    ['POST', 'models/download', async (panel, _request, url) => panel.downloadModel(url.searchParams.get('family'), url.searchParams.get('source'))],
+    ['POST', 'models/install-dir', async (panel, request) => panel.installModelDirectory((await bodyOf(request))['dir'])],
+    ['POST', 'models/remove', async (panel, _request, url) => panel.removeModel(url.searchParams.get('id'))],
+    ['POST', 'job/cancel', async (panel) => panel.cancelJob()],
+    ['POST', 'test', async (panel, request) => {
+            const body = await bodyOf(request);
+            return await panel.test(body['tool'], body['args']);
+        }],
+    ['GET', 'records', async (panel, _request, url) => panel.recordPage(url)],
+    ['POST', 'records/mark', async (panel, request) => {
+            const body = await bodyOf(request);
+            return panel.markRecord(body['id'], body['correction']);
+        }],
+    ['POST', 'records/export', async (panel) => panel.exportRecords()],
+    ['POST', 'records/clear', async (panel) => panel.clearRecords()],
+];
+/** Answer one panel request; failures carry their code, never a stack. */
+export async function handle(panel, handler, request) {
+    try {
+        const value = await handler(panel, request, new URL(request.url));
+        return Response.json({ ok: true, value: value ?? null }, { headers: { 'cache-control': 'no-store' } });
+    }
+    catch (error) {
+        const code = error instanceof DecisionError ? error.code : 'failed';
+        const status = code === 'invalid_request' ? 400 : code === 'not_signed_in' ? 401 : code === 'rate_limited' ? 429 : 500;
+        return Response.json({ ok: false, error: { code, message: messageOf(error) } }, { status, headers: { 'cache-control': 'no-store' } });
+    }
+}
+async function bodyOf(request) {
+    const value = await request.json().catch(() => undefined);
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        throw new DecisionError('invalid_request', 'the body must be a JSON object');
+    return value;
+}
+/** A decision log call; a record or filter the log does not know is the caller's mistake. */
+function logged(work) {
+    try {
+        return work();
+    }
+    catch (error) {
+        if (error instanceof RangeError)
+            throw new DecisionError('invalid_request', error.message);
+        throw error;
+    }
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/node_modules/@openvulcan/dsh-decision-guard/lib/records.d.ts

@@ -0,0 +1,133 @@
+/**
+ * The decision log: every call the decision model or the review LLM took part in, kept in one
+ * JSON Lines file in this plugin's data directory with a rolling limit. It is written only while
+ * the user's `recordDecisions` switch is on.
+ *
+ * A record keeps the call's arguments as the agent sent them, so the user can look back at what
+ * was judged and export the records they marked as training samples; clearing the log is the only
+ * way to remove it.
+ */
+import { type Decision, type DecisionHome, type DecisionOptions } from '@openvulcan/vulcan-decision';
+/** Most records the log keeps; older ones are dropped when the log is compacted. */
+export declare const RETENTION_RECORDS = 5000;
+/** Most days the log keeps a record. */
+export declare const RETENTION_DAYS = 30;
+/** Most records one page returns. */
+export declare const PAGE_LIMIT_MAX = 200;
+/** Log file name; the version changes whenever the line format changes, and other versions are not read. */
+export declare const RECORDS_FILE = "records.v1.jsonl";
+/**
+ * How a recorded call ended.
+ *
+ * - `judge_allowed` / `review_allowed`: the decision model or the review LLM let it run.
+ * - `review_denied`: the review LLM refused it without asking anyone (a forbid rule, or an
+ *   unattended session).
+ * - `unattended_denied`: nobody could be asked and no review allowed it.
+ * - `user_allowed` / `user_denied`: the user answered the approval prompt.
+ * - `approval_expired`: the approval countdown ran out.
+ * - `not_asked`: the user could not be asked, so the call was refused.
+ * - `host_denied`: another dsh integration refused the call before the user was asked.
+ */
+export type RecordOutcome = 'judge_allowed' | 'review_allowed' | 'review_denied' | 'unattended_denied' | 'user_allowed' | 'user_denied' | 'approval_expired' | 'not_asked' | 'host_denied';
+/** What the decision model read and produced, when the call could be rendered. */
+export interface RecordTrace {
+    readonly backend: 'cloud' | 'local';
+    /** Cloud model id or installed local model id; empty when the default cloud model did not resolve. */
+    readonly model: string;
+    /** Cloud endpoint id or local runtime pack, when the model answered. */
+    readonly via?: string;
+    readonly policyVersion: string;
+    readonly settings: DecisionOptions;
+    /** The call text the model read. */
+    readonly rendered: string;
+    /** Raw allow/review/block scores. */
+    readonly logits?: readonly number[];
+    readonly inputTokens?: number;
+}
+/** The decision model's part of one recorded call. */
+export interface RecordJudge {
+    /** Absent when the model could not answer. */
+    readonly label?: Decision;
+    /** Why the model could not answer. */
+    readonly error?: string;
+    /** Set when a rule decided without evaluating the model. */
+    readonly reasonCode?: string;
+    readonly elapsedMs: number;
+    readonly trace?: RecordTrace;
+}
+/** The review LLM's part of one recorded call. */
+export interface RecordReview {
+    /** Absent when the review failed. */
+    readonly verdict?: 'allow' | 'review' | 'deny' | 'forbid';
+    readonly reason?: string;
+    readonly error?: string;
+    readonly elapsedMs: number;
+}
+/** One recorded call. */
+export interface DecisionRecord {
+    readonly id: string;
+    /** When the call reached the gate, in Unix milliseconds. */
+    readonly judgedAtMs: number;
+    readonly sessionId: string;
+    readonly workspaceRoot?: string;
+    readonly toolName: string;
+    /** The arguments as the agent sent them, as JSON. */
+    readonly arguments: string;
+    /** Whether someone could be asked. */
+    readonly attended: boolean;
+    readonly judge: RecordJudge;
+    readonly review?: RecordReview;
+    readonly outcome: RecordOutcome;
+    /** The label the user says the decision model should have given. */
+    readonly correction?: Decision;
+}
+/** A finished call before it is given its identity. */
+export type NewRecord = Omit<DecisionRecord, 'id' | 'correction'>;
+/** One page request, newest first. */
+export interface PageRequest {
+    /** Model result to keep: a decision or `failed`. */
+    readonly label?: string;
+    readonly workspace?: string;
+    readonly markedOnly?: boolean;
+    /** Return records older than this record. */
+    readonly before?: string;
+    readonly limit: number;
+}
+export interface RecordPage {
+    readonly records: readonly DecisionRecord[];
+    readonly hasMore: boolean;
+    readonly total: number;
+    readonly marked: number;
+    /** Workspaces of every kept record, for the filter. */
+    readonly workspaces: readonly string[];
+    readonly retentionRecords: number;
+    readonly retentionDays: number;
+}
+export interface RecordExport {
+    readonly fileName: string;
+    /** JSON Lines training samples. */
+    readonly content: string;
+    readonly count: number;
+}
+/** The log; loaded on first use and kept in memory with the file as its authority. */
+export declare class RecordStore {
+    private readonly home;
+    private readonly now;
+    private loaded;
+    constructor(home: DecisionHome, now?: () => number);
+    /** Keep one finished call. */
+    append(record: NewRecord): DecisionRecord;
+    /** One page of matching records, newest first. */
+    page(request: PageRequest): RecordPage;
+    /** Mark the label the model should have given a record, or clear the mark with null. */
+    mark(id: string, correction: Decision | null): DecisionRecord;
+    /** Export the marked records that carry model input as training samples. */
+    export(): RecordExport;
+    /** Remove every record and the file; this also recovers from an unreadable file. */
+    clear(): void;
+    private path;
+    private records;
+    /** Read the file, dropping records past retention; a line that is not a record makes the whole file unreadable until it is cleared. */
+    private load;
+    private rewrite;
+}