@khorsheed/dsh-file-preview 0.1.0

package/lib/types/fold.d.ts

@@ -0,0 +1,77 @@
+/** Pure log fold over the files a session read, wrote, or edited. @module @khorsheed/dsh-file-preview/fold */
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import type { FilePreviewList, FilePreviewOp } from './types.ts';
+/** The extracted touch operation and display path of one tool call. */
+export interface FilePreviewCallTarget {
+    /** The operation the tool performs. */
+    readonly op: FilePreviewOp;
+    /** The display path recorded in the call arguments. */
+    readonly path: string;
+}
+/** One write/edit diff captured from a tool result's presentation meta. */
+export type FilePreviewResultDiff = {
+    /** The changed file's path (the same display path the call recorded). */
+    readonly path: string;
+    /** Prior content, or null for a new file / an overwrite. */
+    readonly oldText: string | null;
+    /** Content after the change. */
+    readonly newText: string;
+};
+/** Extract the touched path and operation from one tool call's raw arguments JSON. */
+export declare function pathFromToolCall(name: string, argumentsJson: string): FilePreviewCallTarget | undefined;
+/** Read the write/edit diff list out of a tool result's tool-private meta. */
+export declare function diffsFromResultMeta(meta: unknown): readonly FilePreviewResultDiff[] | undefined;
+/**
+ * Fold a session's events into the files it read, wrote, or edited, in
+ * first-seen order and deduplicated by display path; a later occurrence
+ * refreshes the entry's op and location without moving it, and each write/edit
+ * tool result appends its change's diff to the entry's `diffs` in event order.
+ * Nested Code Mode file dispatches (`tool/code-dispatch` events) count too —
+ * they carry no turn/step of their own, so the entry borrows the enclosing
+ * root call's location.
+ * @param events - the session's events in ascending seq order.
+ * @param maxFiles - cap on returned entries; excess files are dropped in
+ *   first-seen order after the cap is reached.
+ * @returns the capped list plus the last scanned seq and the truncation flag.
+ */
+export declare function foldFilePreview(events: readonly SessionEvent[], maxFiles: number): FilePreviewList;
+/** Lines in one diff text: a trailing newline terminates the last line rather than adding one. */
+export declare function lineCount(text: string): number;
+/** One file's mutation facts within one turn — the turn card's vocabulary. */
+export interface TurnFileFact {
+    readonly path: string;
+    /** Seq of the first mutation recorded for this path in this turn (stable ordering). */
+    readonly seq: number;
+    readonly step: number;
+    /** Lines added across the turn's mutations of this path. */
+    readonly added?: number;
+    /** Lines removed; absent when any mutation reported no prior content (create/overwrite). */
+    readonly removed?: number;
+}
+/** Per-turn file maps: turn number → path → mutation facts (first-seen within the turn). */
+export type TurnFilesByTurn = ReadonlyMap<number, ReadonlyMap<string, TurnFileFact>>;
+/**
+ * Fold a session's events into per-turn file-mutation maps — the turn card's
+ * single source of truth. Unlike {@link foldFilePreview}, this does NOT dedupe
+ * a path to its last occurrence: a file touched in two turns appears in BOTH
+ * turn maps, so each turn's card lists exactly what that turn mutated.
+ * write/edit calls register with their own turn; nested Code Mode dispatches
+ * borrow the enclosing root call's turn (dispatch events carry none); a
+ * `tool/result` whose presentation meta carries diffs registers its paths (the
+ * render-intent vocabulary) with the result's turn, and per-turn line deltas
+ * are summed from the diffs. A `write` whose result carries no diffs is a
+ * create (the write tool records no diffs when the file had no prior content):
+ * its full written content — read from the call arguments, which the log keeps
+ * — is the added-line count, once per file per turn.
+ *
+ * Count discipline: a write/edit tool/call only registers the path's location
+ * and never touches counts (its counted result follows); the first count
+ * contribution for a turn+path is adopted verbatim, later ones accumulate per
+ * field with unknown-wins — an uncounted mutation (a Code Mode dispatch, or a
+ * diff whose side reports no prior content) poisons that field to undefined
+ * rather than reporting a misleading partial.
+ * @param events - the session's events in ascending seq order.
+ * @returns turn → path → facts, in event order per turn.
+ */
+export declare function foldFilePreviewByTurn(events: readonly SessionEvent[]): TurnFilesByTurn;
+//# sourceMappingURL=fold.d.ts.map

