@xrn1997/dsh-session-delete 0.5.0 → 0.6.0

package/lib/types/ports/attachments-port.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 宿主 `attachments` 服务的窄镜像（ADR-0035）：只声明本插件读取附件用到的两条。
+ *
+ * - 服务是**可选**的：`ctx.get('attachments')` 每次调用现查（服务可能晚于插件激活），
+ *   `available()` 为假时调用方退回旧的直接 fs 路径。
+ * - `readImage` 会按记录里的引用**校验字节**；`readFileStream` 校验并分块读出。
+ *   两者都不在本文件里重写校验逻辑。
+ * - 不 import 宿主 `attachments` 服务的类型包：形状按该服务的运行期契约抄成窄镜像。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export type ImageMediaTypeLike = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif';
+export interface ImageAttachmentRefLike {
+    readonly attachmentId: string;
+    readonly mediaType: ImageMediaTypeLike;
+    readonly bytes: number;
+    readonly width: number;
+    readonly height: number;
+    readonly name?: string;
+}
+export interface FileAttachmentRefLike {
+    readonly attachmentId: string;
+    readonly name: string;
+    readonly bytes: number;
+}
+export interface StoredImageAttachmentLike {
+    readonly ref: ImageAttachmentRefLike;
+    readonly data: Uint8Array;
+}
+export interface AttachmentsPort {
+    /** 服务在场且成员形状可用；调用方用它决定走服务还是直接 fs。 */
+    available(): boolean;
+    readImage(ref: ImageAttachmentRefLike): Promise<StoredImageAttachmentLike>;
+    readFileStream(ref: FileAttachmentRefLike): AsyncIterable<Uint8Array>;
+}
+/** 服务在 `available()` 之后消失/形状变了：调用方可以退回直接 fs，而不是把这次读取判成 io。 */
+export declare class AttachmentsUnavailableError extends Error {
+    constructor(message?: string);
+}
+/** 每次调用惰性解析服务：插件与 `attachments` 的激活顺序没有承诺。 */
+export declare function createAttachmentsPort(ctx: Context): AttachmentsPort;

package/lib/types/shared/wire.d.ts

@@ -6,13 +6,18 @@
  * 信封 {ok:true,value} / {ok:false,error:{code,message,details?}} 也是两半的共同契约。
  */
 /**
- * 插件专属前缀。
+ * 插件专属前缀（九段相对它命名）。
  *
- * 为什么必须带插件名：宿主 web server 的 `register({kind:'prefix', path})` 对**重复的 (kind, path)
- * 直接抛错**（`dsh-host-webserver` 原文 `webserver: duplicate ${route.kind} route "${route.path}"`），
- * 撞了就是整棵插件树 boot 失败——所以这条路径是与生态的硬边界，不是显示好不好看的问题。
+ * 为什么必须带插件名：宿主 `connection.fetch.register` 对**重复的精确路径**直接抛错
+ * （`connection: exact Fetch route "…" is already registered`），撞了就是整棵插件树 boot 失败——
+ * 所以这条路径是与生态的硬边界，不是显示好不好看的问题。
  */
 export declare const SESSION_DELETE_API_PREFIX = "/dsh-session-delete-api";
