@khorsheed/dsh-file-preview 0.4.1 → 0.4.2

package/lib/typert.remote-client.d.ts

@@ -1,7 +1,8 @@
 /* Generated by @deepseek-ai/dsh-typert-generator from the Host FaceModel — do not edit. */
 import type {
   RemoteResult,
-  TypertRemoteContribution,
+  TypertRemoteInfo,
+  TypertRemoteMethod,
 } from '@deepseek-ai/dsh-typert-protocol'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import type { FilePreviewList, FilePreviewOpenExternal, FilePreviewRead, FilePreviewReveal, FilePreviewTurnMap } from '@khorsheed/dsh-file-preview/types'
@@ -35,6 +36,13 @@ declare module '@deepseek-ai/dsh-typert-protocol' {
   }
 }
 
-export declare const TYPERT_REMOTE: TypertRemoteContribution
+export declare const TYPERT_REMOTE: TypertRemoteInfo<{
+  readonly 'filePreview/capabilities': TypertRemoteMethod<{  }, { protocolVersion: 1; }>
+  readonly 'filePreview/list': TypertRemoteMethod<{ readonly 'agentId': SessionId }, FilePreviewList>
+  readonly 'filePreview/openExternal': TypertRemoteMethod<{ readonly 'agentId': SessionId; readonly 'path': string; readonly 'app': string }, FilePreviewOpenExternal>
+  readonly 'filePreview/read': TypertRemoteMethod<{ readonly 'agentId': SessionId; readonly 'path': string }, FilePreviewRead>
+  readonly 'filePreview/reveal': TypertRemoteMethod<{ readonly 'agentId': SessionId; readonly 'path': string }, FilePreviewReveal>
+  readonly 'filePreview/turnFiles': TypertRemoteMethod<{ readonly 'agentId': SessionId }, FilePreviewTurnMap>
+}>
 export default TYPERT_REMOTE
 //# sourceMappingURL=typert.remote-client.d.ts.map

package/lib/typert.remote-client.js

@@ -1,99 +1,117 @@
 /* Generated by @deepseek-ai/dsh-typert-generator from the Host FaceModel — do not edit. */
 import { z } from 'zod'
 
+import { createTypertRemoteInfo } from '@deepseek-ai/dsh-typert-protocol/remote-info'
+
 let _khorsheed_dsh_file_preview_filePreview_capabilities_result$schema$value
 const _khorsheed_dsh_file_preview_filePreview_capabilities_result$schema = () => (_khorsheed_dsh_file_preview_filePreview_capabilities_result$schema$value ??= z.object({
   'protocolVersion': z.literal(1),
 }))
 let _khorsheed_dsh_file_preview_filePreview_list_parameter_0$schema$value
-const _khorsheed_dsh_file_preview_filePreview_list_parameter_0$schema = () => (_khorsheed_dsh_file_preview_filePreview_list_parameter_0$schema$value ??= z.intersection(z.string(), z.unknown()))
+const _khorsheed_dsh_file_preview_filePreview_list_parameter_0$schema = () => (_khorsheed_dsh_file_preview_filePreview_list_parameter_0$schema$value ??= z.string())
 let _khorsheed_dsh_file_preview_filePreview_list_result$schema$value
 const _khorsheed_dsh_file_preview_filePreview_list_result$schema = () => (_khorsheed_dsh_file_preview_filePreview_list_result$schema$value ??= z.object({
   'entries': z.array(z.object({
-  'path': z.string().readonly(),
-  'op': z.union([z.literal("read"), z.literal("write"), z.literal("edit")]).readonly(),
-  'seq': z.number().readonly(),
-  'turn': z.number().readonly(),
-  'step': z.number().readonly(),
+  'path': z.string().readonly().describe('Display path exactly as the tool call recorded it (relative to the session cwd when it was).'),
+  'op': z.union([z.literal("edit"), z.literal("write"), z.literal("read")]).readonly().describe('The last recorded operation.'),
+  'seq': z.number().readonly().describe('Seq of the last `tool/call` event recorded for this path.'),
+  'turn': z.number().readonly().describe('Turn of the last occurrence.'),
+  'step': z.number().readonly().describe('Step of the last occurrence.'),
   'diffs': z.array(z.object({
-  'seq': z.number().readonly(),
-  'turn': z.number().readonly(),
-  'step': z.number().readonly(),
-  'oldText': z.union([z.literal(null), z.string()]).readonly(),
-  'newText': z.string().readonly(),
-})).readonly(),
+  'seq': z.number().readonly().describe('Seq of the `tool/result` event whose meta carried this diff.'),
+  'turn': z.number().readonly().describe('Turn of the change.'),
+  'step': z.number().readonly().describe('Step of the change.'),
+  'oldText': z.union([z.literal(null), z.string()]).readonly().describe('Prior content, or null for a new file / an overwrite.'),
+  'newText': z.string().readonly().describe('Content after the change.'),
+})).readonly().describe('Each write/edit change\'s diff, captured from the tool results\' presentation meta, in event order.'),
   'lastDiff': z.union([z.undefined(), z.object({
   'oldText': z.union([z.literal(null), z.string()]).readonly(),
   'newText': z.string().readonly(),
-})]).readonly().optional(),
-})).readonly(),
-  'asOfSeq': z.number().readonly(),
-  'truncated': z.boolean().readonly(),
+})]).readonly().optional().describe('The last write/edit change\'s diff (the final `diffs` entry, for callers that want just the latest).'),
+})).readonly().describe('Files in first-seen order, deduplicated by display path.'),
+  'asOfSeq': z.number().readonly().describe('Seq of the last scanned session event (`-1` for an empty log).'),
+  'truncated': z.boolean().readonly().describe('Whether the list was capped at the service\'s `maxFiles` limit.'),
 }))
 let _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_0$schema$value
