@khorsheed/dsh-file-preview 0.1.1 → 0.3.0

package/lib/typert.remote-client.js

@@ -1,6 +1,9 @@
 /* Generated by @deepseek-ai/dsh-typert-generator from the Host FaceModel — do not edit. */
 import { z } from 'zod'
 
+const _khorsheed_dsh_file_preview_filePreview_capabilities_result$schema = z.object({
+  'protocolVersion': z.literal(1),
+})
 const _khorsheed_dsh_file_preview_filePreview_list_parameter_0$schema = z.intersection(z.string(), z.unknown())
 const _khorsheed_dsh_file_preview_filePreview_list_result$schema = z.object({
   'entries': z.array(z.object({
@@ -24,11 +27,20 @@ const _khorsheed_dsh_file_preview_filePreview_list_result$schema = z.object({
   'asOfSeq': z.number().readonly(),
   'truncated': z.boolean().readonly(),
 })
+const _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_0$schema = z.intersection(z.string(), z.unknown())
+const _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_1$schema = z.string()
+const _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_2$schema = z.string()
+const _khorsheed_dsh_file_preview_filePreview_openExternal_result$schema = z.union([z.object({
+  'opened': z.literal(true).readonly(),
+}), z.object({
+  'opened': z.literal(false).readonly(),
+  'reason': z.union([z.literal("missing"), z.literal("unknown-app"), z.literal("unsupported-platform"), z.literal("launch-failed")]).readonly(),
+})])
 const _khorsheed_dsh_file_preview_filePreview_read_parameter_0$schema = z.intersection(z.string(), z.unknown())
 const _khorsheed_dsh_file_preview_filePreview_read_parameter_1$schema = z.string()
 const _khorsheed_dsh_file_preview_filePreview_read_result$schema = z.object({
   'path': z.string().readonly(),
-  'kind': z.union([z.literal("text"), z.literal("image"), z.literal("binary"), z.literal("missing"), z.literal("too-large"), z.literal("error")]).readonly(),
+  'kind': z.union([z.literal("missing"), z.literal("error"), z.literal("text"), z.literal("image"), z.literal("binary"), z.literal("too-large")]).readonly(),
   'content': z.string().readonly().optional(),
   'url': z.string().readonly().optional(),
   'truncated': z.boolean().readonly().optional(),
@@ -62,6 +74,21 @@ const _khorsheed_dsh_file_preview_filePreview_turnFiles_result$schema = z.object
 export const TYPERT_REMOTE = {
   package: '@khorsheed/dsh-file-preview',
   descriptors: [
+    {
+      id: '@khorsheed/dsh-file-preview#filePreview/capabilities',
+      service: 'filePreview',
+      namespace: 'filePreview',
+      method: 'capabilities',
+      invocation: { kind: 'direct' },
+      parameters: [
+      ],
+      result: {
+        mode: 'strict',
+        typeSymbol: '@khorsheed/dsh-file-preview#filePreview/capabilities:result',
+        schema: _khorsheed_dsh_file_preview_filePreview_capabilities_result$schema,
+      },
+      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":191,"column":3},
+    },
     {
       id: '@khorsheed/dsh-file-preview#filePreview/list',
       service: 'filePreview',
@@ -90,7 +117,58 @@ export const TYPERT_REMOTE = {
         typeSymbol: '@khorsheed/dsh-file-preview/types#FilePreviewList',
         schema: _khorsheed_dsh_file_preview_filePreview_list_result$schema,
       },
-      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":316,"column":3},
+      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":311,"column":9},
+    },
+    {
+      id: '@khorsheed/dsh-file-preview#filePreview/openExternal',
+      service: 'filePreview',
+      namespace: 'filePreview',
+      method: 'openExternal',
+      invocation: { kind: 'direct' },
+      scope: {
+        context: 'agent',
+        wire: 'agentId',
+      },
+      parameters: [
+        {
+          name: 'agent',
+          wire: 'agentId',
+          source: 'lookup',
+          lookup: 'agent',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
+            schema: _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_0$schema,
+          },
+        },
+        {
+          name: 'path',
+          wire: 'path',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@khorsheed/dsh-file-preview#filePreview/openExternal:path',
+            schema: _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_1$schema,
+          },
+        },
+        {
+          name: 'app',
+          wire: 'app',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@khorsheed/dsh-file-preview#filePreview/openExternal:app',
+            schema: _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_2$schema,
+          },
+        },
+      ],
+      cancellation: { parameter: 'signal' },
+      result: {
+        mode: 'strict',
+        typeSymbol: '@khorsheed/dsh-file-preview/types#FilePreviewOpenExternal',
+        schema: _khorsheed_dsh_file_preview_filePreview_openExternal_result$schema,
+      },
+      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":528,"column":9},
     },
     {
       id: '@khorsheed/dsh-file-preview#filePreview/read',
@@ -131,7 +209,7 @@ export const TYPERT_REMOTE = {
         typeSymbol: '@khorsheed/dsh-file-preview/types#FilePreviewRead',
         schema: _khorsheed_dsh_file_preview_filePreview_read_result$schema,
       },
-      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":392,"column":9},
+      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":401,"column":9},
     },
     {
       id: '@khorsheed/dsh-file-preview#filePreview/reveal',
@@ -172,7 +250,7 @@ export const TYPERT_REMOTE = {
         typeSymbol: '@khorsheed/dsh-file-preview/types#FilePreviewReveal',
         schema: _khorsheed_dsh_file_preview_filePreview_reveal_result$schema,
       },
-      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":469,"column":9},
+      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":478,"column":9},
     },
     {
       id: '@khorsheed/dsh-file-preview#filePreview/turnFiles',
@@ -202,7 +280,7 @@ export const TYPERT_REMOTE = {
         typeSymbol: '@khorsheed/dsh-file-preview/types#FilePreviewTurnMap',
         schema: _khorsheed_dsh_file_preview_filePreview_turnFiles_result$schema,
       },
-      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":347,"column":3},
+      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":348,"column":9},
     },
   ],
 }

package/lib/types/bash-writes.js

@@ -305,7 +305,7 @@ export class BashWriteCollector {
     #replay(session) {
         this.#pending.set(session.id, new Map());
         this.#captured.set(session.id, new Map());
-        for (const event of session.events)
+        for (const event of session.snapshotEvents())
             this.#onEvent(session, event);
     }
     #onEvent(session, event) {

package/lib/types/fold.d.ts

@@ -26,9 +26,11 @@ export declare function diffsFromResultMeta(meta: unknown): readonly FilePreview
  * 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.
+ * Nested PTC file dispatches (`tool/ptc-dispatch` events — the host's Code
+ * Mode name through 0.1.2, renamed with the 0.1.5 format; the v2→v3 log
+ * migration renames persisted rows, so only the ptc name is matched) 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.
@@ -55,11 +57,12 @@ export type TurnFilesByTurn = ReadonlyMap<number, ReadonlyMap<string, TurnFileFa
  * 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
+ * Reads leave no card entry (the card is the mutation vocabulary — write/edit
+ * only), so a pure-read call never registers; write/edit calls register with
+ * their own turn; nested PTC 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.
@@ -67,7 +70,7 @@ export type TurnFilesByTurn = ReadonlyMap<number, ReadonlyMap<string, TurnFileFa
  * 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
+ * field with unknown-wins — an uncounted mutation (a PTC 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.

package/lib/types/fold.js

@@ -57,9 +57,11 @@ export function diffsFromResultMeta(meta) {
  * 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.
+ * Nested PTC file dispatches (`tool/ptc-dispatch` events — the host's Code
+ * Mode name through 0.1.2, renamed with the 0.1.5 format; the v2→v3 log
+ * migration renames persisted rows, so only the ptc name is matched) 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.
@@ -67,7 +69,7 @@ export function diffsFromResultMeta(meta) {
  */
 export function foldFilePreview(events, maxFiles) {
     const entries = new Map();
-    /** Root tool/call locations, so nested code dispatches borrow their turn/step. */
+    /** Root tool/call locations, so nested 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. */
@@ -88,7 +90,7 @@ export function foldFilePreview(events, maxFiles) {
             record(target, event.seq, event.data.turn, event.data.step);
             continue;
         }
-        if (event.type === 'tool/code-dispatch') {
+        if (event.type === 'tool/ptc-dispatch') {
             // The dispatch event IS the settled outcome: a failed sub-call changed
             // nothing, so only successful file touches record.
             if (event.data.isError)
@@ -172,11 +174,12 @@ function resultCallFacts(message) {
  * 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
+ * Reads leave no card entry (the card is the mutation vocabulary — write/edit
+ * only), so a pure-read call never registers; write/edit calls register with
+ * their own turn; nested PTC 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.
@@ -184,7 +187,7 @@ function resultCallFacts(message) {
  * 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
+ * field with unknown-wins — an uncounted mutation (a PTC 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.
@@ -192,7 +195,7 @@ function resultCallFacts(message) {
  */
 export function foldFilePreviewByTurn(events) {
     const byTurn = new Map();
-    /** Root tool/call locations, so nested code dispatches borrow their turn/step. */
+    /** Root tool/call locations, so nested dispatches borrow their turn/step. */
     const callSites = new Map();
     /** Write-tool calls keyed by callId (create fallback; see {@link WriteCallFacts}). */
     const writeCalls = new Map();
@@ -222,7 +225,7 @@ export function foldFilePreviewByTurn(events) {
      *  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. */
+     *  PTC dispatch): it poisons both fields. */
     const recordContribution = (path, turn, seq, step, added, removed, unknown) => {
         const map = turnMap(turn);
         const key = countKey(turn, path);
@@ -257,6 +260,11 @@ export function foldFilePreviewByTurn(events) {
             const target = pathFromToolCall(event.data.name, event.data.arguments);
             if (target === undefined)
                 continue;
+            // The card's vocabulary is mutations only: a read call registers
+            // nothing (it may still anchor a nested dispatch's location via
+            // callSites above).
+            if (target.op === 'read')
+                continue;
             if (target.op === 'write') {
                 const content = contentFromWriteCall(event.data.arguments);
                 if (content !== undefined) {
@@ -268,9 +276,9 @@ export function foldFilePreviewByTurn(events) {
             recordLocation(target.path, event.data.turn, event.seq, event.data.step);
             continue;
         }
-        if (event.type === 'tool/code-dispatch') {
+        if (event.type === 'tool/ptc-dispatch') {
             // The dispatch event IS the settled outcome: a failed sub-call changed
-            // nothing, so only successful file touches record. Code Mode writes are
+            // nothing, so only successful file touches record. PTC 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)
@@ -278,6 +286,9 @@ export function foldFilePreviewByTurn(events) {
             const target = targetFromArguments(event.data.name, event.data.arguments);
             if (target === undefined)
                 continue;
+            // Reads leave no card entry here too — only mutations register.
+            if (target.op === 'read')
+                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);

package/lib/types/index.d.ts

@@ -5,7 +5,7 @@ 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';
+import type { FilePreviewConfig, FilePreviewList, FilePreviewOpenExternal, FilePreviewRead, FilePreviewReveal, FilePreviewTurnMap } from './types.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         filePreview: FilePreviewService;
@@ -13,8 +13,9 @@ declare module '@deepseek-ai/cordis' {
 }
 /**
  * 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
+ * for web surfaces. `list` is a fold over the session log, then filtered to the
+ * paths that still exist on disk (resolved against the session cwd and stat-ed
+ * per call); `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.
@@ -32,6 +33,8 @@ export declare class FilePreviewService extends TypertRemoteService {
     private readonly agents;
     /** Native reveal runner; a constructor seam for deterministic tests. */
     private readonly revealNative;
+    /** Native open-in-app runner; a constructor seam for deterministic tests. */
+    private readonly openExternalNative;
     /** 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. */
@@ -45,7 +48,12 @@ export declare class FilePreviewService extends TypertRemoteService {
      */
     constructor(ctx: Context, config?: FilePreviewConfig, deps?: {
         revealNative?: (path: string, signal: AbortSignal) => Promise<void>;
+        openExternalNative?: (path: string, app: string, signal: AbortSignal) => Promise<void>;
     });
+    /** Zero-session availability handshake for browser companions. */
+    capabilities(): {
+        protocolVersion: 1;
+    };
     private get fs();
     /**
      * Serve one image file's bytes for a browser `<img>` request. The URL is
@@ -55,27 +63,44 @@ export declare class FilePreviewService extends TypertRemoteService {
      * @param res - the response to fill with bytes or an error status.
      */
     private serveImage;
+    /** Resolve the session's recorded display paths against its cwd and keep only
+     *  those that currently exist as a regular file. The products surfaces fold
+     *  the session log (which is history, not disk state): a path the log wrote
+     *  may have been cleaned up since (a temp script the turn deleted), and such
+     *  a path is not a product to list. Existence is checked fresh on every call
+     *  (never cached), so a deletion that lands after a fold is visible on the
+     *  next fetch. Unresolvable/unstat-able paths are treated as absent.
+     * @param agent - owning live agent; its session cwd anchors relative paths.
+     * @param paths - the display paths to probe.
+     * @returns the subset that resolves to an existing regular file.
+     */
+    private retainExisting;
     /**
      * 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.
+     * captured path the fold already knows keeps its log-derived entry. Only
+     * paths that currently exist on disk are returned — a file the session
+     * wrote and later deleted is history, not a product.
      * @param agent - owning live agent; its session log is the data source.
-     * @returns first-seen files capped by `maxFiles`, with the log watermark.
+     * @returns existing first-seen files capped by `maxFiles`, with the log watermark.
      */
-    list(agent: Agent): FilePreviewList;
+    list(agent: Agent): Promise<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
+     * Built by folding the session log per turn (write/edit calls, PTC
      * 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.
+     * turns appears in BOTH turn groups — per-turn attribution is exact. Only
+     * paths that currently exist on disk are returned (a deleted temp script is
+     * history, not a product); existence is probed fresh on every call, so the
+     * cached fold is filtered per request rather than cached.
      * @param agent - owning live agent; its session log is the data source.
-     * @returns per-turn file groups plus the scanned watermark.
+     * @returns existing per-turn file groups plus the scanned watermark.
      */
-    turnFiles(agent: Agent): FilePreviewTurnMap;
+    turnFiles(agent: Agent): Promise<FilePreviewTurnMap>;
     /**
      * Read the current content of one recorded file, resolved against the
      * session cwd and capped by `maxReadBytes`.
@@ -100,6 +125,22 @@ export declare class FilePreviewService extends TypertRemoteService {
      * @returns whether the file manager selected the file, or why not.
      */
     reveal(agent: Agent, path: string, signal: AbortSignal): Promise<FilePreviewReveal>;
+    /**
+     * Open one recorded file in a specific host application (the "open in IDE"
+     * gesture). The official open-in-app route only accepts directories — a
+     * file path 404s — so file-exact opens go through this method: macOS
+     * `open -a <App> <path>` via the same native-command runner reveal uses.
+     * The browser names the application by official open-in-app catalog id
+     * (probed from `/open-in-app/apps`); the id → app-name map lives in
+     * open-external.ts. Non-macOS hosts and unknown ids answer without
+     * launching, and the client hides the gesture.
+     * @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 app - official open-in-app catalog id (e.g. `cursor`).
+     * @param signal - cooperative cancellation from the calling UI request.
+     * @returns whether the application launched, or why not.
+     */
+    openExternal(agent: Agent, path: string, app: string, signal: AbortSignal): Promise<FilePreviewOpenExternal>;
 }
 export default FilePreviewService;
 //# sourceMappingURL=index.d.ts.map