package/lib/types/fold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fold.d.ts","sourceRoot":"","sources":["../../src/fold.ts"],"names":[],"mappings":"AAAA,8GAA8G;AAE9G,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAG5D,OAAO,KAAK,EAAqC,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAQnG,uEAAuE;AACvE,MAAM,WAAW,qBAAqB;IACpC,uCAAuC;IACvC,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAA;IAC1B,uDAAuD;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,2EAA2E;AAC3E,MAAM,MAAM,qBAAqB,GAAG;IAClC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,gCAAgC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB,CAAA;AAmBD,sFAAsF;AACtF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS,CAOvG;AAED,8EAA8E;AAC9E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,qBAAqB,EAAE,GAAG,SAAS,CAc/F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,eAAe,CA8DlG;AAED,kGAAkG;AAClG,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI9C;AAED,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,uFAAuF;IACvF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,4FAA4F;IAC5F,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,4FAA4F;AAC5F,MAAM,MAAM,eAAe,GAAG,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAA;AAuCpF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,eAAe,CAyHtF"}

package/lib/types/fold.js

@@ -0,0 +1,309 @@
+/** Pure log fold over the files a session read, wrote, or edited. @module @khorsheed/dsh-file-preview/fold */
+/** Tool names whose calls record a touched file path. */
+const FILE_TOOL_NAMES = new Set(['read', 'write', 'edit']);
+/** The argument key carrying the touched path (shared by all three file tools). */
+const FILE_PATH_ARGUMENT = 'file_path';
+/**
+ * Extract the touched path and operation from parsed file-tool arguments.
+ * @param name - the tool name.
+ * @param args - the parsed arguments payload (an object when well-formed).
+ * @returns the touch target, or undefined when the call is not a file touch.
+ */
+function targetFromArguments(name, args) {
+    if (!FILE_TOOL_NAMES.has(name))
+        return undefined;
+    if (args !== null && typeof args === 'object') {
+        const candidate = args[FILE_PATH_ARGUMENT];
+        if (typeof candidate === 'string' && candidate.length > 0) {
+            return { op: name, path: candidate };
+        }
+    }
+    return undefined;
+}
+/** Extract the touched path and operation from one tool call's raw arguments JSON. */
+export function pathFromToolCall(name, argumentsJson) {
+    try {
+        return targetFromArguments(name, JSON.parse(argumentsJson));
+    }
+    catch {
+        // Model arguments are expected JSON; a malformed payload contributes no path.
+        return undefined;
+    }
+}
+/** Read the write/edit diff list out of a tool result's tool-private meta. */
+export function diffsFromResultMeta(meta) {
+    if (meta === null || typeof meta !== 'object')
+        return undefined;
+    const diffs = meta.diffs;
+    if (!Array.isArray(diffs) || diffs.length === 0)
+        return undefined;
+    const result = [];
+    for (const item of diffs) {
+        if (item === null || typeof item !== 'object')
+            return undefined;
+        const { path, oldText, newText } = item;
+        if (typeof path !== 'string' || path.length === 0)
+            return undefined;
+        if (typeof newText !== 'string')
+            return undefined;
+        if (oldText !== null && typeof oldText !== 'string')
+            return undefined;
+        result.push({ path, oldText, newText });
+    }
+    return result;
+}
+/**
+ * Fold a session's events into the files it read, wrote, or edited, in
+ * first-seen order and deduplicated by display path; a later occurrence
+ * refreshes the entry's op and location without moving it, and each write/edit
+ * tool result appends its change's diff to the entry's `diffs` in event order.
+ * Nested Code Mode file dispatches (`tool/code-dispatch` events) count too —
+ * they carry no turn/step of their own, so the entry borrows the enclosing
+ * root call's location.
+ * @param events - the session's events in ascending seq order.
+ * @param maxFiles - cap on returned entries; excess files are dropped in
+ *   first-seen order after the cap is reached.
+ * @returns the capped list plus the last scanned seq and the truncation flag.
+ */
+export function foldFilePreview(events, maxFiles) {
+    const entries = new Map();
+    /** Root tool/call locations, so nested code dispatches borrow their turn/step. */
+    const callSites = new Map();
+    let asOfSeq = -1;
+    /** Upsert one touched path, refreshing a repeat in place and keeping its diffs. */
+    const record = (target, seq, turn, step) => {
+        const next = { path: target.path, op: target.op, seq, turn, step, diffs: [] };
+        const existing = entries.get(target.path);
+        if (existing === undefined && entries.size >= maxFiles)
+            return;
+        entries.set(target.path, existing === undefined ? next : { ...existing, ...next, diffs: existing.diffs });
+    };
+    for (const event of events) {
+        asOfSeq = event.seq;
+        if (event.type === 'tool/call') {
+            callSites.set(String(event.data.callId), { turn: event.data.turn, step: event.data.step });
+            const target = pathFromToolCall(event.data.name, event.data.arguments);
+            if (target === undefined)
+                continue;
+            record(target, event.seq, event.data.turn, event.data.step);
+            continue;
+        }
+        if (event.type === 'tool/code-dispatch') {
+            // The dispatch event IS the settled outcome: a failed sub-call changed
+            // nothing, so only successful file touches record.
+            if (event.data.isError)
+                continue;
+            const target = targetFromArguments(event.data.name, event.data.arguments);
+            if (target === undefined)
+                continue;
+            const site = callSites.get(String(event.data.rootCallId)) ?? { turn: 0, step: 0 };
+            record(target, event.seq, site.turn, site.step);
+            continue;
+        }
+        if (event.type === 'tool/result') {
+            const diffs = diffsFromResultMeta(event.data.meta);
+            if (diffs === undefined)
+                continue;
+            for (const diff of diffs) {
+                // The render-intent vocabulary: a result diff registers its path even
+                // when no write/edit call recorded it (non-write/edit mutation tools
+                // like the official deliverables' follow-along locations).
+                if (!entries.has(diff.path)) {
+                    record({ op: 'edit', path: diff.path }, event.seq, event.data.turn, event.data.step);
+                }
+                const entry = entries.get(diff.path);
+                if (entry === undefined)
+                    continue;
+                const change = {
+                    seq: event.seq,
+                    turn: event.data.turn,
+                    step: event.data.step,
+                    oldText: diff.oldText,
+                    newText: diff.newText,
+                };
+                entries.set(diff.path, { ...entry, diffs: [...entry.diffs, change] });
+            }
+        }
+    }
+    return {
+        entries: [...entries.values()].map((entry) => {
+            const last = entry.diffs[entry.diffs.length - 1];
+            return last === undefined ? entry : { ...entry, lastDiff: { oldText: last.oldText, newText: last.newText } };
+        }),
+        asOfSeq,
+        truncated: entries.size >= maxFiles,
+    };
+}
+/** Lines in one diff text: a trailing newline terminates the last line rather than adding one. */
+export function lineCount(text) {
+    if (text === '')
+        return 0;
+    const lines = text.split('\n').length;
+    return text.endsWith('\n') ? lines - 1 : lines;
+}
+/** Sum two optional counts; unknown wins (any uncounted mutation reports no total). */
+function sumKnown(a, b) {
+    return a === undefined || b === undefined ? undefined : a + b;
+}
+/** Extract the full written content from a `write` tool call's arguments JSON. */
+function contentFromWriteCall(argumentsJson) {
+    try {
+        const args = JSON.parse(argumentsJson);
+        if (args !== null && typeof args === 'object') {
+            const content = args.content;
+            if (typeof content === 'string')
+                return content;
+        }
+    }
+    catch {
+        // Model arguments are expected JSON; a malformed payload has no content.
+    }
+    return undefined;
+}
+/** Read the tool-result block's call identity and failure flag off a result message. */
+function resultCallFacts(message) {
+    const block = message.content[0];
+    if (block?.type !== 'tool-result' || typeof block.toolCallId !== 'string')
+        return undefined;
+    return { callId: block.toolCallId, isError: block.isError === true };
+}
+/**
+ * Fold a session's events into per-turn file-mutation maps — the turn card's
+ * single source of truth. Unlike {@link foldFilePreview}, this does NOT dedupe
+ * a path to its last occurrence: a file touched in two turns appears in BOTH
+ * turn maps, so each turn's card lists exactly what that turn mutated.
+ * write/edit calls register with their own turn; nested Code Mode dispatches
+ * borrow the enclosing root call's turn (dispatch events carry none); a
+ * `tool/result` whose presentation meta carries diffs registers its paths (the
+ * render-intent vocabulary) with the result's turn, and per-turn line deltas
+ * are summed from the diffs. A `write` whose result carries no diffs is a
+ * create (the write tool records no diffs when the file had no prior content):
+ * its full written content — read from the call arguments, which the log keeps
+ * — is the added-line count, once per file per turn.
+ *
+ * Count discipline: a write/edit tool/call only registers the path's location
+ * and never touches counts (its counted result follows); the first count
+ * contribution for a turn+path is adopted verbatim, later ones accumulate per
+ * field with unknown-wins — an uncounted mutation (a Code Mode dispatch, or a
+ * diff whose side reports no prior content) poisons that field to undefined
+ * rather than reporting a misleading partial.
+ * @param events - the session's events in ascending seq order.
+ * @returns turn → path → facts, in event order per turn.
+ */
+export function foldFilePreviewByTurn(events) {
+    const byTurn = new Map();
+    /** Root tool/call locations, so nested code dispatches borrow their turn/step. */
+    const callSites = new Map();
+    /** Write-tool calls keyed by callId (create fallback; see {@link WriteCallFacts}). */
+    const writeCalls = new Map();
+    /** Every path the session log has written/edited or diff-reported so far
+     *  (create discrimination: a first-touch write is a create). */
+    const sessionSeen = new Set();
+    /** Turn+path keys that have received a line-count contribution. */
+    const counted = new Set();
+    const countKey = (turn, path) => `${turn}:${path}`;
+    const turnMap = (turn) => {
+        let map = byTurn.get(turn);
+        if (map === undefined) {
+            map = new Map();
+            byTurn.set(turn, map);
+        }
+        return map;
+    };
+    /** Upsert a path's location without touching its line counts: a write/edit
+     *  tool/call precedes its counted result, so it must neither wipe counts a
+     *  sibling mutation contributed nor adopt anything itself. */
+    const recordLocation = (path, turn, seq, step) => {
+        const map = turnMap(turn);
+        const existing = map.get(path);
+        map.set(path, existing === undefined ? { path, seq, step } : { ...existing, seq, step });
+    };
+    /** Apply one mutation's line-count contribution. The first contribution for
+     *  a turn+path is adopted verbatim (a count-less placeholder from a
+     *  preceding tool/call must not poison it); later contributions accumulate
+     *  per field with unknown-wins. `unknown` marks an uncountable mutation (a
+     *  Code Mode dispatch): it poisons both fields. */
+    const recordContribution = (path, turn, seq, step, added, removed, unknown) => {
+        const map = turnMap(turn);
+        const key = countKey(turn, path);
+        if (unknown) {
+            counted.add(key);
+            map.set(path, { path, seq, step });
+            return;
+        }
+        const existing = map.get(path);
+        if (!counted.has(key)) {
+            counted.add(key);
+            map.set(path, {
+                path, seq, step,
+                ...(added === undefined ? {} : { added }),
+                ...(removed === undefined ? {} : { removed }),
+            });
+            return;
+        }
+        // Narrow the optional totals before the conditional spread so the fact
+        // never carries an explicit `undefined` (exactOptionalPropertyTypes).
+        const mergedAdded = added === undefined ? undefined : sumKnown(existing?.added, added);
+        const mergedRemoved = removed === undefined ? undefined : sumKnown(existing?.removed, removed);
+        map.set(path, {
+            path, seq, step,
+            ...(mergedAdded === undefined ? {} : { added: mergedAdded }),
+            ...(mergedRemoved === undefined ? {} : { removed: mergedRemoved }),
+        });
+    };
+    for (const event of events) {
+        if (event.type === 'tool/call') {
+            callSites.set(String(event.data.callId), { turn: event.data.turn, step: event.data.step });
+            const target = pathFromToolCall(event.data.name, event.data.arguments);
+            if (target === undefined)
+                continue;
+            if (target.op === 'write') {
+                const content = contentFromWriteCall(event.data.arguments);
+                if (content !== undefined) {
+                    const firstTouch = !sessionSeen.has(target.path);
+                    sessionSeen.add(target.path);
+                    writeCalls.set(String(event.data.callId), { path: target.path, content, firstTouch });
+                }
+            }
+            recordLocation(target.path, event.data.turn, event.seq, event.data.step);
+            continue;
+        }
+        if (event.type === 'tool/code-dispatch') {
+            // The dispatch event IS the settled outcome: a failed sub-call changed
+            // nothing, so only successful file touches record. Code Mode writes are
+            // uncountable (no result diffs reach the session), so they register the
+            // path and poison the line-count totals (unknown wins).
+            if (event.data.isError)
+                continue;
+            const target = targetFromArguments(event.data.name, event.data.arguments);
+            if (target === undefined)
+                continue;
+            const site = callSites.get(String(event.data.rootCallId)) ?? { turn: 0, step: 0 };
+            sessionSeen.add(target.path);
+            recordContribution(target.path, site.turn, event.seq, site.step, undefined, undefined, true);
+            continue;
+        }
+        if (event.type === 'tool/result') {
+            const diffs = diffsFromResultMeta(event.data.meta);
+            if (diffs !== undefined) {
+                for (const diff of diffs) {
+                    sessionSeen.add(diff.path);
+                    recordContribution(diff.path, event.data.turn, event.seq, event.data.step, lineCount(diff.newText), diff.oldText === null ? undefined : lineCount(diff.oldText), false);
+                }
+                continue;
+            }
+            // Create fallback: a first-touch write whose result carries no diff meta
+            // — the write tool records no diffs when the file had no prior content —
+            // contributed the whole written content, so the full content IS the
+            // added-line count and a create removes 0. A later empty-meta write to
+            // the same path (an overwrite whose prior content was not diffable)
+            // contributes nothing rather than double-counting.
+            const call = resultCallFacts(event.data.message);
+            const write = call === undefined ? undefined : writeCalls.get(call.callId);
+            if (write === undefined || !write.firstTouch || call?.isError === true)
+                continue;
+            recordContribution(write.path, event.data.turn, event.seq, event.data.step, lineCount(write.content), 0, false);
+        }
+    }
+    return byTurn;
+}