-const _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_0$schema = () => (_khorsheed_dsh_file_preview_filePreview_openExternal_parameter_0$schema$value ??= z.intersection(z.string(), z.unknown()))
+const _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_0$schema = () => (_khorsheed_dsh_file_preview_filePreview_openExternal_parameter_0$schema$value ??= z.string())
 let _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_1$schema$value
 const _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_1$schema = () => (_khorsheed_dsh_file_preview_filePreview_openExternal_parameter_1$schema$value ??= z.string())
 let _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_2$schema$value
 const _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_2$schema = () => (_khorsheed_dsh_file_preview_filePreview_openExternal_parameter_2$schema$value ??= z.string())
 let _khorsheed_dsh_file_preview_filePreview_openExternal_result$schema$value
 const _khorsheed_dsh_file_preview_filePreview_openExternal_result$schema = () => (_khorsheed_dsh_file_preview_filePreview_openExternal_result$schema$value ??= z.union([z.object({
-  'opened': z.literal(true).readonly(),
+  'opened': z.literal(true).readonly().describe('The application launched on the file.'),
 }), 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(),
+  'opened': z.literal(false).readonly().describe('The file could not be opened in the named application.'),
+  'reason': z.union([z.literal("missing"), z.literal("unknown-app"), z.literal("unsupported-platform"), z.literal("launch-failed")]).readonly().describe('Why: `missing` = the recorded path does not resolve to an existing target; `unknown-app` = the catalog id is not mapped; `unsupported-platform` = the host is not macOS; `launch-failed` = the native launch rejected.'),
 })]))
 let _khorsheed_dsh_file_preview_filePreview_read_parameter_0$schema$value
-const _khorsheed_dsh_file_preview_filePreview_read_parameter_0$schema = () => (_khorsheed_dsh_file_preview_filePreview_read_parameter_0$schema$value ??= z.intersection(z.string(), z.unknown()))
+const _khorsheed_dsh_file_preview_filePreview_read_parameter_0$schema = () => (_khorsheed_dsh_file_preview_filePreview_read_parameter_0$schema$value ??= z.string())
 let _khorsheed_dsh_file_preview_filePreview_read_parameter_1$schema$value
 const _khorsheed_dsh_file_preview_filePreview_read_parameter_1$schema = () => (_khorsheed_dsh_file_preview_filePreview_read_parameter_1$schema$value ??= z.string())
 let _khorsheed_dsh_file_preview_filePreview_read_result$schema$value
 const _khorsheed_dsh_file_preview_filePreview_read_result$schema = () => (_khorsheed_dsh_file_preview_filePreview_read_result$schema$value ??= z.object({
-  'path': z.string().readonly(),
-  'kind': z.union([z.literal("missing"), z.literal("too-large"), z.literal("error"), z.literal("text"), z.literal("binary"), z.literal("image")]).readonly(),
-  'content': z.string().readonly().optional(),
-  'url': z.string().readonly().optional(),
-  'truncated': z.boolean().readonly().optional(),
-  'htmlScripted': z.boolean().readonly().optional(),
-  'size': z.number().readonly().optional(),
-  'message': z.string().readonly().optional(),
+  'path': z.string().readonly().describe('The resolved display path of the read target.'),
+  'kind': z.union([z.literal("text"), z.literal("image"), z.literal("error"), z.literal("missing"), z.literal("too-large"), z.literal("binary")]).readonly().describe('Outcome classification; `text`/`image` carry a renderable value, `error` carries message.'),
+  'content': z.string().readonly().optional().describe('Current text content for `text` reads, capped by the service\'s `maxReadBytes` (HTML files by `htmlMaxReadBytes`).'),
+  'url': z.string().readonly().optional().describe('Browser-loadable URL for `image` reads (host-served bytes, session-scoped).'),
+  'truncated': z.boolean().readonly().optional().describe('Whether `content` was truncated to the byte cap.'),
+  'htmlScripted': z.boolean().readonly().optional().describe('HTML files only: best-effort hint that the document contains scripts (`<script>` tags, inline event handlers, or `javascript:` URLs). A hint for default-mode selection and warning — never a trust decision; the sandbox and CSP are the real boundary. Absent for non-HTML reads and for HTML without script markers.'),
+  'size': z.number().readonly().optional().describe('Byte size of the file when the backend reported one.'),
+  'message': z.string().readonly().optional().describe('Human-readable failure detail for `error` reads.'),
 }))
 let _khorsheed_dsh_file_preview_filePreview_reveal_parameter_0$schema$value