+/**
+ * 唯一的取数基础路径：宿主 `/api` + 插件前缀。九段 exact Fetch 路由、客户端探测与附件 URL
+ * 都从它起；`SESSION_DELETE_API_PREFIX` 只作为段名的相对前缀与错误原文。
+ */
+export declare const OFFICIAL_SESSION_DELETE_API_PREFIX = "/api/dsh-session-delete-api";
 /** 九个段名（相对前缀）。**每项 `{ path, method }` 两键**：某段用什么方法也是线上形状的一部分
  *  （ADR-0003），家就在这一张表——路由记录（`src/api/route-table.ts`）逐行投影（`ROUTES.x.method`），
  *  浏览器半的 GET 段同样投影、写段把 `ROUTES.x.method` 交给 `src/client/remote.ts` 的 `post()`，
@@ -251,7 +256,8 @@ export interface AttachmentOrphanItemWire {
     bytes: number;
 }
 /** 孤儿附件报告（`GET /attachment-orphans`）：数量、总字节与对象清单。
- *  清单只带 id/bytes（不含路径/文件名），供设置页预览缩略图，最多 200 条；数量与字节按全量算。
+ *  清单只带 id/bytes（不含路径/文件名），供设置页预览缩略图；条数由 Node 半配置
+ *  （`src/config.ts` 的 `orphanPreviewLimit`，默认 200），数量与字节按全量算。
  *  读不出任何一处引用源时**不返回这一形状**，而是 `io` 失败——不拿 0 冒充"没有孤儿"。 */
 export interface AttachmentOrphanReportWire {
     count: number;
@@ -297,6 +303,13 @@ export declare const PARAMS: {
     readonly attachmentId: "id";
     readonly attachmentKind: "kind";
     readonly attachmentName: "name";
+    /** 图片引用的媒体类型 / 宽高：只给宿主 `attachments.readImage` 做引用校验，不参与路径拼接。 */
+    readonly attachmentMediaType: "mediaType";
+    /** 字节数：图片支与文件支都带——它是宿主读面的引用一部分，并先过 `maxAttachmentBytes` 闸
+     *  （别为一张已知超限的图让宿主整份读出来）。 */
+    readonly attachmentBytes: "bytes";
+    readonly attachmentWidth: "width";
+    readonly attachmentHeight: "height";
 };
 /**
  * 失败信封的**线上形状**（本文件）：`code` 是判别依据、`message` 是上屏原文、

package/lib/types/trash/attachments.d.ts

@@ -1,4 +1,5 @@
 import type { FsPort } from '../ports/fs-port.js';
+import type { SessionDeleteConfig } from '../config.js';
 import { type AttachmentCleanupWire } from '../shared/wire.js';
 export interface ImageRef {
     kind: 'image';
@@ -30,6 +31,7 @@ export declare function attachmentsInContent(content: unknown): AttachmentRef[];
 export interface AttachmentReadDeps {
     fs: Pick<FsPort, 'exists' | 'listFiles' | 'listDirs' | 'readFile' | 'statFile' | 'realpath'>;
     home: string;
+    config: Pick<SessionDeleteConfig, 'maxJsonRefBytes'>;
 }
 export interface AttachmentRemovalDeps extends AttachmentReadDeps {
     fs: Pick<FsPort, 'exists' | 'listFiles' | 'listDirs' | 'readFile' | 'statFile' | 'realpath' | 'removeFile'>;

package/lib/types/verbs/orphan-subagents.d.ts

@@ -27,8 +27,9 @@ interface RawGroup {
  * 彻底删除（组语义见 `src/trash/groups.ts`），把它的根当孤儿删掉就是**替用户做了一个没人点过的决定**。孤儿只
  * 有一种来路：父被彻底删掉了（或被手工从盘上清掉了），清册里再也没有这一行。
  *
- * 根按**传递闭包**收全部后代（与 `HostCorpusPort.subagentMembersOf` 同一实现：闭包核心住
- * `src/domain/closure.ts` 的 `orphanRootsOf`，孩子与孙代都算，深度不设上限），同一条记录只归一组
+ * 根按**传递闭包**收全部 subagent 后代（与 `HostCorpusPort.subagentMembersOf` 同一实现：闭包核心住
+ * `src/domain/closure.ts` 的 `orphanRootsOf`，孩子与孙代都算，深度不设上限；普通 fork 不是成员、
+ * 也不穿过它收后代），同一条记录只归一组
  * （`claimed`）——数据里真出现环时结果是"少数一条"，不是把一个会话删两遍。
  * 归堆与去重**两边都去 `session-` 前缀**：同一个父在两代宿主里写法不同（见 `bareSessionId` 的来历）。
  */

package/locale/en.json

@@ -1,6 +1,6 @@
-{
-  "meta": {
-    "title": "Session Delete",
-    "description": "Delete sessions: delete moves them to a recoverable trash, with an explicit permanent delete."
-  }
-}
+{
+  "meta": {
+    "title": "Session Delete",
+    "description": "Delete sessions: delete moves them to a recoverable trash, with an explicit permanent delete."
+  }
+}

package/locale/zh.json

@@ -1,6 +1,6 @@
-{
-  "meta": {
-    "title": "会话删除",
-    "description": "删除会话：删除 = 移入回收站（可恢复），另设显式的彻底删除。"
-  }
-}
+{
+  "meta": {
+    "title": "会话删除",
+    "description": "删除会话：删除 = 移入回收站（可恢复），另设显式的彻底删除。"
+  }
+}

package/package.json

@@ -1,117 +1,117 @@
-{
-  "name": "@xrn1997/dsh-session-delete",
-  "version": "0.5.0",
-  "description": "在 DeepSeek Harness 里删除会话：删除=移入回收站（可恢复），另设显式彻底删除",
-  "type": "module",
-  "packageManager": "pnpm@11.25.0",
-  "main": "lib/index.js",
-  "types": "lib/types/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./lib/types/index.d.ts",
-      "default": "./lib/index.js"
-    },
-    "./client": {
-      "types": "./lib/types/client/index.d.ts",
-      "default": "./lib/client.js"
-    },
-    "./locale/*.json": "./locale/*.json",
-    "./package.json": "./package.json"
-  },
-  "icon": "./icon.svg",
-  "files": [
-    "lib/index.js",
-    "lib/client.js",
-    "lib/types/**/*.d.ts",
-    "locale",
-    "icon.svg",
-    "cordis.patch.yml",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=24",
-    "dsh": ">=0.1.7-rc.2 <0.3.0-0"
-  },
-  "scripts": {
-    "build": "tsdown && tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint .",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "pack:dry": "npm pack --dry-run --ignore-scripts",
-    "prepack": "npm run build",
-    "gates": "pnpm typecheck && pnpm lint && pnpm test && pnpm build && pnpm run pack:dry"
-  },
-  "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.4",
-    "react": "^18.3.1"
-  },
-  "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.4",
-    "@eslint/js": "^10.0.1",
-    "@testing-library/dom": "^10.4.2",
-    "@testing-library/jest-dom": "^6.10.0",
-    "@testing-library/react": "^16.3.3",
-    "@types/node": "24.19.0",
-    "@types/react": "18.3.31",
-    "@types/react-dom": "18.3.5",
-    "@types/semver": "^7.8.0",
-    "eslint": "^10.14.0",
-    "eslint-plugin-react-hooks": "^7.1.1",
-    "globals": "^17.13.0",
-    "jsdom": "^26.1.0",
-    "react": "^18.3.1",
-    "react-dom": "18.3.1",
-    "semver": "^7.8.5",
-    "tsdown": "0.23.0",
-    "typescript": "5.9.3",
-    "typescript-eslint": "^8.72.1",
-    "vitest": "3.2.7"
-  },
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    },
-    "client": {
-      "inject": [
-        "@deepseek-ai/dsh-client-locale"
-      ],
-      "platform": "web"
-    },
-    "compatibility": {
-      "dshReleases": {
-        "0.2.0-rc.2": "compatible",
-        "0.2.1-rc.1": "compatible",
-        "0.2.1-rc.2": "compatible",
-        "0.2.1-rc.3": "compatible",
-        "0.2.1-rc.5": "compatible"
-      }
-    }
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/xrn1997/dsh-session-delete.git"
-  },
-  "homepage": "https://github.com/xrn1997/dsh-session-delete#readme",
-  "bugs": {
-    "url": "https://github.com/xrn1997/dsh-session-delete/issues"
-  },
-  "keywords": [
-    "dsh",
-    "deepseek-harness",
-    "plugin",
-    "session",
-    "trash",
-    "delete"
-  ],
-  "author": "xrn1997",
-  "license": "Apache-2.0",
-  "dependencies": {
-    "react-markdown": "^10.1.0",
-    "remark-gfm": "^4.0.1"
-  }
-}
+{
+  "name": "@xrn1997/dsh-session-delete",
+  "version": "0.6.0",
+  "description": "在 DeepSeek Harness 里删除会话：删除=移入回收站（可恢复），另设显式彻底删除",
+  "type": "module",
+  "packageManager": "pnpm@11.25.0",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./locale/*.json": "./locale/*.json",
+    "./package.json": "./package.json"
+  },
+  "icon": "./icon.svg",
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "locale",
+    "icon.svg",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=24",
+    "dsh": ">=0.1.7-rc.2 <0.3.0-0"
+  },
+  "scripts": {
+    "build": "tsdown && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "pack:dry": "npm pack --dry-run --ignore-scripts",
+    "prepack": "npm run build",
+    "gates": "pnpm typecheck && pnpm lint && pnpm test && pnpm build && pnpm run pack:dry"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.4",
+    "react": "^18.3.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@eslint/js": "^10.0.1",
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/jest-dom": "^6.10.0",
+    "@testing-library/react": "^16.3.3",
+    "@types/node": "24.19.0",
+    "@types/react": "18.3.31",
+    "@types/react-dom": "18.3.5",
+    "@types/semver": "^7.8.0",
+    "eslint": "^10.14.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "globals": "^17.13.0",
+    "jsdom": "^26.1.0",
+    "react": "^18.3.1",
+    "react-dom": "18.3.1",
+    "semver": "^7.8.5",
+    "tsdown": "0.23.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "^8.72.1",
+    "vitest": "3.2.7"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-locale"
+      ],
+      "platform": "web"
+    },
+    "compatibility": {
+      "dshReleases": {
+        "0.2.0-rc.2": "compatible",
+        "0.2.1-rc.1": "compatible",
+        "0.2.1-rc.2": "compatible",
+        "0.2.1-rc.3": "compatible",
+        "0.2.1-rc.5": "compatible"
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xrn1997/dsh-session-delete.git"
+  },
+  "homepage": "https://github.com/xrn1997/dsh-session-delete#readme",
+  "bugs": {
+    "url": "https://github.com/xrn1997/dsh-session-delete/issues"
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "session",
+    "trash",
+    "delete"
+  ],
+  "author": "xrn1997",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1"
+  }
+}

package/lib/types/api/request-trust.d.ts

@@ -1,45 +0,0 @@
-/**
- * 请求栅栏：判一条打到 `/dsh-session-delete-api` 的请求归不归本插件办。
- *
- * 两件事分开：**归属**（Host / Origin / Referer 是不是本次部署自己的）与**身份**（远程客户端是不是
- * 宿主的已认证 Web 客户端）。绑定策略归宿主 webserver 配置——它只接受具体接口 IP 字面量、拒绝
- * wildcard——所以「谁能到达」不是本插件能替它决定的事；栅栏本身只防 browser confused deputy，
- * 身份留给宿主（见 ②）。口径与宿主 `/api` 的 `isTrustedApiRequest`（asar
- * `dsh-client-connection/lib/index.js`）对齐，差别只有一条：本模块多查 Referer，因为
- * `GET /attachment` 是二进制段（见末段）。
- *
- * 两条放行支，外加一条缺席规则：
- * ① 头栅栏全过 ∧ 源地址回环 ∧ Host 属于本次部署（回环名 / 监听 bind 字面量）——本机工具与转发落在
- *    回环的桌面壳；
- * ② 宿主 `connection` 服务的 `requestRejection` 放行——远程浏览器。它自带宿主的 Host 白名单
- *    （含部署声明的 `trustedHosts`）与「已认证 live peer」，身份就是那次 `dsh web` 打印的 URL 换来的
- *    签名 cookie，不在本插件里复刻；
- * ③ 身份层缺席（`src/ports/connection-port.ts` 报 `absent`，宿主无 `connection` 服务或成员改名）
- *    ⇒ 远程一律拒（fail-closed：退回「只有本机」，LAN 上表现为 403 而不是静默放行）。
- *
- * **DNS rebinding 由 Host 归属判据挡**：`Origin === Host` 只证两者同名，不证这个名字属于本部署；
- * 回环 socket 也不构成豁免（重绑到 `127.0.0.1` 的攻击正是回环源地址）。对浏览器来说 Host 是重绑伪造
- * 不了的那个头——它按连接目标填，而 `Origin` 是页面自己的名字——所以归属判定先于任何本机 / 远程
- * 分支，别在它前面加 fast-path。
- *
- * 末段：`GET /attachment` 的响应不是 opaque 的「读不出内容」——页面若已知某个 `sha256:…` 内容哈希，
- * 就能把它当 `<img src>` 跨源渲染出来。那条请求不带 Origin，靠 Referer 判同源挡；宿主 `/api` 没有
- * 二进制段，所以它的栅栏不需要这一条。
- */
-import type { IncomingMessage } from 'node:http';
-import type { ConnectionPort } from '../ports/connection-port.js';
-export type RequestTrustVerdict = 'allowed' | 'untrusted' | 'unauthenticated';
-export interface RequestTrustFacts {
-    /** 监听器绑定的那个具体接口 IP 字面量；老代次没有这个 getter 时为 `undefined`（bind 支退化，仍 fail-closed）。 */
-    readonly bindHost: string | undefined;
-    /** 宿主的 Web 身份面；端口每次请求惰性解析服务，缺席由它报 `absent`。 */
-    readonly connection: ConnectionPort;
-}
-/**
- * 这条请求归不归本插件办。`untrusted` = 归属不对（跨源 / 重绑 / 头不成形）；`unauthenticated` =
- * 归属对但远程客户端没带宿主身份（原文会提示用 `dsh web` 打印的 URL 打开）。
- *
- * 远程支的两个失败裁决由端口翻译宿主的区分（401 = 缺身份、403 = 归属不对）。身份层缺席（端口报
- * `absent`）一律按归属不对处理：那时没有可换的身份，不能让原文提示用户去补一个不存在的东西。
- */
-export declare function judgeRequest(req: IncomingMessage, facts: RequestTrustFacts): RequestTrustVerdict;

package/lib/types/ports/connection-port.d.ts

@@ -1,33 +0,0 @@
-/**
- * 宿主 `connection` 服务（`dsh-client-connection` 的 `HostConnectionService`，`super(ctx, "connection")`）
- * 的窄镜像：`requestRejection(request)` 一次做宿主 `/api` 的那两道——Host/Origin 栅栏与「已认证 live peer」。
- *
- * **每次请求惰性解析服务**，不在激活时取一次：插件与 `client-connection` 的激活顺序没有承诺，取早了
- * 会让远程支永远缺席（LAN 上全 403 且难排查）。`ctx.get` 是同步查表，代价可以忽略。
- *
- * **状态码在这里翻成裁决**（401 = 归属对、缺身份；403 = 归属不对；其余按归属不对处理），
- * 调用方拿到的就是自己的词表，不需要知道宿主用哪个码表达哪件事。成员名与返回值按 asar
- * `dsh-client-connection/lib/index.js` 原文读实。
- */
-import type { IncomingMessage } from 'node:http';
-import type { Context } from '@deepseek-ai/cordis';
-export type ConnectionVerdict = {
-    readonly kind: 'allowed';
-}
-/** 组成里没有这个服务（无 web 组成 / 老代次）——调用方 fail-closed。 */
- | {
-    readonly kind: 'absent';
-}
-/** 宿主认可归属，但这条请求没带已认证身份。 */
- | {
-    readonly kind: 'unauthenticated';
-}
-/** 宿主不认可归属（Host/Origin 栅栏不过，或它给出的其余状态码）。 */
- | {
-    readonly kind: 'untrusted';
-};
-export interface ConnectionPort {
-    verdictFor(req: IncomingMessage): ConnectionVerdict;
-}
-/** 成员抛错按「归属不对」拒绝（fail-closed）。 */
-export declare function createConnectionPort(ctx: Context): ConnectionPort;