@khorsheed/dsh-file-preview 0.2.0 → 0.3.1

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

@@ -4,17 +4,21 @@ import type {
   TypertRemoteContribution,
 } from '@deepseek-ai/dsh-typert-protocol'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
-import type { FilePreviewList, FilePreviewRead, FilePreviewReveal, FilePreviewTurnMap } from '@khorsheed/dsh-file-preview/types'
+import type { FilePreviewList, FilePreviewOpenExternal, FilePreviewRead, FilePreviewReveal, FilePreviewTurnMap } from '@khorsheed/dsh-file-preview/types'
 
 declare module '@deepseek-ai/dsh-typert-protocol' {
   interface TypertRemoteNamespace$66696c6550726576696577 {
+    capabilities: () => Promise<RemoteResult<{ protocolVersion: 1; }>>
     list: (agentId: SessionId) => Promise<RemoteResult<FilePreviewList>>
+    openExternal: (agentId: SessionId, path: string, app: string, signal?: AbortSignal) => Promise<RemoteResult<FilePreviewOpenExternal>>
     read: (agentId: SessionId, path: string, signal?: AbortSignal) => Promise<RemoteResult<FilePreviewRead>>
     reveal: (agentId: SessionId, path: string, signal?: AbortSignal) => Promise<RemoteResult<FilePreviewReveal>>
     turnFiles: (agentId: SessionId) => Promise<RemoteResult<FilePreviewTurnMap>>
   }
   interface TypertRemoteMap {
+    'filePreview/capabilities': () => Promise<RemoteResult<{ protocolVersion: 1; }>>
     'filePreview/list': (agentId: SessionId) => Promise<RemoteResult<FilePreviewList>>
+    'filePreview/openExternal': (agentId: SessionId, path: string, app: string, signal?: AbortSignal) => Promise<RemoteResult<FilePreviewOpenExternal>>
     'filePreview/read': (agentId: SessionId, path: string, signal?: AbortSignal) => Promise<RemoteResult<FilePreviewRead>>
     'filePreview/reveal': (agentId: SessionId, path: string, signal?: AbortSignal) => Promise<RemoteResult<FilePreviewReveal>>
     'filePreview/turnFiles': (agentId: SessionId) => Promise<RemoteResult<FilePreviewTurnMap>>
@@ -24,6 +28,7 @@ declare module '@deepseek-ai/dsh-typert-protocol' {
   }
   interface TypertRemoteScopeMap {
     'agent:filePreview/list': () => Promise<RemoteResult<FilePreviewList>>
+    'agent:filePreview/openExternal': (path: string, app: string, signal?: AbortSignal) => Promise<RemoteResult<FilePreviewOpenExternal>>
     'agent:filePreview/read': (path: string, signal?: AbortSignal) => Promise<RemoteResult<FilePreviewRead>>
     'agent:filePreview/reveal': (path: string, signal?: AbortSignal) => Promise<RemoteResult<FilePreviewReveal>>
     'agent:filePreview/turnFiles': () => Promise<RemoteResult<FilePreviewTurnMap>>

package/lib/typert.remote-client.js

@@ -1,8 +1,14 @@
 /* Generated by @deepseek-ai/dsh-typert-generator from the Host FaceModel — do not edit. */
 import { z } from 'zod'
 
-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({
+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()))
+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(),
@@ -23,29 +29,50 @@ const _khorsheed_dsh_file_preview_filePreview_list_result$schema = z.object({
 })).readonly(),
   'asOfSeq': z.number().readonly(),
   'truncated': z.boolean().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({
+}))
+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()))
+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(),
+}), 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(),
+})]))
+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()))
+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("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("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(),
-})
-const _khorsheed_dsh_file_preview_filePreview_reveal_parameter_0$schema = z.intersection(z.string(), z.unknown())
-const _khorsheed_dsh_file_preview_filePreview_reveal_parameter_1$schema = z.string()
-const _khorsheed_dsh_file_preview_filePreview_reveal_result$schema = z.union([z.object({
+}))
+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()))
+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(),
 }), z.object({
   'revealed': z.literal(false).readonly(),
   'reason': z.union([z.literal("missing"), z.literal("select-failed")]).readonly(),
-})])
-const _khorsheed_dsh_file_preview_filePreview_turnFiles_parameter_0$schema = z.intersection(z.string(), z.unknown())
-const _khorsheed_dsh_file_preview_filePreview_turnFiles_result$schema = z.object({
+})]))
+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()))
+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({
@@ -57,11 +84,27 @@ const _khorsheed_dsh_file_preview_filePreview_turnFiles_result$schema = z.object
 })).readonly(),
 })).readonly(),
   'asOfSeq': z.number().readonly(),