-const _khorsheed_dsh_file_preview_filePreview_reveal_parameter_0$schema = () => (_khorsheed_dsh_file_preview_filePreview_reveal_parameter_0$schema$value ??= z.intersection(z.string(), z.unknown()))
+const _khorsheed_dsh_file_preview_filePreview_reveal_parameter_0$schema = () => (_khorsheed_dsh_file_preview_filePreview_reveal_parameter_0$schema$value ??= z.string())
 let _khorsheed_dsh_file_preview_filePreview_reveal_parameter_1$schema$value
 const _khorsheed_dsh_file_preview_filePreview_reveal_parameter_1$schema = () => (_khorsheed_dsh_file_preview_filePreview_reveal_parameter_1$schema$value ??= z.string())
 let _khorsheed_dsh_file_preview_filePreview_reveal_result$schema$value
 const _khorsheed_dsh_file_preview_filePreview_reveal_result$schema = () => (_khorsheed_dsh_file_preview_filePreview_reveal_result$schema$value ??= z.union([z.object({
-  'revealed': z.literal(true).readonly(),
+  'revealed': z.literal(true).readonly().describe('The host file manager opened the file\'s folder with the file selected.'),
 }), z.object({
-  'revealed': z.literal(false).readonly(),
-  'reason': z.union([z.literal("missing"), z.literal("select-failed")]).readonly(),
+  'revealed': z.literal(false).readonly().describe('The file could not be revealed; the caller opens the parent folder instead.'),
+  'reason': z.union([z.literal("missing"), z.literal("select-failed")]).readonly().describe('Why: `missing` = the recorded path does not resolve to an existing target; `select-failed` = the host could not select the file.'),
 })]))
 let _khorsheed_dsh_file_preview_filePreview_turnFiles_parameter_0$schema$value
-const _khorsheed_dsh_file_preview_filePreview_turnFiles_parameter_0$schema = () => (_khorsheed_dsh_file_preview_filePreview_turnFiles_parameter_0$schema$value ??= z.intersection(z.string(), z.unknown()))
+const _khorsheed_dsh_file_preview_filePreview_turnFiles_parameter_0$schema = () => (_khorsheed_dsh_file_preview_filePreview_turnFiles_parameter_0$schema$value ??= z.string())
 let _khorsheed_dsh_file_preview_filePreview_turnFiles_result$schema$value
 const _khorsheed_dsh_file_preview_filePreview_turnFiles_result$schema = () => (_khorsheed_dsh_file_preview_filePreview_turnFiles_result$schema$value ??= z.object({
   'turns': z.array(z.object({
   'turn': z.number().readonly(),
   'files': z.array(z.object({
-  'path': z.string().readonly(),
-  'seq': z.number().readonly(),
+  'path': z.string().readonly().describe('The display path (absolute for bash-captured writes; as-recorded otherwise).'),
+  'seq': z.number().readonly().describe('Seq of the first mutation recorded for this path in this turn (stable ordering).'),
   'step': z.number().readonly(),
-  'added': z.number().readonly().optional(),
-  'removed': z.number().readonly().optional(),
-})).readonly(),
+  'added': z.number().readonly().optional().describe('Lines added across the turn\'s mutations of this path.'),
+  'removed': z.number().readonly().optional().describe('Lines removed; 0 for a create; absent when an uncounted mutation (a write whose prior content was not diffable, a PTC dispatch) reported no total.'),
 })).readonly(),
-  'asOfSeq': z.number().readonly(),
+})).readonly().describe('Files mutated per turn, in event order within each turn.'),
+  'asOfSeq': z.number().readonly().describe('Seq of the last scanned session event (cache invalidation watermark).'),
 }))
