@khorsheed/dsh-file-preview 0.2.0 → 0.3.0

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') {
@@ -186,7 +176,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 +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.
@@ -205,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();
@@ -235,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);
@@ -271,7 +261,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 +276,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
@@ -118,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

package/lib/types/index.js

@@ -35,64 +35,12 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
     if (target) Object.defineProperty(target, contextIn.name, descriptor);
     done = true;
 };
-import { readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import z from '@deepseek-ai/schemastery';
 import { BashWriteCollector } from './bash-writes.js';
 import { foldFilePreview, foldFilePreviewByTurn } from './fold.js';
+import { openExternalNative, macAppName } from './open-external.js';
 import { revealNativePath } from './reveal.js';
-/**
- * Register the 3d-artifact skill — the generation-side contract for
- * sandbox-runnable interactive 3D / digital-twin single-file HTML (self-
- * contained, zero runtime network, GLB-inline zero-fetch models). Pull-based
- * discovery: an agent whose task involves generating such an HTML page finds
- * the contract through the skill catalog — no per-session push notice.
- * Optional: compositions without the skill capability skip the registration.
- * A missing/malformed shipped SKILL.md degrades to a warning — a discovery
- * aid must never take a boot down; the pack-smoke test owns the file's
- * presence in the tarball.
- * @param ctx - plugin context.
- */
-function registerArtifactSkill(ctx) {
-    const skills = ctx.get('skills');
-    if (skills === undefined) {
-        // Not a crash: file preview degrades without the skill (and a minimal
-        // composition may legitimately lack the capability). The line exists so a
-        // host-API migration that drops or renames the skills service shows up in
-        // boot logs instead of failing silently — same diagnostic as ankh-guard's
-        // restart-skill registration; grep "skill .* not registered".
-        ctx.logger.warn('file-preview: skills capability absent — the 3d-artifact skill is not registered');
-        return;
-    }
-    try {
-        const skillDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'skills', '3d-artifact');
-        const skillFile = join(skillDir, 'SKILL.md');
-        const raw = readFileSync(skillFile, 'utf8');
-        const match = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/.exec(raw);
-        const name = /^name: (.+)$/m.exec(match?.[1] ?? '')?.[1]?.trim();
-        const description = /^description: (.+)$/m.exec(match?.[1] ?? '')?.[1]?.trim();
-        const content = match?.[2];
-        if (match === null || name === undefined || description === undefined || content === undefined) {
-            ctx.logger.warn('file-preview: shipped SKILL.md is malformed — the 3d-artifact skill is not registered');
-            return;
-        }
-        ctx.effect(() => skills.register({
-            name,
-            description,
-            content,
-            source: 'runtime',
-            provider: 'file-preview',
-            // Content-only (only SKILL.md in the bundle): no `resourceBase`, so the
-            // catalog renders a virtual single-SKILL.md node. Add `resourceBase`
-            // only when the bundle later gains scripts/assets beside SKILL.md.
-        }));
-    }
-    catch (error) {
-        ctx.logger.warn(`file-preview: shipped SKILL.md unreadable (${String(error)}) — the 3d-artifact skill is not registered`);
-    }
-}
 /** Extensions treated as binary without reading (their text decode is meaningless). */
 const BINARY_EXTENSIONS = new Set([
     '.pdf', '.zip', '.gz', '.tar', '.7z', '.zstd', '.br',
@@ -165,21 +113,27 @@ function readErrorMessage(error) {
 let FilePreviewService = (() => {
     let _classSuper = TypertRemoteService;
     let _instanceExtraInitializers = [];
+    let _capabilities_decorators;
     let _list_decorators;
     let _turnFiles_decorators;
     let _read_decorators;
     let _reveal_decorators;
+    let _openExternal_decorators;
     return class FilePreviewService extends _classSuper {
         static {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _capabilities_decorators = [Remote('capabilities')];
             _list_decorators = [Remote('list')];
             _turnFiles_decorators = [Remote('turnFiles')];
             _read_decorators = [Remote('read')];
             _reveal_decorators = [Remote('reveal')];
+            _openExternal_decorators = [Remote('openExternal')];
+            __esDecorate(this, null, _capabilities_decorators, { kind: "method", name: "capabilities", static: false, private: false, access: { has: obj => "capabilities" in obj, get: obj => obj.capabilities }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _list_decorators, { kind: "method", name: "list", static: false, private: false, access: { has: obj => "list" in obj, get: obj => obj.list }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _turnFiles_decorators, { kind: "method", name: "turnFiles", static: false, private: false, access: { has: obj => "turnFiles" in obj, get: obj => obj.turnFiles }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _read_decorators, { kind: "method", name: "read", static: false, private: false, access: { has: obj => "read" in obj, get: obj => obj.read }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _reveal_decorators, { kind: "method", name: "reveal", static: false, private: false, access: { has: obj => "reveal" in obj, get: obj => obj.reveal }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _openExternal_decorators, { kind: "method", name: "openExternal", static: false, private: false, access: { has: obj => "openExternal" in obj, get: obj => obj.openExternal }, metadata: _metadata }, null, _instanceExtraInitializers);
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
         static inject = ['fs'];
@@ -199,6 +153,8 @@ let FilePreviewService = (() => {
         agents;
         /** Native reveal runner; a constructor seam for deterministic tests. */
         revealNative;
+        /** Native open-in-app runner; a constructor seam for deterministic tests. */
+        openExternalNative;
         /** Bash-write collector (S2 seam), or undefined when disabled in config. */
         collector;
         /** Per-session by-turn fold cache, invalidated by the log watermark. */
@@ -219,6 +175,7 @@ let FilePreviewService = (() => {
                 captureBashWrites: config.captureBashWrites ?? true,
             };
             this.revealNative = deps.revealNative ?? revealNativePath;
+            this.openExternalNative = deps.openExternalNative ?? openExternalNative;
             if (config.captureBashWrites !== false) {
                 this.collector = new BashWriteCollector({ fs: this.fs, maxFiles: this.resolved.maxFiles });
                 ctx.effect(() => this.collector.attach(ctx), 'file-preview: bash-write capture');
@@ -239,7 +196,10 @@ let FilePreviewService = (() => {
                     handler: (req, res) => { void this.serveImage(req, res); },
                 }), 'file-preview: image route');
             }
-            registerArtifactSkill(ctx);
+        }
+        /** Zero-session availability handshake for browser companions. */
+        capabilities() {
+            return { protocolVersion: 1 };
         }
         get fs() {
             return this.ctx.fs;
@@ -385,7 +345,7 @@ let FilePreviewService = (() => {
         /**
          * 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
@@ -567,6 +527,53 @@ let FilePreviewService = (() => {
                 return { revealed: false, reason: 'select-failed' };
             }
         }
+        /**
+         * 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.
+         */
+        async openExternal(agent, path, app, signal) {
+            if (typeof path !== 'string' || path.length === 0 || typeof app !== 'string' || app.length === 0) {
+                return { opened: false, reason: 'missing' };
+            }
+            if (macAppName(app) === undefined)
+                return { opened: false, reason: 'unknown-app' };
+            const cwd = agent.session.header.cwd;
+            let target;
+            try {
+                target = await this.fs.resolve(path, cwd === undefined ? { signal } : { cwd, signal });
+            }
+            catch {
+                return { opened: false, reason: 'missing' };
+            }
+            let info;
+            try {
+                info = await this.fs.stat(target, signal);
+            }
+            catch {
+                info = undefined;
+            }
+            if (info === undefined)
+                return { opened: false, reason: 'missing' };
+            try {
+                await this.openExternalNative(this.fs.processPath(target), app, signal);
+                return { opened: true };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return { opened: false, reason: message.startsWith('open-in-app is unsupported on ') ? 'unsupported-platform' : 'launch-failed' };
+            }
+        }
     };
 })();
 export { FilePreviewService };

package/lib/types/open-external.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Native "open this file in a specific application" dispatch used by the
+ * file-preview Remote's `openExternal` method (the "open in IDE" gesture).
+ *
+ * The official open-in-app route (`POST /open-in-app/open`) only accepts
+ * directories — a file path 404s — so file-exact opens carry their own
+ * dispatch here. macOS only: `open -a <App> <path>` through the official
+ * `@deepseek-ai/dsh-native-command` runner (no shell, abort propagation),
+ * mirroring `reveal.ts`'s discipline. The browser picks the application by
+ * official open-in-app catalog id (probed from `/open-in-app/apps`); the
+ * id → `.app` name map below mirrors the official catalog's darwin entries
+ * (packages/host/open-in-app/src/catalog.ts at 0.1.5-rc.1 — re-check on every
+ * host upgrade). Other platforms and unknown ids answer unsupported, and the
+ * client hides the gesture.
+ * @module @khorsheed/dsh-file-preview
+ */
+import { type NativeCommandRunner } from '@deepseek-ai/dsh-native-command';
+/** Injectable platform facts for deterministic adapter tests. */
+export interface OpenExternalInternals {
+    platform?: NodeJS.Platform;
+    run?: NativeCommandRunner;
+}
+/** The application name one catalog id maps to, or undefined when unknown. */
+export declare function macAppName(appId: string): string | undefined;
+/**
+ * Open one file in the named application. Throws when the platform is not
+ * macOS or the catalog id is unknown — the caller maps both to an
+ * `unsupported`/`unknown-app` answer and the client hides the gesture. A
+ * launch failure propagates as the runner's rejection.
+ * @param path - absolute path in the host's execution world (caller owns
+ *   resolution, typically `FileSystem.processPath`).
+ * @param appId - official open-in-app catalog id (e.g. `cursor`).
+ * @param signal - caller/connection lifetime; abort terminates the native command.
+ * @param internals - platform seam for deterministic tests.
+ */
+export declare function openExternalNative(path: string, appId: string, signal: AbortSignal, internals?: OpenExternalInternals): Promise<void>;
+//# sourceMappingURL=open-external.d.ts.map

package/lib/types/open-external.js

@@ -0,0 +1,61 @@
+/**
+ * Native "open this file in a specific application" dispatch used by the
+ * file-preview Remote's `openExternal` method (the "open in IDE" gesture).
+ *
+ * The official open-in-app route (`POST /open-in-app/open`) only accepts
+ * directories — a file path 404s — so file-exact opens carry their own
+ * dispatch here. macOS only: `open -a <App> <path>` through the official
+ * `@deepseek-ai/dsh-native-command` runner (no shell, abort propagation),
+ * mirroring `reveal.ts`'s discipline. The browser picks the application by
+ * official open-in-app catalog id (probed from `/open-in-app/apps`); the
+ * id → `.app` name map below mirrors the official catalog's darwin entries
+ * (packages/host/open-in-app/src/catalog.ts at 0.1.5-rc.1 — re-check on every
+ * host upgrade). Other platforms and unknown ids answer unsupported, and the
+ * client hides the gesture.
+ * @module @khorsheed/dsh-file-preview
+ */
+import { runNativeCommand } from '@deepseek-ai/dsh-native-command';
+/** Official catalog id → macOS application name (darwin entries of the official catalog). */
+const MAC_APP_NAMES = {
+    cursor: 'Cursor',
+    vscode: 'Visual Studio Code',
+    vscodeinsiders: 'Visual Studio Code - Insiders',
+    windsurf: 'Windsurf',
+    zed: 'Zed',
+    sublimetext: 'Sublime Text',
+    xcode: 'Xcode',
+    androidstudio: 'Android Studio',
+    intellij: 'IntelliJ IDEA',
+    pycharm: 'PyCharm',
+    webstorm: 'WebStorm',
+    phpstorm: 'PhpStorm',
+    goland: 'GoLand',
+    rider: 'Rider',
+    rustrover: 'RustRover',
+};
+/** The application name one catalog id maps to, or undefined when unknown. */
+export function macAppName(appId) {
+    return MAC_APP_NAMES[appId];
+}
+/**
+ * Open one file in the named application. Throws when the platform is not
+ * macOS or the catalog id is unknown — the caller maps both to an
+ * `unsupported`/`unknown-app` answer and the client hides the gesture. A
+ * launch failure propagates as the runner's rejection.
+ * @param path - absolute path in the host's execution world (caller owns
+ *   resolution, typically `FileSystem.processPath`).
+ * @param appId - official open-in-app catalog id (e.g. `cursor`).
+ * @param signal - caller/connection lifetime; abort terminates the native command.
+ * @param internals - platform seam for deterministic tests.
+ */
+export async function openExternalNative(path, appId, signal, internals = {}) {
+    const platform = internals.platform ?? process.platform;
+    if (platform !== 'darwin') {
+        throw new Error(`open-in-app is unsupported on ${platform}`);
+    }
+    const app = macAppName(appId);
+    if (app === undefined)
+        throw new Error(`unknown application id "${appId}"`);
+    const run = internals.run ?? runNativeCommand;
+    await run('open', ['-a', app, path], signal);
+}

package/lib/types/types.d.ts

@@ -95,6 +95,16 @@ export type FilePreviewReveal = {
     /** Why: `missing` = the recorded path does not resolve to an existing target; `select-failed` = the host could not select the file. */
     readonly reason: 'missing' | 'select-failed';
 };
+/** Outcome of a `filePreview.openExternal` call (the "open in IDE" gesture). */
+export type FilePreviewOpenExternal = {
+    /** The application launched on the file. */
+    readonly opened: true;
+} | {
+    /** The file could not be opened in the named application. */
+    readonly opened: false;
+    /** 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. */
+    readonly reason: 'missing' | 'unknown-app' | 'unsupported-platform' | 'launch-failed';
+};
 /** One file's mutation facts within one turn — the turn card's vocabulary. */
 export interface FilePreviewTurnFile {
     /** The display path (absolute for bash-captured writes; as-recorded otherwise). */
@@ -105,7 +115,7 @@ export interface FilePreviewTurnFile {
     /** Lines added across the turn's mutations of this path. */
     readonly added?: number;
     /** Lines removed; 0 for a create; absent when an uncounted mutation (a write
-     *  whose prior content was not diffable, a Code Mode dispatch) reported no
+     *  whose prior content was not diffable, a PTC dispatch) reported no
      *  total. */
     readonly removed?: number;
 }

package/package.json

@@ -7,7 +7,7 @@
     "cordis",
     "file-preview"
   ],
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
@@ -42,7 +42,6 @@
     "lib/typert.remote-client.d.ts",
     "lib/typert.remote-client.js",
     "cordis.patch.yml",
-    "skills/**/*.md",
     "LICENSE",
     "CHANGELOG.md"
   ],
@@ -59,25 +58,25 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-agent": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-fs": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-invariants": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-loader-smoke": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-native-command": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-session": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-skill": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-tools": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-util-values": "^0.1.2-rc.1"
+    "@deepseek-ai/dsh-agent": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-fs": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-loader-smoke": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-native-command": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-session": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-skill": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-util-values": "^0.1.5-rc.1"
   },
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
     },
     "compat": {
-      "minHost": "0.1.2-rc.1",
-      "verifiedHost": "0.1.2-rc.1"
+      "minHost": "0.1.5-rc.1",
+      "verifiedHost": "0.1.5-rc.1"
     }
   }
 }