-})
+}))
 
 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',
+        create: _khorsheed_dsh_file_preview_filePreview_capabilities_result$schema,
+        schema: _khorsheed_dsh_file_preview_filePreview_capabilities_result$schema(),
+      },
+      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":196,"column":3},
+    },
     {
       id: '@khorsheed/dsh-file-preview#filePreview/list',
       service: 'filePreview',
@@ -81,16 +124,73 @@ export const TYPERT_REMOTE = {
           codec: {
             mode: 'strict',
             typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
-            schema: _khorsheed_dsh_file_preview_filePreview_list_parameter_0$schema,
+            create: _khorsheed_dsh_file_preview_filePreview_list_parameter_0$schema,
+            schema: _khorsheed_dsh_file_preview_filePreview_list_parameter_0$schema(),
           },
         },
       ],
       result: {
         mode: 'strict',
         typeSymbol: '@khorsheed/dsh-file-preview/types#FilePreviewList',
-        schema: _khorsheed_dsh_file_preview_filePreview_list_result$schema,
+        create: _khorsheed_dsh_file_preview_filePreview_list_result$schema,
+        schema: _khorsheed_dsh_file_preview_filePreview_list_result$schema(),
+      },
+      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":316,"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',
+            create: _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_0$schema,
+            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',
+            create: _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_1$schema,
+            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',
+            create: _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_2$schema,
+            schema: _khorsheed_dsh_file_preview_filePreview_openExternal_parameter_2$schema(),
+          },
+        },
+      ],
+      cancellation: { parameter: 'signal' },
+      result: {
+        mode: 'strict',
+        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(),
       },
