@pellux/goodvibes-sdk 0.18.3 → 0.18.12

package/dist/_internal/platform/tools/shared/overflow.js

@@ -0,0 +1,363 @@
+import { mkdirSync, writeFileSync, readFileSync, readdirSync, unlinkSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { logger } from '../../utils/logger.js';
+import { summarizeError } from '../../utils/error-display.js';
+// ─── Constants ─────────────────────────────────────────────────────────────
+export const DEFAULT_MAX_CHARS = 50_000;
+const OVERFLOW_DIR = '.goodvibes/.overflow';
+const DEFAULT_RETENTION = {
+    maxAgeMs: 60 * 60 * 1000, // 1 hour
+    maxCount: Infinity,
+    maxSizeBytes: Infinity,
+};
+// ─── File Backend ────────────────────────────────────────────────────────────
+/**
+ * FileBackend — spills overflow content to `.goodvibes/.overflow/` on disk.
+ */
+export class FileBackend {
+    type = 'file';
+    overflowDir;
+    constructor(baseDir) {
+        this.overflowDir = join(baseDir, OVERFLOW_DIR);
+    }
+    ensureDir() {
+        try {
+            mkdirSync(this.overflowDir, { recursive: true });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    _safePath(id) {
+        if (id.includes('/') || id.includes('\\') || id.includes('\0') || id.includes('..'))
+            return null;
+        const resolved = join(this.overflowDir, id);
+        // Prevent path traversal — id must not escape overflowDir
+        return resolved.startsWith(this.overflowDir + '/') ? resolved : null;
+    }
+    write(filename, content) {
+        try {
+            if (!this.ensureDir())
+                return null;
+            const target = this._safePath(filename);
+            if (!target)
+                return null;
+            writeFileSync(target, content, 'utf-8');
+            return {
+                id: filename,
+                filename,
+                content,
+                sizeBytes: new TextEncoder().encode(content).length,
+                createdAt: Date.now(),
+                backendType: 'file',
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    read(id) {
+        const target = this._safePath(id);
+        if (!target)
+            return null;
+        try {
+            return readFileSync(target, 'utf-8');
+        }
+        catch {
+            return null;
+        }
+    }
+    cleanup(policy) {
+        const cfg = { ...DEFAULT_RETENTION, ...policy };
+        const now = Date.now();
+        let files;
+        try {
+            files = readdirSync(this.overflowDir);
+        }
+        catch {
+            return;
+        }
+        const entries = [];
+        for (const file of files) {
+            const p = join(this.overflowDir, file);
+            try {
+                const s = statSync(p);
+                entries.push({ file, path: p, mtimeMs: s.mtimeMs, size: s.size });
+            }
+            catch { }
+        }
+        entries.sort((a, b) => a.mtimeMs - b.mtimeMs);
+        const toDelete = new Set();
+        for (const e of entries) {
+            if (now - e.mtimeMs >= cfg.maxAgeMs)
+                toDelete.add(e.path);
+        }
+        const rem = entries.filter((e) => !toDelete.has(e.path));
+        if (cfg.maxCount !== Infinity && rem.length > cfg.maxCount) {
+            const excess = rem.length - cfg.maxCount;
+            for (let i = 0; i < excess; i++)
+                toDelete.add(rem[i].path);
+        }
+        const ac = entries.filter((e) => !toDelete.has(e.path));
+        if (cfg.maxSizeBytes !== Infinity) {
+            let total = ac.reduce((s, e) => s + e.size, 0);
+            for (const e of ac) {
+                if (total <= cfg.maxSizeBytes)
+                    break;
+                toDelete.add(e.path);
+                total -= e.size;
+            }
+        }
+        for (const p of toDelete) {
+            try {
+                unlinkSync(p);
+            }
+            catch { }
+        }
+    }
+    /** Lists all overflow entries. Reads file content eagerly — acceptable for small overflow directories. */
+    list() {
+        let files;
+        try {
+            files = readdirSync(this.overflowDir);
+        }
+        catch {
+            return [];
+        }
+        const result = [];
+        for (const file of files) {
+            const p = join(this.overflowDir, file);
+            try {
+                const s = statSync(p);
+                let content = '';
+                try {
+                    content = readFileSync(p, 'utf-8');
+                }
+                catch { }
+                result.push({ id: file, filename: file, content, sizeBytes: s.size, createdAt: s.mtimeMs, backendType: 'file' });
+            }
+            catch { }
+        }
+        return result;
+    }
+}
+// ─── Ledger Backend ──────────────────────────────────────────────────────────
+/**
+ * LedgerBackend — stores overflow entries in-process (Map).
+ * Ephemeral: entries are lost on process exit.
+ */
+export class LedgerBackend {
+    type = 'ledger';
+    entries = new Map();
+    write(filename, content) {
+        const entry = {
+            id: filename, filename, content,
+            sizeBytes: new TextEncoder().encode(content).length,
+            createdAt: Date.now(),
+            backendType: 'ledger',
+        };
+        this.entries.set(filename, entry);
+        return entry;
+    }
+    read(id) { return this.entries.get(id)?.content ?? null; }
+    cleanup(policy) {
+        const cfg = { ...DEFAULT_RETENTION, ...policy };
+        const now = Date.now();
+        const sorted = Array.from(this.entries.values()).sort((a, b) => a.createdAt - b.createdAt);
+        const toDelete = new Set();
+        for (const e of sorted) {
+            if (now - e.createdAt >= cfg.maxAgeMs)
+                toDelete.add(e.id);
+        }
+        const rem = sorted.filter((e) => !toDelete.has(e.id));
+        if (cfg.maxCount !== Infinity && rem.length > cfg.maxCount) {
+            const excess = rem.length - cfg.maxCount;
+            for (let i = 0; i < excess; i++)
+                toDelete.add(rem[i].id);
+        }
+        const ac = sorted.filter((e) => !toDelete.has(e.id));
+        if (cfg.maxSizeBytes !== Infinity) {
+            let total = ac.reduce((s, e) => s + e.sizeBytes, 0);
+            for (const e of ac) {
+                if (total <= cfg.maxSizeBytes)
+                    break;
+                toDelete.add(e.id);
+                total -= e.sizeBytes;
+            }
+        }
+        for (const id of toDelete)
+            this.entries.delete(id);
+    }
+    list() { return Array.from(this.entries.values()); }
+}
+// ─── Diagnostics Backend ─────────────────────────────────────────────────────
+/**
+ * DiagnosticsBackend — records overflow events as structured log entries.
+ * Does NOT store content; `read()` always returns null.
+ */
+export class DiagnosticsBackend {
+    type = 'diagnostics';
+    log = [];
+    write(filename, content) {
+        const sizeBytes = new TextEncoder().encode(content).length;
+        const createdAt = Date.now();
+        this.log.push({ id: filename, filename, sizeBytes, createdAt });
+        logger.info(`[overflow:diagnostics] spilled ${sizeBytes} bytes → ${filename}`);
+        return { id: filename, filename, content: '', sizeBytes, createdAt, backendType: 'diagnostics' };
+    }
+    read(_id) { return null; }
+    cleanup(policy) {
+        const cfg = { ...DEFAULT_RETENTION, ...policy };
+        const now = Date.now();
+        const sorted = [...this.log].sort((a, b) => a.createdAt - b.createdAt);
+        const toDelete = new Set();
+        for (const e of sorted) {
+            if (now - e.createdAt >= cfg.maxAgeMs)
+                toDelete.add(e.id);
+        }
+        const rem = sorted.filter((e) => !toDelete.has(e.id));
+        if (cfg.maxCount !== Infinity && rem.length > cfg.maxCount) {
+            const excess = rem.length - cfg.maxCount;
+            for (let i = 0; i < excess; i++)
+                toDelete.add(rem[i].id);
+        }
+        const ac = sorted.filter((e) => !toDelete.has(e.id));
+        if (cfg.maxSizeBytes !== Infinity) {
+            let total = ac.reduce((s, e) => s + e.sizeBytes, 0);
+            for (const e of ac) {
+                if (total <= cfg.maxSizeBytes)
+                    break;
+                toDelete.add(e.id);
+                total -= e.sizeBytes;
+            }
+        }
+        for (let i = this.log.length - 1; i >= 0; i--) {
+            if (toDelete.has(this.log[i].id))
+                this.log.splice(i, 1);
+        }
+    }
+    list() {
+        return this.log.map((e) => ({ ...e, content: '', backendType: 'diagnostics' }));
+    }
+}
+// ─── Backend Factory ─────────────────────────────────────────────────────────
+/**
+ * Create a spill backend by type. Defaults to `'file'`.
+ */
+export function createSpillBackend(type = 'file', baseDir) {
+    switch (type) {
+        case 'file':
+            if (!baseDir)
+                throw new Error('File spill backend requires an explicit baseDir');
+            return new FileBackend(baseDir);
+        case 'ledger': return new LedgerBackend();
+        case 'diagnostics': return new DiagnosticsBackend();
+        default: {
+            logger.info(`[overflow] Unknown spill backend "${String(type)}", falling back to file`);
+            if (!baseDir)
+                throw new Error('File spill backend requires an explicit baseDir');
+            return new FileBackend(baseDir);
+        }
+    }
+}
+// ─── OverflowHandler ────────────────────────────────────────────────────────
+/**
+ * Handles large tool output by delegating overflow content to a pluggable
+ * backend and returning a truncated version with a typed reference URI.
+ *
+ * Overflow references encode the backend type:
+ *   `file:.goodvibes/.overflow/{filename}`
+ *   `ledger:{filename}`
+ *   `diagnostics:{filename}`
+ *
+ * Never throws — on write failure, returns truncated content without ref.
+ */
+export class OverflowHandler {
+    backend;
+    retention;
+    constructor(config = {}) {
+        if (!config.backend && (config.spillBackend ?? 'file') === 'file' && !config.baseDir) {
+            throw new Error('OverflowHandler requires an explicit baseDir when using the file spill backend');
+        }
+        this.backend = config.backend ?? createSpillBackend(config.spillBackend ?? 'file', config.baseDir);
+        this.retention = { ...DEFAULT_RETENTION, ...config.retention };
+    }
+    sanitizeLabel(label) {
+        return label
+            .toLowerCase()
+            .replace(/[^a-z0-9-]/g, '-')
+            .replace(/-+/g, '-')
+            .replace(/^-|-$/g, '')
+            .slice(0, 40);
+    }
+    buildRef(filename) {
+        switch (this.backend.type) {
+            case 'file': return `file:${OVERFLOW_DIR}/${filename}`;
+            case 'ledger': return `ledger:${filename}`;
+            case 'diagnostics': return `diagnostics:${filename}`;
+            default: return `${this.backend.type}:${filename}`;
+        }
+    }
+    /**
+     * Handle potentially large content.
+     * Returns unchanged content if within limit.
+     * On overflow: delegates to active backend and returns typed ref.
+     */
+    handle(content, options) {
+        const maxChars = options?.maxChars ?? DEFAULT_MAX_CHARS;
+        if (content.length <= maxChars) {
+            return { content };
+        }
+        const label = this.sanitizeLabel(options?.label ?? 'output');
+        const filename = `${Date.now()}-${label}.txt`;
+        let entry;
+        try {
+            entry = this.backend.write(filename, content);
+        }
+        catch (err) {
+            logger.info(`[overflow] Backend write error: ${summarizeError(err)}`);
+            entry = null;
+        }
+        if (!entry) {
+            return {
+                content: content.slice(0, maxChars) + `\n[... truncated at ${maxChars} chars]`,
+            };
+        }
+        const ref = this.buildRef(filename);
+        const notice = this.backend.type === 'file'
+            ? `Full output: ${ref.replace(/^file:/, '')}`
+            : `Spilled to ${this.backend.type} backend (ref: ${ref})`;
+        return {
+            content: content.slice(0, maxChars) + `\n[... truncated. ${notice}]`,
+            overflowRef: ref,
+            spillBackend: this.backend.type,
+        };
+    }
+    /**
+     * Prune entries that violate the retention policy.
+     */
+    cleanup(policy) {
+        this.backend.cleanup({ ...this.retention, ...policy });
+    }
+    /** List current overflow entries from the active backend. */
+    list() {
+        return this.backend.list();
+    }
+    /** Return the active backend type. */
+    get backendType() {
+        return this.backend.type;
+    }
+}
+// ─── Operator Cleanup Command ────────────────────────────────────────────────
+/**
+ * overflowCleanup — operator-facing cleanup command.
+ *
+ * Prunes overflow entries from the provided overflow handler.
+ * Suitable for scripted operator invocations (e.g. CLI, cron).
+ */
+export function overflowCleanup(handler, policy) {
+    const beforeCount = handler.list().length;
+    handler.cleanup(policy);
+    return { beforeCount };
+}

package/dist/_internal/platform/tools/shared/process-manager.d.ts

@@ -0,0 +1,62 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+/**
+ * ProcessManager — tracks background processes for a single GoodVibes runtime.
+ *
+ * Extracted from tools/exec/index.ts so that other modules (UI, agent system,
+ * live-tail) can query running processes without importing the exec tool.
+ */
+export interface BackgroundProcess {
+    id: string;
+    pid: number;
+    cmd: string;
+    startTime: number;
+    stdout: string[];
+    stderr: string[];
+    exitCode: number | null;
+    done: boolean;
+}
+export interface BgCommandResult {
+    cmd: string;
+    exit_code: number | null;
+    stdout: string;
+    stderr: string;
+    success: boolean;
+    process_id?: string;
+    pid?: number;
+}
+export declare class ProcessManager {
+    private _counter;
+    private _processes;
+    private _procs;
+    private newId;
+    /**
+     * Spawn a background process and start collecting its output.
+     * Returns a BgCommandResult with the process_id and pid.
+     */
+    spawn(cmd: string, cwd: string | undefined, env: Record<string, string> | undefined): BgCommandResult;
+    /** Get the status record for a background process, or undefined if not found. */
+    getStatus(id: string): BackgroundProcess | undefined;
+    /** Get the accumulated stdout/stderr for a background process. */
+    getOutput(id: string): {
+        stdout: string;
+        stderr: string;
+    } | undefined;
+    /**
+     * Stop a background process by ID.
+     * Returns true if the process was found and stopped, false if unknown.
+     */
+    stop(id: string): boolean;
+    /** List all tracked background processes with their status summaries. */
+    list(): Array<{
+        id: string;
+        pid: number;
+        cmd: string;
+        status: string;
+    }>;
+    /**
+     * Handle bg_status / bg_output / bg_stop / bg_list special commands.
+     * Returns a BgCommandResult if the command was handled, null otherwise.
+     */
+    handleCommand(cmd: string): BgCommandResult | null;
+}
+//# sourceMappingURL=process-manager.d.ts.map

package/dist/_internal/platform/tools/shared/process-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-manager.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/tools/shared/process-manager.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAErF;;;;;GAKG;AAIH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,EAAE,OAAO,CAAC;CACf;AAID,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAID,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,UAAU,CAAwC;IAC1D,OAAO,CAAC,MAAM,CAAmD;IAIjE,OAAO,CAAC,KAAK;IAMb;;;OAGG;IACH,KAAK,CACH,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,GACtC,eAAe;IAqDlB,iFAAiF;IACjF,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAIpD,kEAAkE;IAClE,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS;IASrE;;;OAGG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAczB,yEAAyE;IACzE,IAAI,IAAI,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IASvE;;;OAGG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI;CAmDnD"}

package/dist/_internal/platform/tools/shared/process-manager.js

@@ -0,0 +1,155 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+// ─── ProcessManager ───────────────────────────────────────────────────────────
+export class ProcessManager {
+    _counter = 0;
+    _processes = new Map();
+    _procs = new Map();
+    // ─── Private helpers ────────────────────────────────────────────────────────
+    newId() {
+        return `bg_${++this._counter}_${Date.now()}`;
+    }
+    // ─── Public API ─────────────────────────────────────────────────────────────
+    /**
+     * Spawn a background process and start collecting its output.
+     * Returns a BgCommandResult with the process_id and pid.
+     */
+    spawn(cmd, cwd, env) {
+        const id = this.newId();
+        const entry = {
+            id,
+            pid: 0,
+            cmd,
+            startTime: Date.now(),
+            stdout: [],
+            stderr: [],
+            exitCode: null,
+            done: false,
+        };
+        this._processes.set(id, entry);
+        const cleanEnv = Object.fromEntries(Object.entries(process.env).filter(([, v]) => v !== undefined));
+        const mergedEnv = { ...cleanEnv, ...env };
+        const proc = Bun.spawn(['/bin/sh', '-c', cmd], {
+            cwd,
+            env: mergedEnv,
+            stdout: 'pipe',
+            stderr: 'pipe',
+        });
+        entry.pid = proc.pid;
+        this._procs.set(id, proc);
+        // Async collection — fire and forget, stored in entry
+        void (async () => {
+            const [stdoutText, stderrText] = await Promise.all([
+                new Response(proc.stdout).text(),
+                new Response(proc.stderr).text(),
+            ]);
+            entry.stdout.push(stdoutText);
+            entry.stderr.push(stderrText);
+            entry.exitCode = await proc.exited;
+            entry.done = true;
+            this._procs.delete(id);
+        })();
+        return {
+            cmd,
+            exit_code: null,
+            stdout: '',
+            stderr: '',
+            success: true,
+            process_id: id,
+            pid: proc.pid,
+        };
+    }
+    /** Get the status record for a background process, or undefined if not found. */
+    getStatus(id) {
+        return this._processes.get(id);
+    }
+    /** Get the accumulated stdout/stderr for a background process. */
+    getOutput(id) {
+        const entry = this._processes.get(id);
+        if (!entry)
+            return undefined;
+        return {
+            stdout: entry.stdout.join(''),
+            stderr: entry.stderr.join(''),
+        };
+    }
+    /**
+     * Stop a background process by ID.
+     * Returns true if the process was found and stopped, false if unknown.
+     */
+    stop(id) {
+        const entry = this._processes.get(id);
+        if (!entry)
+            return false;
+        const liveProc = this._procs.get(id);
+        if (liveProc && !entry.done) {
+            try {
+                liveProc.kill('SIGTERM');
+            }
+            catch { /* already exited */ }
+        }
+        entry.done = true;
+        this._procs.delete(id);
+        this._processes.delete(id);
+        return true;
+    }
+    /** List all tracked background processes with their status summaries. */
+    list() {
+        return Array.from(this._processes.values()).map((e) => ({
+            id: e.id,
+            pid: e.pid,
+            cmd: e.cmd,
+            status: e.done ? `done (exit ${e.exitCode})` : 'running',
+        }));
+    }
+    /**
+     * Handle bg_status / bg_output / bg_stop / bg_list special commands.
+     * Returns a BgCommandResult if the command was handled, null otherwise.
+     */
+    handleCommand(cmd) {
+        // bg_status <id>
+        const statusMatch = cmd.match(/^bg_status\s+(\S+)$/);
+        if (statusMatch) {
+            const entry = this._processes.get(statusMatch[1]);
+            if (!entry) {
+                return { cmd, exit_code: 1, stdout: '', stderr: `Unknown process: ${statusMatch[1]}`, success: false };
+            }
+            const status = entry.done ? `done (exit ${entry.exitCode})` : 'running';
+            return {
+                cmd,
+                exit_code: 0,
+                stdout: JSON.stringify({ id: entry.id, pid: entry.pid, cmd: entry.cmd, status }),
+                stderr: '',
+                success: true,
+            };
+        }
+        // bg_output <id>
+        const outputMatch = cmd.match(/^bg_output\s+(\S+)$/);
+        if (outputMatch) {
+            const entry = this._processes.get(outputMatch[1]);
+            if (!entry) {
+                return { cmd, exit_code: 1, stdout: '', stderr: `Unknown process: ${outputMatch[1]}`, success: false };
+            }
+            return {
+                cmd,
+                exit_code: 0,
+                stdout: entry.stdout.join(''),
+                stderr: entry.stderr.join(''),
+                success: true,
+            };
+        }
+        // bg_stop <id>
+        const stopMatch = cmd.match(/^bg_stop\s+(\S+)$/);
+        if (stopMatch) {
+            const found = this.stop(stopMatch[1]);
+            if (!found) {
+                return { cmd, exit_code: 1, stdout: '', stderr: `Unknown process: ${stopMatch[1]}`, success: false };
+            }
+            return { cmd, exit_code: 0, stdout: `Stopped ${stopMatch[1]}`, stderr: '', success: true };
+        }
+        // bg_list
+        if (cmd.trim() === 'bg_list') {
+            return { cmd, exit_code: 0, stdout: JSON.stringify(this.list()), stderr: '', success: true };
+        }
+        return null;
+    }
+}

package/dist/_internal/platform/tools/shared/schema-fingerprint.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Output schema fingerprint utility.
+ *
+ * Provides stable SHA-256 fingerprints derived from the sorted key set of a
+ * tool result object. The same output mode / input class always produces the
+ * same fingerprint because the hash is computed from the sorted key names, not
+ * from the values — making it a schema-level identity rather than a content hash.
+ *
+ * Integration pattern:
+ *   1. After a mode-specific result is produced, call `appendSchemaFingerprint`.
+ *   2. The `_meta.outputSchemaFingerprint` field is appended to the result object.
+ *   3. When the feature flag is disabled the result object is returned unchanged.
+ */
+import type { FeatureFlagManager } from '../../runtime/feature-flags/index.js';
+export interface SchemaFingerprintOptions {
+    readonly featureFlags?: Pick<FeatureFlagManager, 'isEnabled'> | null;
+}
+/**
+ * Checks the runtime feature flags explicitly supplied by the composition root.
+ */
+export declare function isSchemaFingerprintEnabled(options?: SchemaFingerprintOptions): boolean;
+/**
+ * Canonical schema shape IDs per tool and output mode.
+ *
+ * The shape ID is the stable, human-readable identifier for what the schema
+ * looks like before the hash is computed. It encodes the tool name and mode
+ * so that diagnostics can group / filter by shape without needing to know the
+ * full fingerprint.
+ */
+export declare const SCHEMA_SHAPE_IDS: Record<string, string>;
+/**
+ * Returns the canonical shape ID for a given tool and mode combination.
+ * Falls back to `<tool>.<mode>.v1` for unknown combinations.
+ */
+export declare function getSchemaShapeId(tool: string, mode: string): string;
+/**
+ * Compute a stable SHA-256 fingerprint from the sorted top-level key names of
+ * a result object.
+ *
+ * The hash input is the JSON-serialised sorted key array, e.g.:
+ *   `["count","files"]` → sha256 → hex string
+ *
+ * Because the hash is over keys only (not values), the same schema shape
+ * always produces the same fingerprint regardless of runtime content.
+ *
+ * Uses the Web Crypto API (available in Bun via globalThis.crypto).
+ */
+export declare function computeSchemaFingerprint(result: Record<string, unknown>): Promise<string>;
+/**
+ * Synchronous variant using the synchronous `crypto.subtle.digestSync` API
+ * available in Bun. Falls back to a deterministic key-sort string when the
+ * sync API is not available (e.g. in Node.js test environments without
+ * polyfilling).
+ *
+ * This is the preferred variant for tool `execute()` paths where async is
+ * already available, but a sync escape hatch is provided for contexts where
+ * adding `await` is impractical.
+ */
+export declare function computeSchemaFingerprintSync(result: Record<string, unknown>): string;
+/**
+ * Schema fingerprint metadata appended to tool results.
+ */
+export interface SchemaFingerprintMeta {
+    /** Canonical shape ID (human-readable, e.g. `find.files.v1`). */
+    schemaShapeId: string;
+    /** SHA-256 hex (64 chars) in Bun; FNV-1a hex (8 chars) in non-Bun environments. */
+    outputSchemaFingerprint: string;
+}
+/**
+ * Append `_meta.outputSchemaFingerprint` to a result object when the feature
+ * flag is enabled. Returns the original object unchanged when the flag is
+ * disabled.
+ *
+ * @param result   The mode result object (plain, not yet JSON-stringified).
+ * @param tool     Tool name: `'find'`, `'analyze'`, or `'inspect'`.
+ * @param mode     The active output mode string (e.g. `'files'`, `'impact'`).
+ * @returns        The augmented (or original) result object.
+ */
+export declare function appendSchemaFingerprint(result: Record<string, unknown>, tool: string, mode: string, options?: SchemaFingerprintOptions): Record<string, unknown>;
+//# sourceMappingURL=schema-fingerprint.d.ts.map

package/dist/_internal/platform/tools/shared/schema-fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-fingerprint.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/tools/shared/schema-fingerprint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAE/E,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,WAAW,CAAC,GAAG,IAAI,CAAC;CACtE;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,GAAE,wBAA6B,GAAG,OAAO,CAE1F;AAID;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAgDnD,CAAC;AAEF;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGnE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,MAAM,CAAC,CAQjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,CAyBR;AAID;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,iEAAiE;IACjE,aAAa,EAAE,MAAM,CAAC;IACtB,mFAAmF;IACnF,uBAAuB,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,wBAA6B,GACrC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqBzB"}