@khorsheed/dsh-file-preview 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # 变更记录
 
+## 未发布
+
+- 从只读宿主包移除 `3d-artifact` 作者 skill；现在由 `@khorsheed/dsh-inline-html-render` 分发并注册。
+- 新增零会话 `capabilities()` Remote 握手（`protocolVersion: 1`），供客户端在宿主缺席时抑制全部 UI。
+
+## 未发布
+
+- 从只读宿主包移除 `3d-artifact` 作者 skill；现在由 `@khorsheed/dsh-inline-html-render` 分发并注册。
+- 新增零会话 `capabilities()` Remote 握手（`protocolVersion: 1`），供客户端在宿主缺席时抑制全部 UI。
+
+## 0.3.0（2026-09-11）
+
+（以 minor 发布：openExternal 是新增能力；pair 包 ui-file-preview 的 peer 边由 pack-dist 按本包版本重写，两包版本线须一致。）
+
+- **BREAKING**：minHost 前移至 `0.1.5-rc.1`；宿主 `0.1.2-rc.1` 的用户请停留在 `0.2.0`。dispatch 事件只匹配 0.1.5 的 `tool/ptc-dispatch`（官方 v2→v3 日志迁移会把持久化的旧名改写过来，0.1.5 宿主不会再发出 `tool/code-dispatch`），0.2.0 的双名探测退役
+- 新增 Remote 方法 `openExternal(agent, path, app, signal)`：在指定宿主应用中打开文件（macOS `open -a`），供浏览器半的「在 IDE 打开」手势使用——官方 open-in-app 路由只收目录。`app` 为官方 catalog id（id → `.app` 名映射镜像官方 catalog 的 darwin 条目）；非 macOS / 未知 id 返回 `opened: false`，不写入。
+
+
 ## 0.2.0（2026-09-10）
 
 适配宿主 0.1.2 线。

package/README.en.md

