@qilin-agent/host-preview-media 0.0.0-stage → 3.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,34 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/host/preview-media/README.md
+/:
+  en: e64f5d01c95cea56
+  zh: 9761d65e30145b9c
+/qilin-host-preview-media:
+  en: e65470c637ecb5e4
+  zh: db57c6508415526f
+/qilin-host-preview-media/summary:
+  en: 404789ef764fe78e
+  zh: e10a8d8e40b33759
+/qilin-host-preview-media/table-of-contents:
+  en: 35483a1f97ac9ea3
+  zh: 2b4d4af0605f0475
+/qilin-host-preview-media/use-this-package:
+  en: 979f3aa7497c6c57
+  zh: 6dcf16bd29c5dd98
+/qilin-host-preview-media/use-this-package/what-to-expect:
+  en: cc5101057995ecaa
+  zh: b9fcfd8eb9c921c4
+/qilin-host-preview-media/model-experience:
+  en: 942a0174b133bcfe
+  zh: b6dca2d453309eb1
+/qilin-host-preview-media/model-experience/kv-cache-effect:
+  en: ca75c51c89c2c9b0
+  zh: ac87fc083e6f2eb0
+/qilin-host-preview-media/known-limitations-and-deferred-work:
+  en: e501ac1171311128
+  zh: 2ed1b3666cc8af6d
+/qilin-host-preview-media/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+---
+description: "Host half of preview media: the /sidebar/media route serving session-workspace files to inline previews, with HTTP Range windows for seeking video."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @qilin-agent/host-preview-media
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Two webServer routes under `/sidebar/media` serve the browser's inline previews. `GET/HEAD /sidebar/media?sessionId=<id>&path=<p>` serves a session-workspace file. A request with a `Range` header is answered from a windowed read (`206`), so the document preview's video element can seek; `?download=1` switches the disposition so the browser saves the file. Whole-file responses are bounded by `mediaLimitBytes`.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Model Experience](#model-experience)
+- [Dev Note](#dev-note)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+
+## Use this package
+
+Mount it in any composition that serves the web app and wants inline media previews. The route needs no configuration; `mediaLimitBytes` (default 20 MiB) bounds one whole-file response, while a ranged request reads only its window and is exempt.
+
+### What to expect
+
+- `206` with `Content-Range` for satisfiable single ranges, `416` for a start past EOF, plain `200` without a usable range header.
+- Reads resolve through the abstract filesystem service, so remote execution worlds serve the same route.
+- The connection service's request rejection (origin fence plus browser authentication) gates every request.
+- `PUT /sidebar/media/upload?sessionId=<id>&path=<p>` writes one complete file into the session workspace through the filesystem's `writeBytes` (create or replace, no version guard); the body is bounded by `mediaLimitBytes` and an oversized body is refused with `400` before any write. The files tab's drop-upload is the caller.
+
+## Model Experience
+
+None, as this package registers no tool, contributes no prompt section, and appends no session event; the route serves bytes the user can already read through the preview surface.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **Single-window ranges** — one `Range` spec is honored per request; a multi-spec header serves the first window only.
+- **Whole-file GET bounded, upload capped once** — a plain `GET` beyond `mediaLimitBytes` is refused, and an upload body crossing the same cap is rejected before any write; there is no chunked or resumable transfer.
+- **Disposition is all-or-nothing** — `?download=1` forces the attachment disposition on the whole answer; no partial-content download resumes.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,57 @@
+---
+description: "预览媒体的宿主半：/sidebar/media 路由向内联预览供出会话工作区文件，带 HTTP Range 窗口供视频拖动进度条。"
+kind: "package-reference"
+---
+
+# @qilin-agent/host-preview-media
+
+[English](README.md) | 中文
+
+## 概述
+
+`/sidebar/media` 之下的两条 webServer 路由服务浏览器的内联预览。`GET/HEAD /sidebar/media?sessionId=<id>&path=<p>` 供出一个会话工作区文件。带 `Range` 头的请求以窗口读回答 `206`，文档预览的 video 元素因此可拖动进度条；`?download=1` 切换处置方式让浏览器保存文件。整文件回答受 `mediaLimitBytes` 约束。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [模型体验](#model-experience)
+- [开发备注](#dev-note)
+- [已知限制与后续工作](#known-limitations-and-deferred-work)
+
+<a id="use-this-package"></a>
+## 使用本包
+
+在任何服务 Web 应用且需要内联媒体预览的组合中挂载。路由无需配置；`mediaLimitBytes`（默认 20 MiB）约束一次整文件回答，ranged 请求只读自身窗口、不受该上限约束。
+
+### 预期行为
+
+- 可满足的单区间得 `206` 与 `Content-Range`；起点越过 EOF 得 `416`；无可用 Range 头得普通 `200`。
+- 读取经抽象文件系统服务解析，远程执行世界同样由此路由供出。
+- connection 服务的请求拒绝（来源围栏加浏览器认证）先于一切字节放行。
+- `PUT /sidebar/media/upload?sessionId=<id>&path=<p>` 经文件系统的 `writeBytes` 向会话工作区写入一个完整文件（创建或覆盖，无版本守卫）；请求体受 `mediaLimitBytes` 约束，超限在写入前即以 `400` 拒绝。文件页的拖放上传是它的调用方。
+
+<a id="model-experience"></a>
+## 模型体验
+
+无，本包不注册工具、不贡献 prompt 小节、不追加会话事件；路由供出的是用户本就能经预览面读到的字节。
+
+#### KV 缓存影响
+
+无；本包既不组装也不发送任何提供方请求。
+
+<a id="known-limitations-and-deferred-work"></a>
+## 已知限制与后续工作
+
+- **单窗口 Range**——每次请求只尊重一个 `Range` 规格；多规格头只服务第一个窗口。
+- **整文件 GET 有界、上传一次性设限**——超过 `mediaLimitBytes` 的普通 `GET` 被拒绝，越过同一上限的上传体在写入前即被拒绝；没有分块或可续传传输。
+- **处置方式全有或全无**——`?download=1` 对整个回答强制附件处置；没有可续传的部分内容下载。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,282 @@
+import z from "@qilin-agent/schemastery";
+//#region lib/types/range.js
+/**
+* Range-header parsing for the preview media route: RFC 9110 §14 single-range
+* semantics, adapted to windowed reads over the abstract filesystem service.
+*/
+/**
+* Parse a single `Range: bytes=...` header against a known size.
+*
+* Semantics (mirroring the video-preview contract this route serves):
+* - only the FIRST range of a multi-range set is honoured,
+* - `bytes=-N` is a suffix range (the last N bytes; `N >= size` = whole file),
+* - `bytes=N-` runs to EOF, `bytes=A-B` is clamped to EOF,
+* - non-integer / negative / empty / inverted specs are ignored (serve 200),
+* - a start at or past EOF is unsatisfiable (416).
+* @param raw - the raw `Range` header value (undefined when absent).
+* @param size - the file size in bytes.
+* @returns the parsed window, `null` when the header admits no range, or an unsatisfiable marker for a start at or past EOF.
+*/
+function parseRange(raw, size) {
+	if (raw === void 0) return null;
+	if (size <= 0) return { unsatisfiable: true };
+	const match = /^bytes=(.+)$/i.exec(raw.trim());
+	if (match === null) return null;
+	const [firstSpec = ""] = (match[1] ?? "").split(",");
+	const spec = firstSpec.trim();
+	if (spec === "") return null;
+	if (spec.startsWith("-")) {
+		const suffix = Number(spec.slice(1));
+		if (!Number.isFinite(suffix) || suffix <= 0) return null;
+		if (suffix >= size) return {
+			start: 0,
+			end: size - 1
+		};
+		return {
+			start: size - suffix,
+			end: size - 1
+		};
+	}
+	const dash = spec.indexOf("-");
+	if (dash === -1) return null;
+	const startText = spec.slice(0, dash);
+	const endText = spec.slice(dash + 1);
+	const start = startText === "" ? 0 : Number(startText);
+	const end = endText === "" ? size - 1 : Number(endText);
+	if (!Number.isInteger(start) || start < 0 || !Number.isInteger(end)) return null;
+	if (start >= size) return { unsatisfiable: true };
+	if (end < start) return null;
+	return {
+		start,
+		end: Math.min(end, size - 1)
+	};
+}
+//#endregion
+//#region lib/types/index.js
+/** Route path the browser media URL builder points at (prefix match). */
+const PREVIEW_MEDIA_PATH = "/sidebar/media";
+/** Content types served by the route, by lowercase extension. */
+const MEDIA_TYPES = {
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".gif": "image/gif",
+	".svg": "image/svg+xml",
+	".webp": "image/webp",
+	".bmp": "image/bmp",
+	".ico": "image/x-icon",
+	".avif": "image/avif",
+	".pdf": "application/pdf",
+	".html": "text/html",
+	".htm": "text/html",
+	".mp4": "video/mp4",
+	".m4v": "video/mp4",
+	".webm": "video/webm",
+	".ogv": "video/ogg",
+	".ogg": "audio/ogg",
+	".mov": "video/quicktime",
+	".qt": "video/quicktime",
+	".mkv": "video/x-matroska",
+	".avi": "video/x-msvideo",
+	".wmv": "video/x-ms-wmv",
+	".flv": "video/x-flv",
+	".m2ts": "video/mp2t",
+	".mpeg": "video/mpeg",
+	".mpg": "video/mpeg",
+	".3gp": "video/3gpp",
+	".3g2": "video/3gpp2"
+};
+/** The binary-safe fallback for extensions the table does not name. */
+const FALLBACK_TYPE = "application/octet-stream";
+/** Content type for one path: the table's entry for its extension, or the fallback. */
+function mediaTypeOf(path) {
+	const dot = path.lastIndexOf(".");
+	return MEDIA_TYPES[dot === -1 ? "" : path.slice(dot).toLowerCase()] ?? FALLBACK_TYPE;
+}
+/** One route failure: the HTTP status and the plain-text line to send. */
+var MediaError = class extends Error {
+	status;
+	constructor(status, message) {
+		super(message);
+		this.status = status;
+	}
+};
+/** The composition's connection service (typed locally: its package is browser-side). */
+function connectionOf(ctx) {
+	return Reflect.get(ctx, "connection");
+}
+/** Send the failure line and end the response. */
+function writeError(res, error) {
+	const status = error instanceof MediaError ? error.status : 500;
+	const line = error instanceof Error ? error.message : String(error);
+	if (!res.headersSent) res.writeHead(status, { "content-type": "text/plain; charset=utf-8" });
+	res.end(status === 500 ? "internal error" : line);
+}
+/** Headers shared by every media response (206 and 200 alike). */
+function mediaHeaders(type) {
+	return {
+		"content-type": type,
+		"accept-ranges": "bytes",
+		"cache-control": "no-cache"
+	};
+}
+/** The basename of a path, for the download disposition. */
+function basenameOf(path) {
+	const slash = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+	return slash === -1 ? path : path.slice(slash + 1);
+}
+/**
+* Resolve one request's `sessionId`/`path` pair to the file it names, against
+* the session's live workspace root (the deployment sandbox root as fallback).
+* Both routes that take the pair share this read; what each does with the
+* target — bounded read, ranged window, or contained write — stays with the route.
+* @param ctx - host context carrying the session registry, sandbox policy, and filesystem service.
+* @param url - the request URL whose query names the target.
+* @returns the requested path, the workspace root it resolved under, and the resolved target.
+* @throws {MediaError} 400 when either query parameter is absent or empty, 404 when the session is unknown.
+*/
+async function resolveMediaTarget(ctx, url) {
+	const sessionId = url.searchParams.get("sessionId");
+	const path = url.searchParams.get("path");
+	if (sessionId === null || path === null || path === "") throw new MediaError(400, "sessionId and path are required");
+	const live = ctx.sessions.get(sessionId);
+	if (live === void 0) throw new MediaError(404, `no session "${sessionId}"`);
+	const root = live.header.cwd ?? ctx.sandboxPolicy.workspaceRoot;
+	return {
+		path,
+		root,
+		target: await ctx.fs.resolve(path, { cwd: root })
+	};
+}
+const inject = [
+	"webServer",
+	"connection",
+	"sessions",
+	"sandboxPolicy",
+	"fs"
+];
+/**
+* Register the preview media route over the composition's filesystem.
+* @param ctx - host context carrying the web server, connection fence,
+* session registry, sandbox policy, and filesystem service.
+* @param config - validated Cordis row (the media limit with its default applied).
+*/
+function apply(ctx, config) {
+	const mediaLimitBytes = config.mediaLimitBytes ?? 20 * 1024 * 1024;
+	const connection = connectionOf(ctx);
+	/** The composition's rejection for one request, or undefined when admitted. */
+	const rejectionOf = (req) => connection.requestRejection(req);
+	ctx.effect(() => ctx.webServer.register({
+		kind: "prefix",
+		path: PREVIEW_MEDIA_PATH,
+		handler: async (req, res) => {
+			const rejection = rejectionOf(req);
+			if (rejection !== void 0) {
+				res.statusCode = rejection;
+				res.end();
+				return;
+			}
+			if (req.method !== "GET" && req.method !== "HEAD") {
+				res.writeHead(405, { allow: "GET, HEAD" });
+				res.end();
+				return;
+			}
+			try {
+				const url = new URL(req.url ?? "/", "http://qilin.internal");
+				const { path, target } = await resolveMediaTarget(ctx, url);
+				const info = await ctx.fs.stat(target);
+				if (info === void 0) throw new MediaError(404, `no entry at "${path}"`);
+				if (info.type !== "file") throw new MediaError(400, `"${path}" is a ${info.type}`);
+				const type = mediaTypeOf(path);
+				const range = info.size === void 0 ? null : parseRange(req.headers.range, info.size);
+				if (range !== null && "unsatisfiable" in range) {
+					const size = info.size ?? 0;
+					res.writeHead(416, {
+						...mediaHeaders(type),
+						"content-range": `bytes */${size}`
+					});
+					res.end();
+					return;
+				}
+				if (range !== null) {
+					const { start, end } = range;
+					const body = await ctx.fs.readByteRange(target, {
+						offset: start,
+						length: end - start + 1
+					});
+					res.writeHead(206, {
+						...mediaHeaders(type),
+						"content-range": `bytes ${start}-${end}/${info.size}`,
+						"content-length": String(body.byteLength)
+					});
+					res.end(req.method === "HEAD" ? void 0 : body);
+					return;
+				}
+				if (info.size !== void 0 && info.size > mediaLimitBytes) throw new MediaError(400, `"${path}" exceeds the preview media limit`);
+				const body = await ctx.fs.readBytes(target, void 0, mediaLimitBytes);
+				const headers = {
+					...mediaHeaders(type),
+					"content-length": String(body.byteLength)
+				};
+				if (url.searchParams.get("download") === "1") headers["content-disposition"] = `attachment; filename*=UTF-8''${encodeURIComponent(basenameOf(path))}`;
+				res.writeHead(200, headers);
+				res.end(req.method === "HEAD" ? void 0 : body);
+			} catch (error) {
+				writeError(res, error);
+			}
+		}
+	}), `preview-media: GET/HEAD ${PREVIEW_MEDIA_PATH}`);
+	/** Buffer one request body up to a byte ceiling; the caller names its limit. */
+	const readBody = async (req, limit) => {
+		const chunks = [];
+		let total = 0;
+		for await (const chunk of req) {
+			const piece = chunk;
+			total += piece.byteLength;
+			if (total > limit) throw new MediaError(400, "upload exceeds the media limit");
+			chunks.push(piece);
+		}
+		return Buffer.concat(chunks);
+	};
+	ctx.effect(() => ctx.webServer.register({
+		kind: "exact",
+		path: `${PREVIEW_MEDIA_PATH}/upload`,
+		handler: async (req, res) => {
+			const rejection = rejectionOf(req);
+			if (rejection !== void 0) {
+				res.statusCode = rejection;
+				res.end();
+				return;
+			}
+			if (req.method !== "PUT") {
+				res.writeHead(405, { allow: "PUT" });
+				res.end();
+				return;
+			}
+			try {
+				const { path, root, target } = await resolveMediaTarget(ctx, new URL(req.url ?? "/", "http://qilin.internal"));
+				if (!ctx.fs.contains(await ctx.fs.resolve(root), target)) throw new MediaError(403, `"${path}" is outside the workspace`);
+				const body = await readBody(req, mediaLimitBytes);
+				const outcome = await ctx.fs.writeBytes(target, body, void 0, void 0, {
+					mode: "workspace-write",
+					workspaceRoot: root
+				});
+				res.writeHead(200, {
+					"content-type": "application/json",
+					"cache-control": "no-store"
+				});
+				res.end(JSON.stringify({
+					ok: true,
+					path,
+					version: outcome.version
+				}));
+			} catch (error) {
+				writeError(res, error);
+			}
+		}
+	}), `preview-media: PUT ${PREVIEW_MEDIA_PATH}/upload`);
+}
+/** Cordis row Config schema: the media limit is a positive byte count. */
+const Config = z.object({ mediaLimitBytes: z.number().step(1).min(1).max(2147483647).default(20 * 1024 * 1024) });
+//#endregion
+export { Config, PREVIEW_MEDIA_PATH, apply, inject };

package/lib/types/index.d.ts

@@ -0,0 +1,20 @@
+import type { Context } from '@qilin-agent/kylin';
+import z from '@qilin-agent/schemastery';
+/** Route path the browser media URL builder points at (prefix match). */
+export declare const PREVIEW_MEDIA_PATH = "/sidebar/media";
+/** Cordis row selecting the media limit. */
+export interface Config {
+    /** Ceiling in bytes for one whole-file (non-ranged) response. */
+    mediaLimitBytes?: number;
+}
+export declare const inject: string[];
+/**
+ * Register the preview media route over the composition's filesystem.
+ * @param ctx - host context carrying the web server, connection fence,
+ * session registry, sandbox policy, and filesystem service.
+ * @param config - validated Cordis row (the media limit with its default applied).
+ */
+export declare function apply(ctx: Context, config: Config): void;
+/** Cordis row Config schema: the media limit is a positive byte count. */
+export declare const Config: z<Config>;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/range.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Range-header parsing for the preview media route: RFC 9110 §14 single-range
+ * semantics, adapted to windowed reads over the abstract filesystem service.
+ */
+/** A resolved, satisfiable byte range (both ends inclusive). */
+export interface ByteRange {
+    start: number;
+    end: number;
+}
+/**
+ * The outcome of parsing one `Range` header:
+ * - {@link ByteRange} — serve 206 for these bytes,
+ * - `{ unsatisfiable: true }` — well-formed but past EOF: serve 416,
+ * - `null` — no (usable) range: serve the full 200 response.
+ */
+export type ParsedRange = ByteRange | {
+    unsatisfiable: true;
+} | null;
+/**
+ * Parse a single `Range: bytes=...` header against a known size.
+ *
+ * Semantics (mirroring the video-preview contract this route serves):
+ * - only the FIRST range of a multi-range set is honoured,
+ * - `bytes=-N` is a suffix range (the last N bytes; `N >= size` = whole file),
+ * - `bytes=N-` runs to EOF, `bytes=A-B` is clamped to EOF,
+ * - non-integer / negative / empty / inverted specs are ignored (serve 200),
+ * - a start at or past EOF is unsatisfiable (416).
+ * @param raw - the raw `Range` header value (undefined when absent).
+ * @param size - the file size in bytes.
+ * @returns the parsed window, `null` when the header admits no range, or an unsatisfiable marker for a start at or past EOF.
+ */
+export declare function parseRange(raw: string | undefined, size: number): ParsedRange;
+//# sourceMappingURL=range.d.ts.map

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@qilin-agent/host-preview-media",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Host half of preview media: the /sidebar/media route serving session-workspace files to inline previews, with HTTP Range windows for seeking video",
+  "version": "3.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/host/preview-media"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@qilin-agent/schemastery": "~3.18.3"
+  },
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "devDependencies": {
+    "@qilin-agent/kylin-plugin-loader": "~1.0.4",
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/host-webserver": "3.1.3"
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
 }