@klarkxy/dsh-plugin-kit 0.1.0 → 0.3.0

package/README.md

@@ -1,5 +1,8 @@
 # @klarkxy/dsh-plugin-kit
 
+<!-- release-state-note -->
+The [repository registry](../../README.md#plugin-lifecycle) tracks Draft → Testing → Published, moving forward only. Fixes, testing and version updates keep published packages Published; each update still passes release checks. First publication explicitly selects Testing packages and records Published only after npm archive verification. See the [release guide](../../RELEASING.md).
+
 The shared support package for the feature plugins in this repository: shared record types, the plugin-page model menu, host RPC registration, the official-UI style contract, and one native `llm` text call. It is a library, not a DSH bundle — adding it as a dependency gives a feature plugin the pieces it needs, not a new user-visible feature of its own.
 
 [简体中文](docs/README.zh-CN.md)
@@ -15,10 +18,16 @@ The shared support package for the feature plugins in this repository: shared re
 - `.` — the shared contract types, plus `registerHostRpc`, `callLlmText` and `resolveFeatureModel`.
 - `./contracts` — browser-safe types and constants: shared memory/knowledge records, `TaskContract` / `TaskCheckpoint`, `ModelRoute`, `RpcResult`, `CHAT_EVENTS_SLOT`, `projectIdFromCwd`.
 - `./host-rpc` — host RPC registration helper and its context type.
+- `./model-settings` — host-only model settings contributions. Register the owning plugin's read snapshot and CAS writer with `registerModelSettings` inside `ctx.effect`; the hub discovers active owners using `collectModelSettings`. Each registration has an incarnation ID, so a stale page cannot write into a replacement instance. Reads expose only model fields and revision, with an optional independent model catalog; storage and validation stay with the owner.
 - `./client-utils` — browser-safe helpers for native plugin-page seats: `selectedSessionId`, `useNativeSeat`, `useFeatureRefresh`. `react` is an optional peer.
+- `./model-settings-client` — browser-safe optional invalidation subscription using `createModelSettingsSubscriber`. Model Hub mounts the native stream descriptor once; pages own their rereads and draft conflicts. Owners call host-side `notifyModelSettingsChanged` after persistence and memory state commit.
 - `./model-menu` — plugin-page model select: catalog parsing, empty-route handling, reasoning-effort options.
 - `./llm-call` — `callLlmText` and `resolveFeatureModel` as separate exports.
 - `./official-ui` — the shared browser-side style contract: `officialUiCss(roots)`, the `--dsw-*` token allowlist, and the focus/elevation helpers.
+- `./cli-process` — run a resolved executable without a command shell, with bounded output, serialized line callbacks, deadlines and owned-process-tree cancellation. Streaming mode delivers stdout through `onLine`; it does not also retain stdout.
+- `./cli-media` — validate and stage explicit workspace/current-session media, enforce file limits, and publish native image/file attachments. Remote job authority and vendor protocols remain in each plugin; these helpers do not sandbox a vendor CLI's own file access.
+
+Plugins passing their Cordis context to `resolveFeatureModel` must declare `agents`, `sessionProjections` and `agentDefaultModel` in `inject`. These services supply the live session selection and the host default when the plugin has no saved model.
 
 ## Plugin UI convention
 
@@ -46,12 +55,25 @@ restyling controls of its own. Concretely:
 `OFFICIAL_THEME_TOKEN_NAMES` is that allowlist. Adding a token to it is a
 deliberate act: confirm the name against the host theme first.
 
-## Deprecated types
+## Session ancestry
+
+`isSubagentSession` uses durable session headers, never the author of a user message.
+Explicit subagent origin or positive delegation depth wins. A seeded human fork with
+zero or omitted depth and ordinary/free classification keeps its parent as history
+lineage; incomplete legacy parent metadata still identifies a child session.
 
-`AiPolicy`, `PurposeSpec`, `ModelTarget`, `AiServices`, `AiFeatureScope`, `AuxiliaryRequest`, `AuxiliaryResult` and `UsageReceipt` are retained under `./contracts` marked `@deprecated`. They described the retired shared model-routing service; features must not use them for new calls.
+## Shared string contracts
+
+`./contracts` is the single source for cross-plugin literals:
+
+- `MODEL_SETTINGS_CHANGES_REMOTE` — the model-settings change stream provided by `@klarkxy/dsh-model-hub`. Subscribers degrade silently when that package is not installed.
+- `WEB_PROVIDER_AVAILABILITY_EVENT` and `DshWebManagementDescriptor` — native web providers announce a local availability change and optional display metadata.
+- `CREATOR_PRESET_ID` — the host Creator agent-preset id.
 
 ## Development
 
+Model settings contributions accept `ModelSettingsText` (`string | { zh: string; en: string }`) for provider titles, field labels/descriptions, follow labels and catalog errors. Built-in display copy should include both languages; user data and third-party literal strings stay unchanged. Model Hub resolves the text at render time when the host locale changes.
+
 ```sh
 pnpm --filter @klarkxy/dsh-plugin-kit typecheck
 pnpm --filter @klarkxy/dsh-plugin-kit test

package/docs/README.zh-CN.md

@@ -1,5 +1,8 @@
 # @klarkxy/dsh-plugin-kit
 
+<!-- release-state-note -->
+插件生命周期见[仓库状态清单](../../../README.zh-CN.md#插件生命周期)：草稿 → 测试中 → 已发布，只向前推进。已发布插件的修复、测试和升版保持已发布；每次更新仍须通过发布检查。首次发布须明确选择测试中的包，并在 npm 归档验证成功后登记。详见[发布规则](../../../RELEASING.zh-CN.md)。
+
 本仓库功能插件共用的支撑包：共享记录类型、插件页模型菜单、宿主 RPC 注册、官方 UI 样式契约，以及一次原生 `llm` 文本调用。它是一个库，不是 DSH bundle——把它作为依赖装上，得到的是功能插件需要的零件，而不是一个新的用户可见功能。
 
 [English](../README.md)
@@ -15,10 +18,16 @@
 - `.` — 共享契约类型，以及 `registerHostRpc`、`callLlmText`、`resolveFeatureModel`。
 - `./contracts` — 浏览器安全的类型与常量：共享记忆/知识记录、`TaskContract` / `TaskCheckpoint`、`ModelRoute`、`RpcResult`、`CHAT_EVENTS_SLOT`、`projectIdFromCwd`。
 - `./host-rpc` — 宿主 RPC 注册辅助及其上下文类型。
+- `./model-settings` — 仅供宿主使用的模型设置贡献入口。在 `ctx.effect` 中用 `registerModelSettings` 登记所属插件的模型快照和 CAS 保存接口，枢纽通过 `collectModelSettings` 发现活动入口。每次注册有独立实例标识，旧页面不能写入重新加载的实例。只公开模型字段、版本以及可选的独立模型目录；存储与校验仍归所属插件维护。
 - `./client-utils` — 浏览器安全的原生插件页座位辅助：`selectedSessionId`、`useNativeSeat`、`useFeatureRefresh`。`react` 是可选对等依赖。
+- `./model-settings-client` — 浏览器安全的可选模型设置订阅。`createModelSettingsSubscriber` 复用原生远程流，模型枢纽统一注册描述符；消费页处理刷新和草稿冲突。所属插件在持久化和内存更新完成后用宿主入口的 `notifyModelSettingsChanged` 发出失效提示。
 - `./model-menu` — 插件页模型菜单：目录解析、空路由处理、思考强度选项。
 - `./llm-call` — 单独导出 `callLlmText` 与 `resolveFeatureModel`。
 - `./official-ui` — 浏览器端共享样式契约：`officialUiCss(roots)`、`--dsw-*` token 白名单，以及焦点环与层级辅助。
+- `./cli-process` — 不经命令 shell 运行已解析的可执行文件，提供输出上限、串行逐行回调、超时及本次进程树的取消。流式模式通过 `onLine` 交付 stdout，不再重复保留 stdout 字符串。
+- `./cli-media` — 校验并暂存明确指定的工作区／当前会话媒体，限制文件大小，返回原生图片和文件附件。远端任务授权与厂商协议由各插件负责；这些辅助不为厂商 CLI 自身的文件访问提供沙箱。
+
+将 Cordis 上下文传给 `resolveFeatureModel` 的插件须在 `inject` 中声明 `agents`、`sessionProjections` 和 `agentDefaultModel`。插件未保存模型时，这三个服务提供当前会话选择和宿主默认模型。
 
 ## 插件 UI 约定
 
@@ -30,12 +39,22 @@
 
 `OFFICIAL_THEME_TOKEN_NAMES` 就是这份白名单。往里加 token 是一个需要确认的动作：先对照宿主主题核实名字。
 
-## 已停用的类型
+## 会话关系
+
+`isSubagentSession` 只读取持久会话头，不根据 user 消息判断真人。明确的子代理来源或正派发深度优先；派发深度为零或由原生宿主省略、明确带 seed 的普通/自由真人分叉保留 parent 作为历史继承关系，仅有 parent 的旧会话及未知元数据仍按子线程处理。
 
-`AiPolicy`、`PurposeSpec`、`ModelTarget`、`AiServices`、`AiFeatureScope`、`AuxiliaryRequest`、`AuxiliaryResult`、`UsageReceipt` 仍保留在 `./contracts` 并标注 `@deprecated`。它们描述已停用的共享模型路由服务，新调用不得使用。
+## 跨插件字符串契约
+
+`./contracts` 是插件间字面量的单一来源：
+
+- `MODEL_SETTINGS_CHANGES_REMOTE`：由 `@klarkxy/dsh-model-hub` 提供的模型设置变更流。未安装该包时，订阅方静默降级。
+- `WEB_PROVIDER_AVAILABILITY_EVENT` 与 `DshWebManagementDescriptor`：原生网页供应商宣布本地可用性变化，以及可选的展示元数据。
+- `CREATOR_PRESET_ID`：宿主 Creator 预设 id。
 
 ## 开发
 
+模型设置贡献的提供方标题、字段名称与说明、跟随模式名称及目录错误支持 `ModelSettingsText`（`string | { zh: string; en: string }`）。内置展示文案提供中英文，用户数据和第三方字符串保留原文；模型设置页在渲染时跟随宿主语言解析。
+
 ```sh
 pnpm --filter @klarkxy/dsh-plugin-kit typecheck
 pnpm --filter @klarkxy/dsh-plugin-kit test

package/lib/cli-media.d.ts

@@ -0,0 +1,70 @@
+import { AttachmentStore, FileAttachmentRef, ImageAttachmentRef } from "@deepseek-ai/dsh-attachment";
+//#region src/cli-media.d.ts
+type MediaKind = 'image' | 'audio' | 'video';
+type MediaInput = {
+  path?: string;
+  attachmentId?: string;
+  kind: MediaKind;
+};
+type MediaExec = {
+  signal: AbortSignal;
+  agent?: {
+    session: {
+      id: unknown;
+    };
+  };
+};
+type MediaHost = {
+  sandboxPolicy: {
+    resolve(input: {
+      session?: unknown;
+    }): {
+      workspaceRoot: string;
+      mode: string;
+    };
+  };
+  attachments: AttachmentStore;
+  get?(name: string): unknown;
+};
+type PublishedMedia = {
+  path: string;
+  name: string;
+  kind: MediaKind;
+  mediaType: string;
+  bytes: number;
+  attachment: {
+    type: 'image';
+    attachment: ImageAttachmentRef;
+  } | {
+    type: 'file';
+    attachment: FileAttachmentRef;
+  };
+};
+declare class CliMediaError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string);
+}
+declare const MEDIA_LIMITS: Record<MediaKind, number>;
+declare function insideDirectory(root: string, path: string): boolean;
+/** Resolve each path component; links are not accepted as media or receipt boundaries. */
+declare function confinedPath(root: string, path: string): Promise<string>;
+declare function mediaWorkspace(host: MediaHost, exec: MediaExec, write: boolean): Promise<string>;
+declare function inspectMedia(path: string, kind: MediaKind): Promise<{
+  mediaType: string;
+  bytes: number;
+}>;
+declare function stageMedia(host: MediaHost, exec: MediaExec, root: string, directory: string, inputs: MediaInput[]): Promise<{
+  path: string;
+  mediaType: string;
+  bytes: number;
+}[]>;
+declare function jobDirectory(root: string, slug: string, id?: string): Promise<{
+  id: string;
+  directory: string;
+}>;
+declare function writeReceipt(directory: string, receipt: unknown): Promise<void>;
+declare function readReceipt<T>(root: string, slug: string, id: string): Promise<T>;
+declare function publishMedia(host: MediaHost, source: string, sourceRoot: string, destination: string, workspace: string, kind: MediaKind, signal: AbortSignal): Promise<PublishedMedia>;
+//#endregion
+export { CliMediaError, MEDIA_LIMITS, MediaExec, MediaHost, MediaInput, MediaKind, PublishedMedia, confinedPath, insideDirectory, inspectMedia, jobDirectory, mediaWorkspace, publishMedia, readReceipt, stageMedia, writeReceipt };
+//# sourceMappingURL=cli-media.d.ts.map