-      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":368,"column":9},
+      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":539,"column":9},
     },
     {
       id: '@khorsheed/dsh-file-preview#filePreview/read',
@@ -111,7 +211,8 @@ export const TYPERT_REMOTE = {
           codec: {
             mode: 'strict',
             typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
-            schema: _khorsheed_dsh_file_preview_filePreview_read_parameter_0$schema,
+            create: _khorsheed_dsh_file_preview_filePreview_read_parameter_0$schema,
+            schema: _khorsheed_dsh_file_preview_filePreview_read_parameter_0$schema(),
           },
         },
         {
@@ -121,7 +222,8 @@ export const TYPERT_REMOTE = {
           codec: {
             mode: 'strict',
             typeSymbol: '@khorsheed/dsh-file-preview#filePreview/read:path',
-            schema: _khorsheed_dsh_file_preview_filePreview_read_parameter_1$schema,
+            create: _khorsheed_dsh_file_preview_filePreview_read_parameter_1$schema,
+            schema: _khorsheed_dsh_file_preview_filePreview_read_parameter_1$schema(),
           },
         },
       ],
@@ -129,9 +231,10 @@ export const TYPERT_REMOTE = {
       result: {
         mode: 'strict',
         typeSymbol: '@khorsheed/dsh-file-preview/types#FilePreviewRead',
-        schema: _khorsheed_dsh_file_preview_filePreview_read_result$schema,
+        create: _khorsheed_dsh_file_preview_filePreview_read_result$schema,
+        schema: _khorsheed_dsh_file_preview_filePreview_read_result$schema(),
       },
-      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":458,"column":9},
+      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":409,"column":9},
     },
     {
       id: '@khorsheed/dsh-file-preview#filePreview/reveal',
@@ -152,7 +255,8 @@ export const TYPERT_REMOTE = {
           codec: {
             mode: 'strict',
             typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
-            schema: _khorsheed_dsh_file_preview_filePreview_reveal_parameter_0$schema,
+            create: _khorsheed_dsh_file_preview_filePreview_reveal_parameter_0$schema,
+            schema: _khorsheed_dsh_file_preview_filePreview_reveal_parameter_0$schema(),
           },
         },
         {
@@ -162,7 +266,8 @@ export const TYPERT_REMOTE = {
           codec: {
             mode: 'strict',
             typeSymbol: '@khorsheed/dsh-file-preview#filePreview/reveal:path',
-            schema: _khorsheed_dsh_file_preview_filePreview_reveal_parameter_1$schema,
+            create: _khorsheed_dsh_file_preview_filePreview_reveal_parameter_1$schema,
+            schema: _khorsheed_dsh_file_preview_filePreview_reveal_parameter_1$schema(),
           },
         },
       ],
@@ -170,9 +275,10 @@ export const TYPERT_REMOTE = {
       result: {
         mode: 'strict',
         typeSymbol: '@khorsheed/dsh-file-preview/types#FilePreviewReveal',
-        schema: _khorsheed_dsh_file_preview_filePreview_reveal_result$schema,
+        create: _khorsheed_dsh_file_preview_filePreview_reveal_result$schema,
+        schema: _khorsheed_dsh_file_preview_filePreview_reveal_result$schema(),
       },
-      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":535,"column":9},
+      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":489,"column":9},
     },
     {
       id: '@khorsheed/dsh-file-preview#filePreview/turnFiles',
@@ -193,16 +299,18 @@ export const TYPERT_REMOTE = {
           codec: {
             mode: 'strict',
             typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
-            schema: _khorsheed_dsh_file_preview_filePreview_turnFiles_parameter_0$schema,
+            create: _khorsheed_dsh_file_preview_filePreview_turnFiles_parameter_0$schema,
+            schema: _khorsheed_dsh_file_preview_filePreview_turnFiles_parameter_0$schema(),
           },
         },
       ],
       result: {
         mode: 'strict',
         typeSymbol: '@khorsheed/dsh-file-preview/types#FilePreviewTurnMap',
-        schema: _khorsheed_dsh_file_preview_filePreview_turnFiles_result$schema,
+        create: _khorsheed_dsh_file_preview_filePreview_turnFiles_result$schema,
+        schema: _khorsheed_dsh_file_preview_filePreview_turnFiles_result$schema(),
       },
-      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":405,"column":9},
+      sourceLocation: {"file":"packages/file-preview/src/index.ts","line":353,"column":9},
     },
   ],
 }

package/lib/types/fold.d.ts

@@ -26,10 +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, or
- * `tool/ptc-dispatch` on seats running the PTC rename) 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.
@@ -58,7 +59,7 @@ export type TurnFilesByTurn = ReadonlyMap<number, ReadonlyMap<string, TurnFileFa
  * turn maps, so each turn's card lists exactly what that turn mutated.
  * 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 Code Mode dispatches borrow the enclosing root call's
+ * 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
@@ -69,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

@@ -1,14 +1,6 @@
 /** 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']);
-/**
- * Settled nested-dispatch event names, matched by name (feature detection,
- * never a version check): `tool/code-dispatch` is the Code Mode name every
- * host through 0.1.2-rc.1 emits; `tool/ptc-dispatch` is the PTC rename later
- * 0.1.2 seats move to. Both carry the same settled-dispatch payload, so one
- * branch serves either.
- */
-const DISPATCH_EVENT_NAMES = new Set(['tool/code-dispatch', 'tool/ptc-dispatch']);
 /** The argument key carrying the touched path (shared by all three file tools). */
 const FILE_PATH_ARGUMENT = 'file_path';
 /**
@@ -65,10 +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, or
- * `tool/ptc-dispatch` on seats running the PTC rename) 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.
@@ -76,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. */
@@ -97,19 +90,16 @@ export function foldFilePreview(events, maxFiles) {
             record(target, event.seq, event.data.turn, event.data.step);
             continue;
         }