+let _khorsheed_dsh_file_preview_filePreview_list_parameter_0_strict$schema$value
+const _khorsheed_dsh_file_preview_filePreview_list_parameter_0_strict$schema = () => (_khorsheed_dsh_file_preview_filePreview_list_parameter_0_strict$schema$value ??= z.string())
+let _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_0_strict$schema$value
+const _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_0_strict$schema = () => (_khorsheed_dsh_file_preview_filePreview_openExternal_parameter_0_strict$schema$value ??= z.string())
+let _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_1_strict$schema$value
+const _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_1_strict$schema = () => (_khorsheed_dsh_file_preview_filePreview_openExternal_parameter_1_strict$schema$value ??= z.string())
+let _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_2_strict$schema$value
+const _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_2_strict$schema = () => (_khorsheed_dsh_file_preview_filePreview_openExternal_parameter_2_strict$schema$value ??= z.string())
+let _khorsheed_dsh_file_preview_filePreview_read_parameter_0_strict$schema$value
+const _khorsheed_dsh_file_preview_filePreview_read_parameter_0_strict$schema = () => (_khorsheed_dsh_file_preview_filePreview_read_parameter_0_strict$schema$value ??= z.string())
+let _khorsheed_dsh_file_preview_filePreview_read_parameter_1_strict$schema$value
+const _khorsheed_dsh_file_preview_filePreview_read_parameter_1_strict$schema = () => (_khorsheed_dsh_file_preview_filePreview_read_parameter_1_strict$schema$value ??= z.string())
+let _khorsheed_dsh_file_preview_filePreview_reveal_parameter_0_strict$schema$value
+const _khorsheed_dsh_file_preview_filePreview_reveal_parameter_0_strict$schema = () => (_khorsheed_dsh_file_preview_filePreview_reveal_parameter_0_strict$schema$value ??= z.string())
+let _khorsheed_dsh_file_preview_filePreview_reveal_parameter_1_strict$schema$value
+const _khorsheed_dsh_file_preview_filePreview_reveal_parameter_1_strict$schema = () => (_khorsheed_dsh_file_preview_filePreview_reveal_parameter_1_strict$schema$value ??= z.string())
+let _khorsheed_dsh_file_preview_filePreview_turnFiles_parameter_0_strict$schema$value
+const _khorsheed_dsh_file_preview_filePreview_turnFiles_parameter_0_strict$schema = () => (_khorsheed_dsh_file_preview_filePreview_turnFiles_parameter_0_strict$schema$value ??= z.string())
 