package/lib/cli-media.js

@@ -0,0 +1,249 @@
+import { createReadStream, createWriteStream } from "node:fs";
+import { lstat, mkdir, open, readFile, realpath, rename, writeFile } from "node:fs/promises";
+import { pipeline } from "node:stream/promises";
+import { basename, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { randomUUID } from "node:crypto";
+//#region src/cli-media.ts
+var CliMediaError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+		this.name = "CliMediaError";
+	}
+};
+const fail = (code, message) => new CliMediaError(code, message);
+const MEDIA_LIMITS = {
+	image: 31457280,
+	audio: 104857600,
+	video: 268435456
+};
+function insideDirectory(root, path) {
+	const rel = relative(root, path);
+	return !isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep}`);
+}
+/** Resolve each path component; links are not accepted as media or receipt boundaries. */
+async function confinedPath(root, path) {
+	const base = await realpath(root), absolute = resolve(base, path);
+	if (!insideDirectory(base, absolute) || (await lstat(root)).isSymbolicLink()) throw fail("outside-workspace", "The file must stay inside the permitted directory.");
+	let part = base;
+	for (const component of relative(base, absolute).split(sep).filter(Boolean)) {
+		part = join(part, component);
+		if ((await lstat(part)).isSymbolicLink()) throw fail("outside-workspace", "Symbolic links are not accepted for media files.");
+	}
+	const canonical = await realpath(absolute);
+	if (!insideDirectory(base, canonical)) throw fail("outside-workspace", "The file must stay inside the permitted directory.");
+	return canonical;
+}
+async function mediaWorkspace(host, exec, write) {
+	exec.signal.throwIfAborted();
+	const policy = host.sandboxPolicy.resolve({ session: exec.agent?.session });
+	if (write && policy.mode === "read-only") throw fail("read-only", "This operation saves media and needs workspace write access.");
+	const root = await realpath(policy.workspaceRoot);
+	if (!(await lstat(root)).isDirectory()) throw fail("invalid-workspace", "The workspace is unavailable.");
+	return root;
+}
+async function inspectMedia(path, kind) {
+	const info = await lstat(path);
+	if (!info.isFile() || info.isSymbolicLink() || info.size < 4 || info.size > MEDIA_LIMITS[kind]) throw fail("invalid-media", "The media file is empty, too large, or not a regular file.");
+	const file = await open(path, "r"), head = Buffer.alloc(64);
+	try {
+		await file.read(head, 0, head.length, 0);
+	} finally {
+		await file.close();
+	}
+	let mediaType;
+	if (head.subarray(0, 8).equals(Buffer.from([
+		137,
+		80,
+		78,
+		71,
+		13,
+		10,
+		26,
+		10
+	]))) mediaType = "image/png";
+	else if (head[0] === 255 && head[1] === 216 && head[2] === 255) mediaType = "image/jpeg";
+	else if (/^GIF8[79]a$/.test(head.toString("ascii", 0, 6))) mediaType = "image/gif";
+	else if (head.toString("ascii", 0, 4) === "RIFF" && head.toString("ascii", 8, 12) === "WEBP") mediaType = "image/webp";
+	else if (head.toString("ascii", 0, 4) === "RIFF" && head.toString("ascii", 8, 12) === "WAVE") mediaType = "audio/wav";
+	else if (head.toString("ascii", 0, 3) === "ID3" || head[0] === 255 && (head[1] & 224) === 224) mediaType = "audio/mpeg";
+	else if (head.toString("ascii", 0, 4) === "fLaC") mediaType = "audio/flac";
+	else if (head.toString("ascii", 0, 4) === "OggS") mediaType = "audio/ogg";
+	else if (head.toString("ascii", 4, 8) === "ftyp") {
+		const brand = head.toString("ascii", 8, 12);
+		mediaType = /^(?:heic|heix|hevc|hevx|mif1|msf1)$/.test(brand) ? "image/heic" : kind === "audio" ? "audio/mp4" : brand === "qt  " ? "video/quicktime" : "video/mp4";
+	} else if (head.subarray(0, 4).equals(Buffer.from([
+		26,
+		69,
+		223,
+		163
+	]))) mediaType = kind === "audio" ? "audio/webm" : "video/webm";
+	if (!mediaType?.startsWith(`${kind}/`)) throw fail("invalid-media", `The file is not a supported ${kind} file.`);
+	return {
+		mediaType,
+		bytes: info.size
+	};
+}
+async function sessionAttachments(host, exec) {
+	if (!exec.agent) throw fail("no-session", "Session attachments need an active session.");
+	const query = host.get?.("sessionQuery");
+	if (!query) throw fail("no-session-query", "The host cannot read current-session attachments.");
+	const snapshot = await query.readSession(exec.agent.session.id);
+	exec.signal.throwIfAborted();
+	const result = /* @__PURE__ */ new Map();
+	for (const raw of snapshot.events) {
+		const event = raw;
+		if (event.type !== "user/message" && event.type !== "tool/result") continue;
+		const content = event.data?.content ?? event.data?.message?.content;
+		if (!Array.isArray(content)) continue;
+		for (const block of content) if ((block?.type === "image" || block?.type === "file") && typeof block.attachment?.attachmentId === "string") result.set(block.attachment.attachmentId, block);
+	}
+	return result;
+}
+async function* bounded(chunks, max, signal) {
+	let bytes = 0;
+	for await (const chunk of chunks) {
+		signal.throwIfAborted();
+		bytes += chunk.byteLength;
+		if (bytes > max) throw fail("invalid-media", "The media file exceeds its size limit.");
+		yield chunk;
+	}
+	signal.throwIfAborted();
+}
+async function stageMedia(host, exec, root, directory, inputs) {
+	if (inputs.length > 40) throw fail("bad-request", "At most 40 input files are allowed.");
+	const refs = inputs.some((input) => input.attachmentId) ? await sessionAttachments(host, exec) : /* @__PURE__ */ new Map();
+	const staged = [];
+	for (const [index, input] of inputs.entries()) {
+		exec.signal.throwIfAborted();
+		if (!MEDIA_LIMITS[input.kind] || Boolean(input.path) === Boolean(input.attachmentId)) throw fail("bad-request", "Provide exactly one workspace path or current-session attachment ID per input.");
+		const ref = input.attachmentId ? refs.get(input.attachmentId) : void 0;
+		if (input.attachmentId && !ref) throw fail("unknown-attachment", "The attachment does not belong to the current session.");
+		const source = input.path ? await confinedPath(root, input.path) : void 0;
+		if (source) await inspectMedia(source, input.kind);
+		const rawName = source ? basename(source) : ref.attachment.name || "attachment";
+		const extension = /^\.[a-z0-9]{1,8}$/i.test(extname(rawName)) ? extname(rawName).toLowerCase() : ref?.type === "image" ? "." + ref.attachment.mediaType.split("/")[1] : ".bin";
+		const target = join(directory, `input-${index}${extension}`);
+		if (source) await pipeline(createReadStream(source), createWriteStream(target, { flags: "wx" }), { signal: exec.signal });
+		else if (ref.type === "image") {
+			if (input.kind !== "image") throw fail("invalid-media", "An image attachment cannot be used as audio or video.");
+			const stored = await host.attachments.readImage(ref.attachment, exec.signal);
+			if (stored.data.byteLength > MEDIA_LIMITS.image) throw fail("invalid-media", "The image is too large.");
+			await writeFile(target, stored.data, {
+				flag: "wx",
+				signal: exec.signal
+			});
+		} else await pipeline(bounded(host.attachments.readFileStream(ref.attachment, exec.signal), MEDIA_LIMITS[input.kind], exec.signal), createWriteStream(target, { flags: "wx" }), { signal: exec.signal });
+		const info = await inspectMedia(target, input.kind);
+		staged.push({
+			path: target,
+			...info
+		});
+	}
+	return staged;
+}
+async function jobDirectory(root, slug, id = randomUUID()) {
+	if (!/^dsh-[a-z0-9-]+$/.test(slug) || !/^[a-f0-9-]{36}$/i.test(id)) throw fail("bad-request", "Invalid media job identifier.");
+	const parent = join(root, `.${slug}`);
+	await mkdir(parent, { recursive: true });
+	await confinedPath(root, parent);
+	const directory = join(parent, id);
+	await mkdir(directory, { recursive: true });
+	await confinedPath(root, directory);
+	return {
+		id,
+		directory
+	};
+}
+async function writeReceipt(directory, receipt) {
+	const target = join(directory, "receipt.json"), temporary = join(directory, `receipt-${randomUUID()}.tmp`);
+	await confinedPath(directory, directory);
+	await writeFile(temporary, JSON.stringify(receipt, null, 2) + "\n", {
+		flag: "wx",
+		mode: 384
+	});
+	await rename(temporary, target);
+}
+async function readReceipt(root, slug, id) {
+	if (!/^dsh-[a-z0-9-]+$/.test(slug) || !/^[a-f0-9-]{36}$/i.test(id)) throw fail("bad-request", "Invalid media job identifier.");
+	const path = await confinedPath(root, join(root, `.${slug}`, id, "receipt.json"));
+	if ((await lstat(path)).size > 1048576) throw fail("invalid-receipt", "The media receipt is too large.");
+	return JSON.parse(await readFile(path, "utf8"));
+}
+async function publishMedia(host, source, sourceRoot, destination, workspace, kind, signal) {
+	signal.throwIfAborted();
+	const path = await confinedPath(sourceRoot, source), info = await inspectMedia(path, kind);
+	if (kind === "image" && ![
+		"image/png",
+		"image/jpeg",
+		"image/gif",
+		"image/webp"
+	].includes(info.mediaType)) throw fail("unsupported-media", "The host cannot attach this image format. Use PNG, JPEG, GIF or WebP.");
+	await confinedPath(workspace, destination);
+	const extension = {
+		"image/png": ".png",
+		"image/jpeg": ".jpg",
+		"image/gif": ".gif",
+		"image/webp": ".webp",
+		"audio/mpeg": ".mp3",
+		"audio/wav": ".wav",
+		"audio/flac": ".flac",
+		"audio/ogg": ".ogg",
+		"audio/mp4": ".m4a",
+		"video/mp4": ".mp4",
+		"video/quicktime": ".mov",
+		"video/webm": ".webm",
+		"audio/webm": ".webm"
+	}[info.mediaType];
+	const rawName = basename(path).replace(/[^\w.\-]/g, "_").slice(-100) || kind;
+	const name = extension ? rawName.replace(/\.[^.]*$/, "") + extension : rawName;
+	const reuse = insideDirectory(destination, path) && await realpath(sourceRoot) === await realpath(workspace);
+	const target = reuse ? path : join(destination, `${randomUUID().slice(0, 8)}-${name}`);
+	if (kind === "image") {
+		const input = {
+			data: await readFile(path),
+			mediaType: info.mediaType,
+			name
+		};
+		await host.attachments.validateImage(input);
+		signal.throwIfAborted();
+		if (!reuse) await writeFile(target, input.data, {
+			flag: "wx",
+			signal
+		});
+		const [attachment] = await host.attachments.saveImages([input]);
+		signal.throwIfAborted();
+		return {
+			path: relative(workspace, target).split(sep).join("/"),
+			name,
+			kind,
+			...info,
+			attachment: {
+				type: "image",
+				attachment
+			}
+		};
+	}
+	if (!reuse) await pipeline(createReadStream(path), createWriteStream(target, { flags: "wx" }), { signal });
+	const attachment = await host.attachments.saveFileStream({
+		data: bounded(createReadStream(target), MEDIA_LIMITS[kind], signal),
+		name,
+		signal
+	});
+	signal.throwIfAborted();
+	return {
+		path: relative(workspace, target).split(sep).join("/"),
+		name,
+		kind,
+		...info,
+		attachment: {
+			type: "file",
+			attachment
+		}
+	};
+}
+//#endregion
+export { CliMediaError, MEDIA_LIMITS, confinedPath, insideDirectory, inspectMedia, jobDirectory, mediaWorkspace, publishMedia, readReceipt, stageMedia, writeReceipt };
+
+//# sourceMappingURL=cli-media.js.map

package/lib/cli-media.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-media.js","names":[],"sources":["../src/cli-media.ts"],"sourcesContent":["import { createReadStream, createWriteStream } from 'node:fs'\nimport { lstat, realpath, mkdir, open, readFile, writeFile, rename } from 'node:fs/promises'\nimport { pipeline } from 'node:stream/promises'\nimport { basename, extname, isAbsolute, join, relative, resolve, sep } from 'node:path'\nimport { randomUUID } from 'node:crypto'\nimport type { AttachmentStore, ImageAttachmentRef, FileAttachmentRef, ImageMediaType } from '@deepseek-ai/dsh-attachment'\n\nexport type MediaKind = 'image' | 'audio' | 'video'\nexport type MediaInput = { path?: string; attachmentId?: string; kind: MediaKind }\nexport type MediaExec = { signal: AbortSignal; agent?: { session: { id: unknown } } }\nexport type MediaHost = {\n  sandboxPolicy: { resolve(input: { session?: unknown }): { workspaceRoot: string; mode: string } };\n  attachments: AttachmentStore;\n  get?(name: string): unknown;\n}\nexport type PublishedMedia = {\n  path: string; name: string; kind: MediaKind; mediaType: string; bytes: number;\n  attachment: { type: 'image'; attachment: ImageAttachmentRef } | { type: 'file'; attachment: FileAttachmentRef };\n}\nexport class CliMediaError extends Error {\n  constructor(public readonly code: string, message: string) { super(message); this.name = 'CliMediaError' }\n}\nconst fail = (code: string, message: string) => new CliMediaError(code, message)\nexport const MEDIA_LIMITS: Record<MediaKind, number> = { image: 30 * 1024 * 1024, audio: 100 * 1024 * 1024, video: 256 * 1024 * 1024 }\nexport function insideDirectory(root: string, path: string): boolean {\n  const rel = relative(root, path)\n  return !isAbsolute(rel) && rel !== '..' && !rel.startsWith(`..${sep}`)\n}\n/** Resolve each path component; links are not accepted as media or receipt boundaries. */\nexport async function confinedPath(root: string, path: string): Promise<string> {\n  const base = await realpath(root), absolute = resolve(base, path)\n  if (!insideDirectory(base, absolute) || (await lstat(root)).isSymbolicLink()) throw fail('outside-workspace', 'The file must stay inside the permitted directory.')\n  let part = base\n  for (const component of relative(base, absolute).split(sep).filter(Boolean)) {\n    part = join(part, component)\n    if ((await lstat(part)).isSymbolicLink()) throw fail('outside-workspace', 'Symbolic links are not accepted for media files.')\n  }\n  const canonical = await realpath(absolute)\n  if (!insideDirectory(base, canonical)) throw fail('outside-workspace', 'The file must stay inside the permitted directory.')\n  return canonical\n}\nexport async function mediaWorkspace(host: MediaHost, exec: MediaExec, write: boolean): Promise<string> {\n  exec.signal.throwIfAborted()\n  const policy = host.sandboxPolicy.resolve({ session: exec.agent?.session })\n  if (write && policy.mode === 'read-only') throw fail('read-only', 'This operation saves media and needs workspace write access.')\n  const root = await realpath(policy.workspaceRoot)\n  if (!(await lstat(root)).isDirectory()) throw fail('invalid-workspace', 'The workspace is unavailable.')\n  return root\n}\nexport async function inspectMedia(path: string, kind: MediaKind): Promise<{ mediaType: string; bytes: number }> {\n  const info = await lstat(path)\n  if (!info.isFile() || info.isSymbolicLink() || info.size < 4 || info.size > MEDIA_LIMITS[kind]) throw fail('invalid-media', 'The media file is empty, too large, or not a regular file.')\n  const file = await open(path, 'r'), head = Buffer.alloc(64)\n  try { await file.read(head, 0, head.length, 0) } finally { await file.close() }\n  let mediaType: string | undefined\n  if (head.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) mediaType = 'image/png'\n  else if (head[0] === 255 && head[1] === 216 && head[2] === 255) mediaType = 'image/jpeg'\n  else if (/^GIF8[79]a$/.test(head.toString('ascii', 0, 6))) mediaType = 'image/gif'\n  else if (head.toString('ascii', 0, 4) === 'RIFF' && head.toString('ascii', 8, 12) === 'WEBP') mediaType = 'image/webp'\n  else if (head.toString('ascii', 0, 4) === 'RIFF' && head.toString('ascii', 8, 12) === 'WAVE') mediaType = 'audio/wav'\n  else if (head.toString('ascii', 0, 3) === 'ID3' || (head[0] === 255 && (head[1] & 224) === 224)) mediaType = 'audio/mpeg'\n  else if (head.toString('ascii', 0, 4) === 'fLaC') mediaType = 'audio/flac'\n  else if (head.toString('ascii', 0, 4) === 'OggS') mediaType = 'audio/ogg'\n  else if (head.toString('ascii', 4, 8) === 'ftyp') {\n    const brand = head.toString('ascii', 8, 12)\n    mediaType = /^(?:heic|heix|hevc|hevx|mif1|msf1)$/.test(brand) ? 'image/heic' : kind === 'audio' ? 'audio/mp4' : brand === 'qt  ' ? 'video/quicktime' : 'video/mp4'\n  } else if (head.subarray(0, 4).equals(Buffer.from([26, 69, 223, 163]))) mediaType = kind === 'audio' ? 'audio/webm' : 'video/webm'\n  if (!mediaType?.startsWith(`${kind}/`)) throw fail('invalid-media', `The file is not a supported ${kind} file.`)\n  return { mediaType, bytes: info.size }\n}\nasync function sessionAttachments(host: MediaHost, exec: MediaExec): Promise<Map<string, { type: 'image' | 'file'; attachment: ImageAttachmentRef | FileAttachmentRef }>> {\n  if (!exec.agent) throw fail('no-session', 'Session attachments need an active session.')\n  const query = host.get?.('sessionQuery') as { readSession(id: unknown): Promise<{ events: unknown[] }> } | undefined\n  if (!query) throw fail('no-session-query', 'The host cannot read current-session attachments.')\n  const snapshot = await query.readSession(exec.agent.session.id)\n  exec.signal.throwIfAborted()\n  const result = new Map<string, { type: 'image' | 'file'; attachment: ImageAttachmentRef | FileAttachmentRef }>()\n  for (const raw of snapshot.events) {\n    const event = raw as { type?: string; data?: { content?: unknown; message?: { content?: unknown } } }\n    if (event.type !== 'user/message' && event.type !== 'tool/result') continue\n    const content = event.data?.content ?? event.data?.message?.content\n    if (!Array.isArray(content)) continue\n    for (const block of content) {\n      if ((block?.type === 'image' || block?.type === 'file') && typeof block.attachment?.attachmentId === 'string') result.set(block.attachment.attachmentId, block)\n    }\n  }\n  return result\n}\nasync function* bounded(chunks: AsyncIterable<Uint8Array>, max: number, signal: AbortSignal): AsyncIterable<Uint8Array> {\n  let bytes = 0\n  for await (const chunk of chunks) {\n    signal.throwIfAborted(); bytes += chunk.byteLength\n    if (bytes > max) throw fail('invalid-media', 'The media file exceeds its size limit.')\n    yield chunk\n  }\n  signal.throwIfAborted()\n}\nexport async function stageMedia(host: MediaHost, exec: MediaExec, root: string, directory: string, inputs: MediaInput[]): Promise<{ path: string; mediaType: string; bytes: number }[]> {\n  if (inputs.length > 40) throw fail('bad-request', 'At most 40 input files are allowed.')\n  const refs = inputs.some(input => input.attachmentId) ? await sessionAttachments(host, exec) : new Map()\n  const staged: { path: string; mediaType: string; bytes: number }[] = []\n  for (const [index, input] of inputs.entries()) {\n    exec.signal.throwIfAborted()\n    if (!MEDIA_LIMITS[input.kind] || Boolean(input.path) === Boolean(input.attachmentId)) throw fail('bad-request', 'Provide exactly one workspace path or current-session attachment ID per input.')\n    const ref = input.attachmentId ? refs.get(input.attachmentId) : undefined\n    if (input.attachmentId && !ref) throw fail('unknown-attachment', 'The attachment does not belong to the current session.')\n    const source = input.path ? await confinedPath(root, input.path) : undefined\n    if (source) await inspectMedia(source, input.kind)\n    const rawName = source ? basename(source) : ref!.attachment.name || 'attachment'\n    const extension = /^\\.[a-z0-9]{1,8}$/i.test(extname(rawName)) ? extname(rawName).toLowerCase() : ref?.type === 'image' ? '.' + (ref.attachment as ImageAttachmentRef).mediaType.split('/')[1] : '.bin'\n    const target = join(directory, `input-${index}${extension}`)\n    if (source) await pipeline(createReadStream(source), createWriteStream(target, { flags: 'wx' }), { signal: exec.signal })\n    else if (ref!.type === 'image') {\n      if (input.kind !== 'image') throw fail('invalid-media', 'An image attachment cannot be used as audio or video.')\n      const stored = await host.attachments.readImage(ref!.attachment as ImageAttachmentRef, exec.signal)\n      if (stored.data.byteLength > MEDIA_LIMITS.image) throw fail('invalid-media', 'The image is too large.')\n      await writeFile(target, stored.data, { flag: 'wx', signal: exec.signal })\n    } else await pipeline(bounded(host.attachments.readFileStream(ref!.attachment as FileAttachmentRef, exec.signal), MEDIA_LIMITS[input.kind], exec.signal), createWriteStream(target, { flags: 'wx' }), { signal: exec.signal })\n    const info = await inspectMedia(target, input.kind)\n    staged.push({ path: target, ...info })\n  }\n  return staged\n}\nexport async function jobDirectory(root: string, slug: string, id: string = randomUUID()): Promise<{ id: string; directory: string }> {\n  if (!/^dsh-[a-z0-9-]+$/.test(slug) || !/^[a-f0-9-]{36}$/i.test(id)) throw fail('bad-request', 'Invalid media job identifier.')\n  const parent = join(root, `.${slug}`)\n  await mkdir(parent, { recursive: true }); await confinedPath(root, parent)\n  const directory = join(parent, id)\n  await mkdir(directory, { recursive: true }); await confinedPath(root, directory)\n  return { id, directory }\n}\nexport async function writeReceipt(directory: string, receipt: unknown): Promise<void> {\n  const target = join(directory, 'receipt.json'), temporary = join(directory, `receipt-${randomUUID()}.tmp`)\n  await confinedPath(directory, directory)\n  await writeFile(temporary, JSON.stringify(receipt, null, 2) + '\\n', { flag: 'wx', mode: 0o600 })\n  // Replacement is atomic in this directory; credentials and signed URLs do not belong in receipts.\n  await rename(temporary, target)\n}\nexport async function readReceipt<T>(root: string, slug: string, id: string): Promise<T> {\n  if (!/^dsh-[a-z0-9-]+$/.test(slug) || !/^[a-f0-9-]{36}$/i.test(id)) throw fail('bad-request', 'Invalid media job identifier.')\n  const path = await confinedPath(root, join(root, `.${slug}`, id, 'receipt.json'))\n  if ((await lstat(path)).size > 1024 * 1024) throw fail('invalid-receipt', 'The media receipt is too large.')\n  return JSON.parse(await readFile(path, 'utf8')) as T\n}\nexport async function publishMedia(host: MediaHost, source: string, sourceRoot: string, destination: string, workspace: string, kind: MediaKind, signal: AbortSignal): Promise<PublishedMedia> {\n  signal.throwIfAborted()\n  const path = await confinedPath(sourceRoot, source), info = await inspectMedia(path, kind)\n  if (kind === 'image' && !['image/png', 'image/jpeg', 'image/gif', 'image/webp'].includes(info.mediaType)) throw fail('unsupported-media', 'The host cannot attach this image format. Use PNG, JPEG, GIF or WebP.')\n  await confinedPath(workspace, destination)\n  const extension = ({ 'image/png': '.png', 'image/jpeg': '.jpg', 'image/gif': '.gif', 'image/webp': '.webp', 'audio/mpeg': '.mp3', 'audio/wav': '.wav', 'audio/flac': '.flac', 'audio/ogg': '.ogg', 'audio/mp4': '.m4a', 'video/mp4': '.mp4', 'video/quicktime': '.mov', 'video/webm': '.webm', 'audio/webm': '.webm' } as Record<string, string>)[info.mediaType]\n  const rawName = basename(path).replace(/[^\\w.\\-]/g, '_').slice(-100) || kind\n  const name = extension ? rawName.replace(/\\.[^.]*$/, '') + extension : rawName\n  const reuse = insideDirectory(destination, path) && await realpath(sourceRoot) === await realpath(workspace)\n  const target = reuse ? path : join(destination, `${randomUUID().slice(0, 8)}-${name}`)\n  if (kind === 'image') {\n    const input = { data: await readFile(path), mediaType: info.mediaType as ImageMediaType, name }\n    await host.attachments.validateImage(input)\n    signal.throwIfAborted()\n    if (!reuse) await writeFile(target, input.data, { flag: 'wx', signal })\n    const [attachment] = await host.attachments.saveImages([input])\n    signal.throwIfAborted()\n    return { path: relative(workspace, target).split(sep).join('/'), name, kind, ...info, attachment: { type: 'image', attachment } }\n  }\n  if (!reuse) await pipeline(createReadStream(path), createWriteStream(target, { flags: 'wx' }), { signal })\n  const attachment = await host.attachments.saveFileStream({ data: bounded(createReadStream(target), MEDIA_LIMITS[kind], signal), name, signal })\n  signal.throwIfAborted()\n  return { path: relative(workspace, target).split(sep).join('/'), name, kind, ...info, attachment: { type: 'file', attachment } }\n}\n"],"mappings":"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"}

package/lib/cli-process.d.ts

@@ -0,0 +1,33 @@
+import { spawn } from "node:child_process";
+//#region src/cli-process.d.ts
+/** A resolved executable, never a shell command or an argument string. */
+type CliExecutable = {
+  command: string;
+  args?: string[];
+  env?: NodeJS.ProcessEnv;
+  displayPath: string;
+};
+type CliOutput = {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+};
+declare class CliProcessError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string);
+}
+type CliOptions = {
+  cwd: string;
+  signal: AbortSignal;
+  input?: string;
+  timeoutMs?: number;
+  maxOutputBytes?: number;
+  maxLineBytes?: number;
+  onLine?: (line: string) => void | Promise<void>;
+  spawnChild?: typeof spawn;
+};
+/** Own one process tree until it exits, including caller cancellation and protocol failure. */
+declare function runCli(executable: CliExecutable, args: string[], options: CliOptions): Promise<CliOutput>;
+//#endregion
+export { CliExecutable, CliOptions, CliOutput, CliProcessError, runCli };
+//# sourceMappingURL=cli-process.d.ts.map