package/lib/types/index.d.ts

@@ -0,0 +1,105 @@
+/** Read-only file-preview Remote service over live sessions and the filesystem.
+ * @module @khorsheed/dsh-file-preview
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import z from '@deepseek-ai/schemastery';
+import type { FilePreviewConfig, FilePreviewList, FilePreviewRead, FilePreviewReveal, FilePreviewTurnMap } from './types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        filePreview: FilePreviewService;
+    }
+}
+/**
+ * The `filePreview` Remote service: session-scoped read-only file inspection
+ * for web surfaces. `list` is a pure fold over the session log (no filesystem
+ * access); `read` resolves the path against the session cwd and serves current
+ * text content through `ctx.fs` (or a browser URL for images), capped by
+ * config. Image bytes ride a dedicated host route so the browser loads them
+ * natively without bloating the RPC channel.
+ */
+export declare class FilePreviewService extends TypertRemoteService {
+    static inject: string[];
+    static Config: z<FilePreviewConfig>;
+    /** URL prefix the image route answers under. */
+    static readonly IMAGE_ROUTE = "/file-preview-image";
+    private readonly resolved;
+    /** Whether a web server is present to host the image route; image reads
+     * answer `binary` without it (the headless face has no browser to serve). */
+    private readonly imageRoute;
+    /** The agents service when present (image route only; null headless). */
+    private readonly agents;
+    /** Native reveal runner; a constructor seam for deterministic tests. */
+    private readonly revealNative;
+    /** Bash-write collector (S2 seam), or undefined when disabled in config. */
+    private readonly collector;
+    /** Per-session by-turn fold cache, invalidated by the log watermark. */
+    private readonly turnCache;
+    /**
+     * @param ctx - owning Cordis Context carrying `fs`; `webServer` and `agents`
+     *   are optional (the image route needs them, headless faces lack both).
+     * @param config - optional deployment tuning; defaults cap reads and lists,
+     *   and enable the bash-write collector.
+     * @param deps - test seam for the native reveal dispatch.
+     */
+    constructor(ctx: Context, config?: FilePreviewConfig, deps?: {
+        revealNative?: (path: string, signal: AbortSignal) => Promise<void>;
+    });
+    private get fs();
+    /**
+     * Serve one image file's bytes for a browser `<img>` request. The URL is
+     * `IMAGE_ROUTE/<sessionId>/<encodeURIComponent(path)>`; the session must be
+     * live (the same scope `read` serves) and the path resolves against its cwd.
+     * @param req - the incoming image request.
+     * @param res - the response to fill with bytes or an error status.
+     */
+    private serveImage;
+    /**
+     * List the files one session wrote or edited: the log fold plus any
+     * bash-written files the collector verified (the S2 seam), merged so a
+     * captured path the fold already knows keeps its log-derived entry.
+     * @param agent - owning live agent; its session log is the data source.
+     * @returns first-seen files capped by `maxFiles`, with the log watermark.
+     */
+    list(agent: Agent): FilePreviewList;
+    /**
+     * Every turn's file mutations for the turn-tail card — the single source of
+     * truth the card renders (the client's old write/edit-only fold retired).
+     * Built by folding the session log per turn (write/edit calls, Code Mode
+     * dispatches borrowing the root call's turn, and render-intent paths from
+     * result diff meta) and merging the collector's bash-written captures by
+     * their own turn. The fold is cached per session and invalidated by the log
+     * watermark, so repeated card fetches do not refold. A path touched in two
+     * turns appears in BOTH turn groups — per-turn attribution is exact.
+     * @param agent - owning live agent; its session log is the data source.
+     * @returns per-turn file groups plus the scanned watermark.
+     */
+    turnFiles(agent: Agent): FilePreviewTurnMap;
+    /**
+     * Read the current content of one recorded file, resolved against the
+     * session cwd and capped by `maxReadBytes`.
+     * @param agent - owning live agent; its session cwd anchors relative paths.
+     * @param path - the display path recorded by the write/edit tool call.
+     * @param signal - cooperative cancellation from the calling UI request.
+     * @returns the classified read; `text` carries content, `image` carries a
+     *   browser URL, other kinds carry the size or a human-readable reason.
+     */
+    read(agent: Agent, path: string, signal: AbortSignal): Promise<FilePreviewRead>;
+    /**
+     * Reveal one recorded file in the host file manager — open its folder and
+     * select the file (macOS Finder, Windows Explorer, or a select-capable
+     * desktop file manager). The display path resolves against the session cwd;
+     * the native reveal runs on the host. A path that does not resolve to an
+     * existing target, or a platform that cannot select, answers `revealed:
+     * false` and the caller opens the parent folder instead (the pre-reveal
+     * "show in folder" behavior), so the gesture always lands somewhere visible.
+     * @param agent - owning live agent; its session cwd anchors relative paths.
+     * @param path - the display path recorded by the read/write/edit tool call.
+     * @param signal - cooperative cancellation from the calling UI request.
+     * @returns whether the file manager selected the file, or why not.
+     */
+    reveal(agent: Agent, path: string, signal: AbortSignal): Promise<FilePreviewReveal>;
+}
+export default FilePreviewService;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,KAAK,EAAiB,MAAM,wBAAwB,CAAA;AAGlE,OAAO,EAAU,mBAAmB,EAAE,MAAM,kCAAkC,CAAA;AAC9E,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAIxC,OAAO,KAAK,EAAE,iBAAiB,EAAoB,eAAe,EAAE,eAAe,EAAE,iBAAiB,EAAuB,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAEnK,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,WAAW,EAAE,kBAAkB,CAAA;KAChC;CACF;AA4HD;;;;;;;GAOG;AACH,qBAAa,kBAAmB,SAAQ,mBAAmB;IACzD,MAAM,CAAC,MAAM,WAAS;IAEtB,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,iBAAiB,CAAC,CAKjC;IAEF,gDAAgD;IAChD,MAAM,CAAC,QAAQ,CAAC,WAAW,yBAAwB;IAEnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IACtD;iFAC6E;IAC7E,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,yEAAyE;IACzE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;IAClD,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsD;IACnF,4EAA4E;IAC5E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgC;IAC1D,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkE;IAE5F;;;;;;OAMG;IACH,YACE,GAAG,EAAE,OAAO,EACZ,MAAM,GAAE,iBAAsB,EAC9B,IAAI,GAAE;QAAE,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;KAAO,EAoCnF;IAED,OAAO,KAAK,EAAE,GAEb;IAED;;;;;;OAMG;YACW,UAAU;IAmExB;;;;;;OAMG;IAEH,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,eAAe,CAgBlC;IAED;;;;;;;;;;;OAWG;IAEH,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,kBAAkB,CAiC1C;IAED;;;;;;;;OAQG;IAEG,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC,CA6DpF;IAED;;;;;;;;;;;;OAYG;IAEG,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAgCxF;CACF;eAEc,kBAAkB"}