-export const TYPERT_REMOTE = {
+export const TYPERT_REMOTE = createTypertRemoteInfo({
   package: '@khorsheed/dsh-file-preview',
-  descriptors: [
-    {
-      id: '@khorsheed/dsh-file-preview#filePreview/capabilities',
+  methods: {
+    'filePreview/capabilities': {
       service: 'filePreview',
-      namespace: 'filePreview',
-      method: 'capabilities',
+      description: 'Zero-session availability handshake for browser companions.',
       invocation: { kind: 'direct' },
       parameters: [
       ],
@@ -102,14 +120,13 @@ export const TYPERT_REMOTE = {
         typeSymbol: '@khorsheed/dsh-file-preview#filePreview/capabilities:result',
         create: _khorsheed_dsh_file_preview_filePreview_capabilities_result$schema,
         schema: _khorsheed_dsh_file_preview_filePreview_capabilities_result$schema(),
+        jsonSchema: {"type":"object","properties":{"protocolVersion":{"type":"number","const":1}},"required":["protocolVersion"],"additionalProperties":true},
       },
-      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":196,"column":3},
+      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":135,"column":3},
     },
-    {
-      id: '@khorsheed/dsh-file-preview#filePreview/list',
+    'filePreview/list': {
       service: 'filePreview',
-      namespace: 'filePreview',
-      method: 'list',
+      description: '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. Only paths that currently exist on disk are returned — a file the session wrote and later deleted is history, not a product.',
       invocation: { kind: 'direct' },
       scope: {
         context: 'agent',
@@ -119,6 +136,7 @@ export const TYPERT_REMOTE = {
         {
           name: 'agent',
           wire: 'agentId',
+          description: 'owning live agent; its session log is the data source.',
           source: 'lookup',
           lookup: 'agent',
           codec: {
@@ -126,6 +144,14 @@ export const TYPERT_REMOTE = {
             typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
             create: _khorsheed_dsh_file_preview_filePreview_list_parameter_0$schema,
             schema: _khorsheed_dsh_file_preview_filePreview_list_parameter_0$schema(),
+            jsonSchema: {"type":"string"},
+          },
+          strictCodec: {
+            mode: 'strict',
+            typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
+            create: _khorsheed_dsh_file_preview_filePreview_list_parameter_0_strict$schema,
+            schema: _khorsheed_dsh_file_preview_filePreview_list_parameter_0_strict$schema(),
+            jsonSchema: {"type":"string"},
           },
         },
       ],
@@ -134,14 +160,14 @@ export const TYPERT_REMOTE = {
         typeSymbol: '@khorsheed/dsh-file-preview/types#FilePreviewList',
         create: _khorsheed_dsh_file_preview_filePreview_list_result$schema,
         schema: _khorsheed_dsh_file_preview_filePreview_list_result$schema(),
+        description: 'existing first-seen files capped by `maxFiles`, with the log watermark.',
+        jsonSchema: {"type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","description":"Display path exactly as the tool call recorded it (relative to the session cwd when it was)."},"op":{"type":"string","enum":["edit","write","read"],"description":"The last recorded operation."},"seq":{"type":"number","description":"Seq of the last `tool/call` event recorded for this path."},"turn":{"type":"number","description":"Turn of the last occurrence."},"step":{"type":"number","description":"Step of the last occurrence."},"diffs":{"type":"array","items":{"type":"object","properties":{"seq":{"type":"number","description":"Seq of the `tool/result` event whose meta carried this diff."},"turn":{"type":"number","description":"Turn of the change."},"step":{"type":"number","description":"Step of the change."},"oldText":{"oneOf":[{"type":"null","const":null},{"type":"string"}],"description":"Prior content, or null for a new file / an overwrite."},"newText":{"type":"string","description":"Content after the change."}},"required":["seq","turn","step","oldText","newText"],"additionalProperties":true},"description":"Each write/edit change's diff, captured from the tool results' presentation meta, in event order."},"lastDiff":{"type":"object","properties":{"oldText":{"oneOf":[{"type":"null","const":null},{"type":"string"}]},"newText":{"type":"string"}},"required":["oldText","newText"],"additionalProperties":true,"description":"The last write/edit change's diff (the final `diffs` entry, for callers that want just the latest)."}},"required":["path","op","seq","turn","step","diffs"],"additionalProperties":true},"description":"Files in first-seen order, deduplicated by display path."},"asOfSeq":{"type":"number","description":"Seq of the last scanned session event (`-1` for an empty log)."},"truncated":{"type":"boolean","description":"Whether the list was capped at the service's `maxFiles` limit."}},"required":["entries","asOfSeq","truncated"],"additionalProperties":true},
       },
-      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":316,"column":9},
+      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":227,"column":9},
     },
-    {
-      id: '@khorsheed/dsh-file-preview#filePreview/openExternal',
+    'filePreview/openExternal': {
       service: 'filePreview',
-      namespace: 'filePreview',
-      method: 'openExternal',
+      description: '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.',
       invocation: { kind: 'direct' },
       scope: {
         context: 'agent',
@@ -151,6 +177,7 @@ export const TYPERT_REMOTE = {
         {
           name: 'agent',
           wire: 'agentId',
+          description: 'owning live agent; its session cwd anchors relative paths.',
           source: 'lookup',
           lookup: 'agent',
           codec: {
@@ -158,28 +185,52 @@ export const TYPERT_REMOTE = {
             typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
             create: _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_0$schema,
             schema: _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_0$schema(),
+            jsonSchema: {"type":"string"},
+          },
+          strictCodec: {
+            mode: 'strict',
+            typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
+            create: _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_0_strict$schema,
+            schema: _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_0_strict$schema(),
+            jsonSchema: {"type":"string"},
           },
         },
         {
           name: 'path',
-          wire: 'path',
+          description: 'the display path recorded by the read/write/edit tool call.',
           source: 'json',
           codec: {
             mode: 'strict',
             typeSymbol: '@khorsheed/dsh-file-preview#filePreview/openExternal:path',
             create: _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_1$schema,
             schema: _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_1$schema(),
+            jsonSchema: {"type":"string"},
+          },
+          strictCodec: {
+            mode: 'strict',
+            typeSymbol: '@khorsheed/dsh-file-preview#filePreview/openExternal:path',
+            create: _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_1_strict$schema,
+            schema: _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_1_strict$schema(),
+            jsonSchema: {"type":"string"},
           },
         },
         {
           name: 'app',
-          wire: 'app',
+          description: 'official open-in-app catalog id (e.g. `cursor`).',
           source: 'json',
           codec: {
             mode: 'strict',
             typeSymbol: '@khorsheed/dsh-file-preview#filePreview/openExternal:app',
             create: _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_2$schema,
             schema: _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_2$schema(),
+            jsonSchema: {"type":"string"},
+          },
+          strictCodec: {
+            mode: 'strict',
+            typeSymbol: '@khorsheed/dsh-file-preview#filePreview/openExternal:app',
+            create: _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_2_strict$schema,
+            schema: _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_2_strict$schema(),
+            jsonSchema: {"type":"string"},
           },
         },
       ],
@@ -189,14 +240,14 @@ export const TYPERT_REMOTE = {
         typeSymbol: '@khorsheed/dsh-file-preview/types#FilePreviewOpenExternal',
         create: _khorsheed_dsh_file_preview_filePreview_openExternal_result$schema,
         schema: _khorsheed_dsh_file_preview_filePreview_openExternal_result$schema(),
+        description: 'whether the application launched, or why not.',
+        jsonSchema: {"oneOf":[{"type":"object","properties":{"opened":{"type":"boolean","const":true,"description":"The application launched on the file."}},"required":["opened"],"additionalProperties":true},{"type":"object","properties":{"opened":{"type":"boolean","const":false,"description":"The file could not be opened in the named application."},"reason":{"type":"string","enum":["missing","unknown-app","unsupported-platform","launch-failed"],"description":"Why: `missing` = the recorded path does not resolve to an existing target; `unknown-app` = the catalog id is not mapped; `unsupported-platform` = the host is not macOS; `launch-failed` = the native launch rejected."}},"required":["opened","reason"],"additionalProperties":true}]},
       },
-      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":539,"column":9},
+      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":369,"column":9},
     },
-    {
-      id: '@khorsheed/dsh-file-preview#filePreview/read',
+    'filePreview/read': {
       service: 'filePreview',
-      namespace: 'filePreview',
-      method: 'read',
+      description: 'Read the current content of one recorded file, resolved against the session cwd and capped by `maxReadBytes`. The text read is a bounded byte window (`readByteRange` of cap + 1 bytes), so an oversized file costs the cap, never its full size; a known oversized stat still short-circuits to `too-large` before any bytes move.',
       invocation: { kind: 'direct' },
       scope: {
         context: 'agent',
@@ -206,6 +257,7 @@ export const TYPERT_REMOTE = {
         {
           name: 'agent',
           wire: 'agentId',
+          description: 'owning live agent; its session cwd anchors relative paths.',
           source: 'lookup',
           lookup: 'agent',
           codec: {
@@ -213,17 +265,33 @@ export const TYPERT_REMOTE = {
             typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
             create: _khorsheed_dsh_file_preview_filePreview_read_parameter_0$schema,
             schema: _khorsheed_dsh_file_preview_filePreview_read_parameter_0$schema(),
+            jsonSchema: {"type":"string"},
+          },
+          strictCodec: {
+            mode: 'strict',
+            typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
+            create: _khorsheed_dsh_file_preview_filePreview_read_parameter_0_strict$schema,
+            schema: _khorsheed_dsh_file_preview_filePreview_read_parameter_0_strict$schema(),
+            jsonSchema: {"type":"string"},
           },
         },
         {
           name: 'path',
-          wire: 'path',
+          description: 'the display path recorded by the write/edit tool call.',
           source: 'json',
           codec: {
             mode: 'strict',
             typeSymbol: '@khorsheed/dsh-file-preview#filePreview/read:path',
             create: _khorsheed_dsh_file_preview_filePreview_read_parameter_1$schema,
             schema: _khorsheed_dsh_file_preview_filePreview_read_parameter_1$schema(),
+            jsonSchema: {"type":"string"},
+          },
+          strictCodec: {
+            mode: 'strict',
+            typeSymbol: '@khorsheed/dsh-file-preview#filePreview/read:path',
+            create: _khorsheed_dsh_file_preview_filePreview_read_parameter_1_strict$schema,
+            schema: _khorsheed_dsh_file_preview_filePreview_read_parameter_1_strict$schema(),
+            jsonSchema: {"type":"string"},
           },
         },
       ],
@@ -233,14 +301,14 @@ export const TYPERT_REMOTE = {
         typeSymbol: '@khorsheed/dsh-file-preview/types#FilePreviewRead',
         create: _khorsheed_dsh_file_preview_filePreview_read_result$schema,
         schema: _khorsheed_dsh_file_preview_filePreview_read_result$schema(),
+        description: 'the classified read; `text` carries content, `image` carries a browser URL, other kinds carry the size or a human-readable reason.',
+        jsonSchema: {"type":"object","properties":{"path":{"type":"string","description":"The resolved display path of the read target."},"kind":{"type":"string","enum":["text","image","error","missing","too-large","binary"],"description":"Outcome classification; `text`/`image` carry a renderable value, `error` carries message."},"content":{"type":"string","description":"Current text content for `text` reads, capped by the service's `maxReadBytes` (HTML files by `htmlMaxReadBytes`)."},"url":{"type":"string","description":"Browser-loadable URL for `image` reads (host-served bytes, session-scoped)."},"truncated":{"type":"boolean","description":"Whether `content` was truncated to the byte cap."},"htmlScripted":{"type":"boolean","description":"HTML files only: best-effort hint that the document contains scripts (`<script>` tags, inline event handlers, or `javascript:` URLs). A hint for default-mode selection and warning — never a trust decision; the sandbox and CSP are the real boundary. Absent for non-HTML reads and for HTML without script markers."},"size":{"type":"number","description":"Byte size of the file when the backend reported one."},"message":{"type":"string","description":"Human-readable failure detail for `error` reads."}},"required":["path","kind"],"additionalProperties":true},
       },
-      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":409,"column":9},
+      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":286,"column":9},
     },
-    {
-      id: '@khorsheed/dsh-file-preview#filePreview/reveal',
+    'filePreview/reveal': {
       service: 'filePreview',
-      namespace: 'filePreview',
-      method: 'reveal',
+      description: '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.',
       invocation: { kind: 'direct' },
       scope: {
         context: 'agent',
@@ -250,6 +318,7 @@ export const TYPERT_REMOTE = {
         {
           name: 'agent',
           wire: 'agentId',
+          description: 'owning live agent; its session cwd anchors relative paths.',
           source: 'lookup',
           lookup: 'agent',
           codec: {
@@ -257,17 +326,33 @@ export const TYPERT_REMOTE = {
             typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
             create: _khorsheed_dsh_file_preview_filePreview_reveal_parameter_0$schema,
             schema: _khorsheed_dsh_file_preview_filePreview_reveal_parameter_0$schema(),
+            jsonSchema: {"type":"string"},
+          },
+          strictCodec: {
+            mode: 'strict',
+            typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
+            create: _khorsheed_dsh_file_preview_filePreview_reveal_parameter_0_strict$schema,
+            schema: _khorsheed_dsh_file_preview_filePreview_reveal_parameter_0_strict$schema(),
+            jsonSchema: {"type":"string"},
           },
         },
         {
           name: 'path',
-          wire: 'path',
+          description: 'the display path recorded by the read/write/edit tool call.',
           source: 'json',
           codec: {
             mode: 'strict',
             typeSymbol: '@khorsheed/dsh-file-preview#filePreview/reveal:path',
             create: _khorsheed_dsh_file_preview_filePreview_reveal_parameter_1$schema,
             schema: _khorsheed_dsh_file_preview_filePreview_reveal_parameter_1$schema(),
+            jsonSchema: {"type":"string"},
+          },
+          strictCodec: {
+            mode: 'strict',
+            typeSymbol: '@khorsheed/dsh-file-preview#filePreview/reveal:path',
+            create: _khorsheed_dsh_file_preview_filePreview_reveal_parameter_1_strict$schema,
+            schema: _khorsheed_dsh_file_preview_filePreview_reveal_parameter_1_strict$schema(),
+            jsonSchema: {"type":"string"},
           },
         },
       ],
@@ -277,14 +362,14 @@ export const TYPERT_REMOTE = {
         typeSymbol: '@khorsheed/dsh-file-preview/types#FilePreviewReveal',
         create: _khorsheed_dsh_file_preview_filePreview_reveal_result$schema,
         schema: _khorsheed_dsh_file_preview_filePreview_reveal_result$schema(),
+        description: 'whether the file manager selected the file, or why not.',
+        jsonSchema: {"oneOf":[{"type":"object","properties":{"revealed":{"type":"boolean","const":true,"description":"The host file manager opened the file's folder with the file selected."}},"required":["revealed"],"additionalProperties":true},{"type":"object","properties":{"revealed":{"type":"boolean","const":false,"description":"The file could not be revealed; the caller opens the parent folder instead."},"reason":{"type":"string","enum":["missing","select-failed"],"description":"Why: `missing` = the recorded path does not resolve to an existing target; `select-failed` = the host could not select the file."}},"required":["revealed","reason"],"additionalProperties":true}]},
       },
-      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":489,"column":9},
+      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":319,"column":9},
     },
-    {
-      id: '@khorsheed/dsh-file-preview#filePreview/turnFiles',
+    'filePreview/turnFiles': {
       service: 'filePreview',
-      namespace: 'filePreview',
-      method: 'turnFiles',
+      description: '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, 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. 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.',
       invocation: { kind: 'direct' },
       scope: {
         context: 'agent',
@@ -294,6 +379,7 @@ export const TYPERT_REMOTE = {
         {
           name: 'agent',
           wire: 'agentId',
+          description: 'owning live agent; its session log is the data source.',
           source: 'lookup',
           lookup: 'agent',
           codec: {
@@ -301,6 +387,14 @@ export const TYPERT_REMOTE = {
             typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
             create: _khorsheed_dsh_file_preview_filePreview_turnFiles_parameter_0$schema,
             schema: _khorsheed_dsh_file_preview_filePreview_turnFiles_parameter_0$schema(),
+            jsonSchema: {"type":"string"},
+          },
+          strictCodec: {
+            mode: 'strict',
+            typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
+            create: _khorsheed_dsh_file_preview_filePreview_turnFiles_parameter_0_strict$schema,
+            schema: _khorsheed_dsh_file_preview_filePreview_turnFiles_parameter_0_strict$schema(),
+            jsonSchema: {"type":"string"},
           },
         },
       ],
@@ -309,10 +403,12 @@ export const TYPERT_REMOTE = {
         typeSymbol: '@khorsheed/dsh-file-preview/types#FilePreviewTurnMap',
         create: _khorsheed_dsh_file_preview_filePreview_turnFiles_result$schema,
         schema: _khorsheed_dsh_file_preview_filePreview_turnFiles_result$schema(),
+        description: 'existing per-turn file groups plus the scanned watermark.',
+        jsonSchema: {"type":"object","properties":{"turns":{"type":"array","items":{"type":"object","properties":{"turn":{"type":"number"},"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","description":"The display path (absolute for bash-captured writes; as-recorded otherwise)."},"seq":{"type":"number","description":"Seq of the first mutation recorded for this path in this turn (stable ordering)."},"step":{"type":"number"},"added":{"type":"number","description":"Lines added across the turn's mutations of this path."},"removed":{"type":"number","description":"Lines removed; 0 for a create; absent when an uncounted mutation (a write whose prior content was not diffable, a PTC dispatch) reported no total."}},"required":["path","seq","step"],"additionalProperties":true}}},"required":["turn","files"],"additionalProperties":true},"description":"Files mutated per turn, in event order within each turn."},"asOfSeq":{"type":"number","description":"Seq of the last scanned session event (cache invalidation watermark)."}},"required":["turns","asOfSeq"],"additionalProperties":true},
       },
-      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":353,"column":9},
+      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":253,"column":9},
     },
-  ],
-}
+  },
+}, z)
 
 export default TYPERT_REMOTE

package/lib/types/bash-writes.d.ts

@@ -16,6 +16,7 @@
  * @module @khorsheed/dsh-file-preview
  */
 import type { Context } from '@deepseek-ai/cordis';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
 import type { FileSystem } from '@deepseek-ai/dsh-fs';
 /** One verified captured write, merged into the fold as a `write` entry. */
 export interface CapturedWrite {
@@ -53,7 +54,9 @@ export declare function extractWriteTargets(command: string): string[];
 export declare function expandShellPath(token: string, env: NodeJS.ProcessEnv, home: string, cwd: string | undefined): string | null;
 /** Options for {@link BashWriteCollector}. */
 export interface BashWriteCollectorOptions {
-    fs: FileSystem;
+    /** The fs face candidates resolve and stat through (the two members the
+     * collector reads from `ctx.fs`; any face honoring the same contract plugs in). */
+    fs: Pick<FileSystem, 'resolve' | 'stat'>;
     env?: NodeJS.ProcessEnv;
     home?: string;
     /** Cap on captured writes per session (mirrors the fold's maxFiles). */
@@ -79,5 +82,20 @@ export declare class BashWriteCollector {
     attach(ctx: Context): () => void;
     /** Verified captures for one session (the fold-merge source), or undefined. */
     captured(sessionId: string): ReadonlyMap<string, CapturedWrite> | undefined;
+    /**
+     * Rebuild one session's captures from its own event snapshot — the
+     * snapshot-driven twin of the live feed's replay, for a caller that holds
+     * the session's events rather than a composition's event feed. The same
+     * extraction, expansion, and stat-verification pipeline runs in event
+     * order, every verification awaited, so the result mirrors what the live
+     * feed would have captured from the same events. Nothing is stored in the
+     * live registry: pending candidates and verified captures are local to the
+     * call.
+     * @param cwd - the session's cwd for relative write targets, or undefined.
+     * @param events - the session's events in ascending seq order.
+     * @returns the verified captures (undefined when none survived, mirroring
+     *   `captured`).
+     */
+    replaySnapshot(cwd: string | undefined, events: readonly SessionEvent[]): Promise<ReadonlyMap<string, CapturedWrite> | undefined>;
 }
 //# sourceMappingURL=bash-writes.d.ts.map

package/lib/types/bash-writes.js

@@ -301,6 +301,56 @@ export class BashWriteCollector {
     captured(sessionId) {
         return this.#captured.get(sessionId);
     }
+    /**
+     * Rebuild one session's captures from its own event snapshot — the
+     * snapshot-driven twin of the live feed's replay, for a caller that holds
+     * the session's events rather than a composition's event feed. The same
+     * extraction, expansion, and stat-verification pipeline runs in event
+     * order, every verification awaited, so the result mirrors what the live
+     * feed would have captured from the same events. Nothing is stored in the
+     * live registry: pending candidates and verified captures are local to the
+     * call.
+     * @param cwd - the session's cwd for relative write targets, or undefined.
+     * @param events - the session's events in ascending seq order.
+     * @returns the verified captures (undefined when none survived, mirroring
+     *   `captured`).
+     */
+    async replaySnapshot(cwd, events) {
+        const pending = new Map();
+        const captured = new Map();
+        for (const event of events) {
+            if (event.type === 'tool/call') {
+                if (event.data.name !== 'bash')
+                    continue;
+                const command = parseArguments(event.data.arguments).command;
+                if (typeof command !== 'string' || command.length === 0)
+                    continue;
+                const candidates = extractWriteTargets(command)
+                    .map(token => expandShellPath(token, this.#env, this.#home, cwd))
+                    .filter((path) => path !== null);
+                if (candidates.length === 0)
+                    continue;
+                pending.set(String(event.data.callId), {
+                    turn: event.data.turn,
+                    step: event.data.step,
+                    seq: event.seq,
+                    candidates,
+                });
+                continue;
+            }
+            if (event.type === 'tool/result') {
+                const callId = String(event.data.message?.source?.callId ?? '');
+                const write = pending.get(callId);
+                if (write === undefined)
+                    continue;
+                pending.delete(callId);
+                // Awaited in event order so the capture map's contents and insertion
+                // order are the deterministic twin of the live feed's.
+                await this.#verifyInto(captured, write);
+            }
+        }
+        return captured.size === 0 ? undefined : captured;
+    }
     /** Rebuild one session's registry from its own history (host restart). */
     #replay(session) {
         this.#pending.set(session.id, new Map());
@@ -345,6 +395,12 @@ export class BashWriteCollector {
     /** stat-verify the pending candidates and store the survivors. */
     async #verify(session, pending) {
         const captured = this.#captured.get(session.id) ?? new Map();
+        await this.#verifyInto(captured, pending);
+        if (captured.size > 0)
+            this.#captured.set(session.id, captured);
+    }
+    /** stat-verify the pending candidates into the given capture map. */
+    async #verifyInto(captured, pending) {
         for (const candidate of pending.candidates) {
             if (captured.size >= this.#maxFiles || captured.has(candidate))
                 continue;
@@ -361,7 +417,5 @@ export class BashWriteCollector {
                 captured.set(candidate, { turn: pending.turn, step: pending.step, seq: pending.seq });
             }
         }
-        if (captured.size > 0)
-            this.#captured.set(session.id, captured);
     }
 }