@@ -32,7 +32,7 @@ Host half only — the visible surface (Produced tab, preview drawer, per-turn c
 dsh plugin --profile web add @khorsheed/dsh-client-ui-file-preview
 ```
 
-Uninstall; a leftover client half degrades to an empty state rather than an error:
+Uninstall; if the client half is left behind, its zero-session handshake fails and every UI surface is absent (no error card or empty tab remains):
 
 ```sh
 dsh plugin --profile web remove @khorsheed/dsh-file-preview
@@ -53,10 +53,10 @@ dsh plugin --profile web remove @khorsheed/dsh-file-preview
 
 ## Compatibility
 
-- npm release line (`@deepseek-ai/dsh@0.1.2-rc.1`): ✅ full — baseline moved to the 0.1.2-rc.1 API surface (single-arm 0.1.2 API consumption; the 0.1.1-rc.2 runtime arm is retired), full build+test green; minHost moves up to 0.1.2-rc.1 — older hosts stay on the previous release line.
-- source line (deepseek-harness master): ✅ (verifiedHost: 0.1.2-rc.1)
+- npm release line (`@deepseek-ai/dsh@0.1.5-rc.1`): ✅ full — adapted to the 0.1.5-rc.1 PTC rename (only `tool/ptc-dispatch` is matched; the official v2→v3 log migration renames persisted rows), full build+test green; minHost moves up to 0.1.5-rc.1 — older hosts stay on the previous release line.
+- source line (deepseek-harness master): ✅ (verifiedHost: 0.1.5-rc.1)
 
-**Version line mapping**: 0.2.0 and up support host `0.1.2-rc.1` and later; hosts on `0.1.0-rc.6` ~ `0.1.1-rc.2` stay on the 0.1.x release line (last release `0.1.1`).
+**Version line mapping**: the first release after 0.2.0 supports host `0.1.5-rc.1` and later; hosts on `0.1.2-rc.1` stay on `0.2.0`, hosts on `0.1.0-rc.6` ~ `0.1.1-rc.2` stay on the 0.1.x release line (last release `0.1.1`).
 
 ## Known Limitations
 
@@ -68,11 +68,14 @@ dsh plugin --profile web remove @khorsheed/dsh-file-preview
 <details>
 <summary>Internals (click to expand)</summary>
 
-`ctx.filePreview` (wire namespace `filePreview`) exposes four generated Remote methods:
+`ctx.filePreview` (wire namespace `filePreview`) exposes six generated Remote methods:
 
-- `list(agent)` — a pure fold over `agent.session.events`: `read`/`write`/`edit` `tool/call`s contribute display paths, as do settled nested Code Mode `tool/code-dispatch`es for those tools (failed dispatches record nothing; entries borrow the root call's turn/step). A `write`/`edit` `tool/result` carrying `diffs` meta appends each change to the entry in event order, `lastDiff` kept as the final one. The response carries the entries, the last scanned seq, and whether `maxFiles` was hit. No filesystem access in the fold; with `captureBashWrites` on, entries merge with the collector's verified bash-written paths. Before returning, each path is resolved against the session cwd and `stat`-ed, keeping only those that still exist as a regular file — the log fold is history, the product list reflects disk state (a temp script a turn wrote then cleaned up is no longer a product); existence is probed fresh per call (not cached with the log fold).
+- `capabilities()` — a zero-session availability handshake returning `{ protocolVersion: 1 }`; the companion client installs UI surfaces only after it succeeds.
+
+- `list(agent)` — a pure fold over `agent.session.events`: `read`/`write`/`edit` `tool/call`s contribute display paths, as do settled nested PTC `tool/ptc-dispatch`es for those tools (failed dispatches record nothing; entries borrow the root call's turn/step). A `write`/`edit` `tool/result` carrying `diffs` meta appends each change to the entry in event order, `lastDiff` kept as the final one. The response carries the entries, the last scanned seq, and whether `maxFiles` was hit. No filesystem access in the fold; with `captureBashWrites` on, entries merge with the collector's verified bash-written paths. Before returning, each path is resolved against the session cwd and `stat`-ed, keeping only those that still exist as a regular file — the log fold is history, the product list reflects disk state (a temp script a turn wrote then cleaned up is no longer a product); existence is probed fresh per call (not cached with the log fold).
 - `read(agent, path, signal)` — resolves `path` against the session cwd and serves `kind: 'text'` (capped at `maxReadBytes`, flagged `truncated`), or `kind: 'image'` with a browser-loadable URL on web hosts — bytes ride a dedicated `/file-preview-image/<sessionId>/<path>` route, registered only when the optional `webServer` and `agents` services are composed; headless hosts answer `binary` — or a classified notice: `binary` (binary extension or NUL bytes; never read), `missing`, `too-large`, or `error` (message included).
 - `reveal(agent, path, signal)` — opens the file's folder with the file selected, shell-free through `@deepseek-ai/dsh-native-command`: macOS `open -R`, Windows `explorer /select,<path>`, WSL via `wslpath`, desktop Linux tries `nautilus`/`dolphin`/`nemo --select` in order. Answers `{ revealed: true }`, or `false` with `reason: 'missing'` (no such target) or `'select-failed'` (no capable file manager — the caller then opens the parent folder, so the gesture always lands somewhere visible). Writes nothing.
+- `openExternal(agent, path, app, signal)` — open a file in a specific host application (the "open in IDE" gesture): the official open-in-app route accepts directories only, so file-exact opens go here — macOS `open -a <App> <path>`, shell-free as well. `app` is an official open-in-app catalog id (the client probes `/open-in-app/apps`); the id → `.app` name map lives in `open-external.ts` (mirroring the official catalog's darwin entries). Non-macOS hosts and unknown ids answer `{ opened: false, reason }`, and the client hides the gesture. Writes nothing.
 - `turnFiles(agent)` — every turn's file mutations for the turn-tail card, the same single source of truth as `list` but NOT deduped: a file touched in two turns appears in both groups, so each card lists exactly what that turn mutated. Line deltas are summed from result diffs; the fold is cached per session and invalidated by the log watermark, which the response carries for the client's own cache. Like `list`, it probes existence against the session cwd before returning and keeps only files that still exist (a cleaned-up temp script does not occupy a card).
 
 Bash-write collector: watches each session's bash `tool/call`/`tool/result` pairs, extracts high-precision write targets (`cat > path` heredocs, single `>` redirects, `tee` non-append, `sed -i`), expands `$VAR`/`~`/relative paths against the host environment and session cwd, and records only paths `fs.stat` confirms as files (a miss beats a false positive). Captures live in a per-session in-memory registry rebuilt by replaying the session's own history on `session/created`, so a restarted host regains them; the session log itself is never mutated (the official `Session.append` cannot mark a plugin event `ignorable` — see the S2 seam in `docs/upstream-seam-registry.md`). Bash-captured files carry no diff history; previews read current content through `read`.

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # last confirmed-consistent state. Both languages carry equal authority; after
 # editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/file-preview/README.en.md
-packages/file-preview/README.en.md: ef4c3a913fe23a474cb4d05114fb9f080ff641d1
-packages/file-preview/README.md: a34ba31610e054fd3f82c9b2d5c3635e04a970ed
+packages/file-preview/README.en.md: e454c9f4feefaa3bd879b7e2d277c393f46fb790
+packages/file-preview/README.md: 824c988049eea742c9e0f38078161829b14660ea

package/README.md

@@ -32,7 +32,7 @@ dsh plugin --profile web add @khorsheed/dsh-file-preview
 dsh plugin --profile web add @khorsheed/dsh-client-ui-file-preview
 ```
 
-卸载；残留的客户端半降级为空态而非报错：
+卸载；如果只残留客户端半，它的零会话握手会失败，全部 UI 面均缺席（不留错误卡或空 tab）：
 
 ```sh
 dsh plugin --profile web remove @khorsheed/dsh-file-preview
@@ -53,10 +53,10 @@ dsh plugin --profile web remove @khorsheed/dsh-file-preview
 
 ## Compatibility
 
-- npm 发布线（`@deepseek-ai/dsh@0.1.2-rc.1`）：✅ 完整——基线迁移至 0.1.2-rc.1 API 面（单臂消费 0.1.2 API，0.1.1-rc.2 运行臂已退役），全量构建测试通过；minHost 前移至 0.1.2-rc.1，旧宿主请停留在旧发布线。
-- 源码线（deepseek-harness master）：✅（verifiedHost: 0.1.2-rc.1）
+- npm 发布线（`@deepseek-ai/dsh@0.1.5-rc.1`）：✅ 完整——适配 0.1.5-rc.1 的 PTC 更名（只匹配 `tool/ptc-dispatch`；旧日志由官方 v2→v3 迁移改写到新名），全量构建测试通过；minHost 前移至 0.1.5-rc.1，旧宿主请停留在旧发布线。
+- 源码线（deepseek-harness master）：✅（verifiedHost: 0.1.5-rc.1）
 
-**版本线对照**：0.2.0 起支持宿主 `0.1.2-rc.1` 及以后；宿主 `0.1.0-rc.6` ~ `0.1.1-rc.2` 的用户请停留在 0.1.x 发布线（末版 `0.1.1`）。
+**版本线对照**：0.2.0 之后的首个发布起支持宿主 `0.1.5-rc.1` 及以后；宿主 `0.1.2-rc.1` 请停留在 `0.2.0`，宿主 `0.1.0-rc.6` ~ `0.1.1-rc.2` 请停留在 0.1.x 发布线（末版 `0.1.1`）。
 
 ## Known Limitations
 
@@ -68,11 +68,14 @@ dsh plugin --profile web remove @khorsheed/dsh-file-preview
 <details>
 <summary>内部结构（点击展开）</summary>
 
-`ctx.filePreview`（wire 命名空间 `filePreview`）暴露四个生成的 Remote 方法：
+`ctx.filePreview`（wire 命名空间 `filePreview`）暴露六个生成的 Remote 方法：
 
-- `list(agent)`——对 `agent.session.events` 的纯折叠：`read`/`write`/`edit` 的 `tool/call` 贡献展示路径，这些工具的已完结嵌套 Code Mode `tool/code-dispatch` 同样计入（失败的派发不记录；条目借用根调用的 turn/step）。携带 `diffs` 元数据的 `write`/`edit` `tool/result` 把每次改动按事件序追加进条目，`lastDiff` 保留为最后一次。响应携带条目、最后扫描的 seq，以及是否触达 `maxFiles`。折叠本身不访问文件系统；`captureBashWrites` 开启时并入采集器验证过的 bash 写入路径。返回前按会话 cwd 解析每条路径并 `stat`，只保留当前仍存在的常规文件——日志折叠是历史，产物列表只看磁盘现状（某回合写后又清理的临时脚本不再是产物）；存在性每次调用都现查（不随日志折叠缓存）。
+- `capabilities()`——零会话可用性握手，返回 `{ protocolVersion: 1 }`；配套客户端只在握手成功后安装 UI 面。
+
+- `list(agent)`——对 `agent.session.events` 的纯折叠：`read`/`write`/`edit` 的 `tool/call` 贡献展示路径，这些工具的已完结嵌套 PTC `tool/ptc-dispatch` 同样计入（失败的派发不记录；条目借用根调用的 turn/step）。携带 `diffs` 元数据的 `write`/`edit` `tool/result` 把每次改动按事件序追加进条目，`lastDiff` 保留为最后一次。响应携带条目、最后扫描的 seq，以及是否触达 `maxFiles`。折叠本身不访问文件系统；`captureBashWrites` 开启时并入采集器验证过的 bash 写入路径。返回前按会话 cwd 解析每条路径并 `stat`，只保留当前仍存在的常规文件——日志折叠是历史，产物列表只看磁盘现状（某回合写后又清理的临时脚本不再是产物）；存在性每次调用都现查（不随日志折叠缓存）。
 - `read(agent, path, signal)`——以会话 cwd 为基准解析 `path`，返回 `kind: 'text'`（超过 `maxReadBytes` 截断并标记 `truncated`）；web 宿主上图片返回 `kind: 'image'` 及浏览器可加载 URL——字节走专门的 `/file-preview-image/<sessionId>/<path>` 路由，仅当组合了可选的 `webServer` 与 `agents` 服务时注册；无 web 宿主返回 `binary`——否则返回分类提示：`binary`（二进制扩展名或 NUL 字节；绝不读取）、`missing`、`too-large`、`error`（含消息）。
 - `reveal(agent, path, signal)`——在宿主文件管理器中打开文件所在文件夹并选中它，全程无 shell，走 `@deepseek-ai/dsh-native-command`：macOS `open -R`、Windows `explorer /select,<path>`、WSL 经 `wslpath`、桌面 Linux 依次尝试 `nautilus`/`dolphin`/`nemo --select`。选中返回 `{ revealed: true }`，否则 `false` 及 `reason: 'missing'`（目标不存在）或 `'select-failed'`（无可用文件管理器——调用方改开父文件夹，手势总能落在可见处）。不写入任何东西。
+- `openExternal(agent, path, app, signal)`——在指定宿主应用中打开文件（「在 IDE 打开」手势）：官方 open-in-app 路由只收目录，文件级打开走这里——macOS `open -a <App> <path>`，同样无 shell。`app` 是官方 open-in-app catalog id（客户端经 `/open-in-app/apps` 探测）；id → `.app` 名映射在 `open-external.ts`（镜像官方 catalog 的 darwin 条目）。非 macOS 或未知 id 返回 `{ opened: false, reason }`，客户端据此隐藏手势。不写入任何东西。
 - `turnFiles(agent)`——每个回合的文件变更，回合卡片与 `list` 同源但**不**去重：同一文件在两个回合改过，两个分组都有它——每张卡片精确列出该回合改了什么。行数增减由 result diff 求和；折叠按会话缓存、由日志水位线失效，响应携带水位线供客户端自缓存。与 `list` 一样，返回前按会话 cwd 校验存在性，只保留当前仍存在的文件（被清理的临时脚本不占卡片）。
 
 bash 写入采集器：监听每个会话的 bash `tool/call`/`tool/result` 配对，提取高精度写入目标（`cat > path` heredoc、单 `>` 重定向、`tee` 非追加、`sed -i`），按宿主环境与会话 cwd 展开 `$VAR`/`~`/相对路径，只记录 `fs.stat` 确认为文件的路径（宁缺毋滥）。采集结果存于按会话的内存登记表，`session/created` 时重放会话自身历史重建——宿主重启后不丢；会话日志本身绝不被改动（官方 `Session.append` 无法给插件事件标 `ignorable`——见 `docs/upstream-seam-registry.md` 的 S2 条目）。bash 采集的文件没有 diff 历史；预览与普通条目一样通过 `read` 读当前内容。

package/lib/index.js

@@ -1,9 +1,7 @@
-import { readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
 import { Remote, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import z from "@deepseek-ai/schemastery";
 import { homedir, release } from "node:os";
+import { resolve } from "node:path";
 import { runNativeCommand } from "@deepseek-ai/dsh-native-command";
 //#region lib/types/bash-writes.js
 /**
@@ -330,14 +328,6 @@ const FILE_TOOL_NAMES = /* @__PURE__ */ new Set([
 	"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 = /* @__PURE__ */ 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";
 /**
@@ -389,10 +379,11 @@ 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.
@@ -400,7 +391,7 @@ function diffsFromResultMeta(meta) {
 */
 function foldFilePreview(events, maxFiles) {
 	const entries = /* @__PURE__ */ 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 = /* @__PURE__ */ new Map();
 	let asOfSeq = -1;
 	/** Upsert one touched path, refreshing a repeat in place and keeping its diffs. */
@@ -433,16 +424,15 @@ function foldFilePreview(events, maxFiles) {
 			record(target, event.seq, event.data.turn, event.data.step);
 			continue;
 		}
-		if (DISPATCH_EVENT_NAMES.has(event.type)) {
-			const dispatch = event;
-			if (dispatch.data.isError) continue;
-			const target = targetFromArguments(dispatch.data.name, dispatch.data.arguments);
+		if (event.type === "tool/ptc-dispatch") {
+			if (event.data.isError) continue;
+			const target = targetFromArguments(event.data.name, event.data.arguments);
 			if (target === void 0) continue;
-			const site = callSites.get(String(dispatch.data.rootCallId)) ?? {
+			const site = callSites.get(String(event.data.rootCallId)) ?? {
 				turn: 0,
 				step: 0
 			};
-			record(target, dispatch.seq, site.turn, site.step);
+			record(target, event.seq, site.turn, site.step);
 			continue;
 		}
 		if (event.type === "tool/result") {
@@ -520,7 +510,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
@@ -531,7 +521,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.
@@ -539,7 +529,7 @@ function resultCallFacts(message) {
 */
 function foldFilePreviewByTurn(events) {
 	const byTurn = /* @__PURE__ */ 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 = /* @__PURE__ */ new Map();
 	/** Write-tool calls keyed by callId (create fallback; see {@link WriteCallFacts}). */
 	const writeCalls = /* @__PURE__ */ new Map();
@@ -577,7 +567,7 @@ 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);
@@ -636,18 +626,17 @@ function foldFilePreviewByTurn(events) {
 			recordLocation(target.path, event.data.turn, event.seq, event.data.step);
 			continue;
 		}
-		if (DISPATCH_EVENT_NAMES.has(event.type)) {
-			const dispatch = event;
-			if (dispatch.data.isError) continue;
-			const target = targetFromArguments(dispatch.data.name, dispatch.data.arguments);
+		if (event.type === "tool/ptc-dispatch") {
+			if (event.data.isError) continue;
+			const target = targetFromArguments(event.data.name, event.data.arguments);
 			if (target === void 0) continue;
 			if (target.op === "read") continue;
-			const site = callSites.get(String(dispatch.data.rootCallId)) ?? {
+			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, void 0, void 0, true);
+			recordContribution(target.path, site.turn, event.seq, site.step, void 0, void 0, true);
 			continue;
 		}
 		if (event.type === "tool/result") {
@@ -668,6 +657,68 @@ function foldFilePreviewByTurn(events) {
 	return byTurn;
 }
 //#endregion
+//#region lib/types/open-external.js
+/**
+* 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
+*/
+/** 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. */
+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.
+*/
+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 === void 0) throw new Error(`unknown application id "${appId}"`);
+	await (internals.run ?? runNativeCommand)("open", [
+		"-a",
+		app,
+		path
+	], signal);
+}
+//#endregion
 //#region lib/types/reveal.js
 /**
 * Cross-platform native "show in folder, selecting the file" dispatch used by
@@ -785,47 +836,6 @@ var __esDecorate = function(ctor, descriptorIn, decorators, contextIn, initializ
 	if (target) Object.defineProperty(target, contextIn.name, descriptor);
 	done = true;
 };
-/**
-* 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 === void 0) {
-		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 === void 0 || description === void 0 || content === void 0) {
-			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"
-		}));
-	} 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 = /* @__PURE__ */ new Set([
 	".pdf",
@@ -926,17 +936,32 @@ 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",
@@ -981,6 +1006,17 @@ let FilePreviewService = (() => {
 				},
 				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,
@@ -1005,6 +1041,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. */
@@ -1025,6 +1063,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,
@@ -1045,7 +1084,10 @@ let FilePreviewService = (() => {
 					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;
@@ -1184,7 +1226,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
@@ -1386,6 +1428,63 @@ let FilePreviewService = (() => {
 				};
 			}
 		}
+		/**
+		* 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) === void 0) return {
+				opened: false,
+				reason: "unknown-app"
+			};
+			const cwd = agent.session.header.cwd;
+			let target;
+			try {
+				target = await this.fs.resolve(path, cwd === void 0 ? { signal } : {
+					cwd,
+					signal
+				});
+			} catch {
+				return {
+					opened: false,
+					reason: "missing"
+				};
+			}
+			let info;
+			try {
+				info = await this.fs.stat(target, signal);
+			} catch {
+				info = void 0;
+			}
+			if (info === void 0) return {
+				opened: false,
+				reason: "missing"
+			};
+			try {
+				await this.openExternalNative(this.fs.processPath(target), app, signal);
+				return { opened: true };
+			} catch (error) {
+				return {
+					opened: false,
+					reason: (error instanceof Error ? error.message : String(error)).startsWith("open-in-app is unsupported on ") ? "unsupported-platform" : "launch-failed"
+				};
+			}
+		}
 	};
 })();
 //#endregion