-        if (DISPATCH_EVENT_NAMES.has(event.type)) {
+        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. The PTC rename keeps
-            // the code-dispatch payload shape (the ptc name has no SessionEventMap
-            // row yet), so the data reads through the declared constituent.
-            const dispatch = event;
-            if (dispatch.data.isError)
+            // nothing, so only successful file touches record.
+            if (event.data.isError)
                 continue;
-            const target = targetFromArguments(dispatch.data.name, dispatch.data.arguments);
+            const target = targetFromArguments(event.data.name, event.data.arguments);
             if (target === undefined)
                 continue;
-            const site = callSites.get(String(dispatch.data.rootCallId)) ?? { turn: 0, step: 0 };
-            record(target, dispatch.seq, site.turn, site.step);
+            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') {
@@ -172,8 +162,13 @@ function contentFromWriteCall(argumentsJson) {
     }
     return undefined;
 }
-/** Read the tool-result block's call identity and failure flag off a result message. */
+/** Read the result message's call identity and failure flag. V4's first-class
+ *  tool role puts both on the message itself; V3 wrapped them in the leading
+ *  `tool-result` content block — read the message level first, then the block. */
 function resultCallFacts(message) {
+    if (typeof message.toolCallId === 'string') {
+        return { callId: message.toolCallId, isError: message.isError === true };
+    }
     const block = message.content[0];
     if (block?.type !== 'tool-result' || typeof block.toolCallId !== 'string')
         return undefined;
@@ -186,7 +181,7 @@ function resultCallFacts(message) {
  * turn maps, so each turn's card lists exactly what that turn mutated.
  * 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 Code Mode dispatches borrow the enclosing root call's
+ * 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
@@ -197,7 +192,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.
@@ -205,7 +200,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();
@@ -235,7 +230,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);
@@ -271,7 +266,7 @@ export function foldFilePreviewByTurn(events) {
             if (target === undefined)
                 continue;
             // The card's vocabulary is mutations only: a read call registers
-            // nothing (it may still anchor a nested code dispatch's location via
+            // nothing (it may still anchor a nested dispatch's location via
             // callSites above).
             if (target.op === 'read')
                 continue;
@@ -286,24 +281,22 @@ export function foldFilePreviewByTurn(events) {
             recordLocation(target.path, event.data.turn, event.seq, event.data.step);
             continue;
         }
-        if (DISPATCH_EVENT_NAMES.has(event.type)) {
+        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). Same payload
-            // shape caveat as foldFilePreview above.
-            const dispatch = event;
-            if (dispatch.data.isError)
+            // path and poison the line-count totals (unknown wins).
+            if (event.data.isError)
                 continue;
-            const target = targetFromArguments(dispatch.data.name, dispatch.data.arguments);
+            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(dispatch.data.rootCallId)) ?? { turn: 0, step: 0 };
+            const site = callSites.get(String(event.data.rootCallId)) ?? { turn: 0, step: 0 };
             sessionSeen.add(target.path);
-            recordContribution(target.path, site.turn, dispatch.seq, site.step, undefined, undefined, true);
+            recordContribution(target.path, site.turn, event.seq, site.step, undefined, undefined, true);
             continue;
         }
         if (event.type === 'tool/result') {

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;
@@ -33,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. */
@@ -46,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
@@ -81,7 +88,7 @@ export declare class FilePreviewService extends TypertRemoteService {
     /**
      * 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
@@ -96,7 +103,10 @@ export declare class FilePreviewService extends TypertRemoteService {
     turnFiles(agent: Agent): Promise<FilePreviewTurnMap>;
     /**
      * Read the current content of one recorded file, resolved against the
-     * session cwd and capped by `maxReadBytes`.
+     * 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.
      * @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.
@@ -118,6 +128,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