@cjhyy/code-shell-server 0.9.13 → 0.9.14

package/dist/panels/bridge-contract.d.ts

@@ -33,6 +33,7 @@ export declare function panelRuntimeCapabilities(input: {
 }): {
     tasks?: {} | undefined;
     resources?: {
+        createReferences?: boolean | undefined;
         materialize: boolean;
         capture: boolean;
     } | undefined;

package/dist/panels/bridge-contract.js

@@ -24,6 +24,10 @@ export const panelResourceMethods = [
     "resources.upload.cancel",
     "resources.materialize",
     "resources.capture",
+    "resources.references.create",
+    "resources.references.get",
+    "resources.references.relink",
+    "resources.references.forget",
 ];
 export const panelToolJobMethods = [
     "tasks.start",
@@ -84,6 +88,9 @@ export function panelRuntimeCapabilities(input) {
                     ...input.resources,
                     materialize: input.process,
                     capture: input.process,
+                    ...(input.resources.externalReferences
+                        ? { createReferences: input.process }
+                        : {}),
                 },
             }
             : {}),

package/dist/panels/resources/directories.d.ts

@@ -7,6 +7,11 @@ export declare function openResourceDirectory(root: string, path: string, create
     path: string;
     location: (file: string) => string;
     rootIdentity: Stats;
+    rootPath: string;
+    identities: {
+        dev: number;
+        ino: number;
+    }[];
     verify: () => Promise<void>;
     close: () => Promise<void>;
 }>;

package/dist/panels/resources/directories.js

@@ -48,7 +48,8 @@ export async function openResourceDirectory(root, path, create, authorize) {
         const original = await lstat(root);
         if (!original.isDirectory() || original.isSymbolicLink())
             throw new Error("Resource directory must not be a symlink");
-        let current = await realpath(root);
+        const rootPath = await realpath(root);
+        let current = rootPath;
         for (let i = -1; i < parts.length; i++) {
             if (i >= 0) {
                 await verify();
@@ -80,7 +81,16 @@ export async function openResourceDirectory(root, path, create, authorize) {
         const location = (file) => process.platform === "linux"
             ? `/proc/self/fd/${parent.handle.fd}/${file}`
             : join(parent.path, file);
-        return { name, path: location(name), location, rootIdentity: held[0].identity, verify, close };
+        return {
+            name,
+            path: location(name),
+            location,
+            rootIdentity: held[0].identity,
+            rootPath,
+            identities: held.map(({ identity }) => ({ dev: identity.dev, ino: identity.ino })),
+            verify,
+            close,
+        };
     }
     catch (error) {
         await close();

package/dist/panels/resources/library.d.ts

@@ -1,5 +1,6 @@
 import type { Readable } from "node:stream";
 import type { MediaAsset, MediaScope } from "./types.js";
+export declare function resourceMimeType(name: string, requested?: string): string;
 export interface MediaLibraryOptions {
     rootDirectory: string;
     maxFileBytes?: number;
@@ -32,6 +33,10 @@ export interface MediaReadResult {
     body: Readable | null;
 }
 export declare function resourceName(value: string): string;
+export declare function rangeBounds(range: string, size: number): {
+    start: number;
+    end: number;
+} | null;
 /**
  * Host-owned immutable, scope-local media. importFile accepts only paths already
  * authorized by the caller (for example native file selection); guest APIs must

package/dist/panels/resources/library.js

@@ -50,6 +50,12 @@ const SAFE_MIME_TYPES = new Set([
     "audio/webm",
     "application/octet-stream",
 ]);
+export function resourceMimeType(name, requested) {
+    const mime = requested?.split(";", 1)[0].toLowerCase();
+    return mime && SAFE_MIME_TYPES.has(mime)
+        ? mime
+        : (MIME_BY_EXTENSION[extname(name).toLowerCase()] ?? "application/octet-stream");
+}
 export function mediaSourceIdentity(info) {
     return {
         dev: info.dev,
@@ -87,7 +93,7 @@ function assetRecord(raw, id) {
         createdAt: value.createdAt,
     };
 }
-function rangeBounds(range, size) {
+export function rangeBounds(range, size) {
     const match = /^bytes=(\d*)-(\d*)$/.exec(range);
     if (!match || (!match[1] && !match[2]))
         return null;
@@ -227,10 +233,7 @@ export class ResourceLibrary {
                 throw new Error("Resource digest does not match the expected digest");
             const id = `asset-${sha256}`;
             const name = resourceName(options.name ?? sourcePath);
-            const requestedMime = options.mimeType?.split(";", 1)[0].toLowerCase();
-            const mimeType = requestedMime && SAFE_MIME_TYPES.has(requestedMime)
-                ? requestedMime
-                : (MIME_BY_EXTENSION[extname(name).toLowerCase()] ?? "application/octet-stream");
+            const mimeType = resourceMimeType(name, options.mimeType);
             const record = {
                 id,
                 name,

package/dist/panels/resources/references.d.ts

@@ -0,0 +1,48 @@
+import type { MediaReadResult } from "./library.js";
+import type { ExternalResourceReference, ResourceScope } from "./types.js";
+export interface ExternalReferenceOptions {
+    name?: string;
+    mimeType?: string;
+    expectedBytes?: number;
+    expectedLastModified?: number;
+    signal?: AbortSignal;
+    assertAuthorized?: () => void | Promise<void>;
+}
+interface ReferenceOptions {
+    rootDirectory: string;
+    maxFileBytes?: number;
+    isScopeAuthorized(scope: ResourceScope): boolean | Promise<boolean>;
+}
+/** Host-only source locations; public records contain no path and claim no content hash. */
+export declare class ExternalResourceReferences {
+    private readonly options;
+    private closed;
+    private readonly queues;
+    private readonly streams;
+    constructor(options: ReferenceOptions);
+    private authorize;
+    private locked;
+    private directory;
+    private record;
+    private selected;
+    private checked;
+    /** Only call with a directory selected and authorized by the trusted Host. */
+    createFromDirectory(scope: ResourceScope, root: string, path: string, options?: ExternalReferenceOptions): Promise<ExternalResourceReference>;
+    createFromSelectedPath(scope: ResourceScope, path: string, options?: ExternalReferenceOptions): Promise<ExternalResourceReference>;
+    get(scope: ResourceScope, id: string): Promise<ExternalResourceReference>;
+    relinkFromDirectory(scope: ResourceScope, id: string, root: string, path: string, options?: ExternalReferenceOptions): Promise<ExternalResourceReference>;
+    relinkFromSelectedPath(scope: ResourceScope, id: string, path: string, options?: ExternalReferenceOptions): Promise<ExternalResourceReference>;
+    forget(scope: ResourceScope, id: string): Promise<{
+        forgotten: true;
+    }>;
+    openRead(scope: ResourceScope, id: string, options?: {
+        range?: string;
+        method?: string;
+        signal?: AbortSignal;
+    }): Promise<MediaReadResult>;
+    private stopStreams;
+    cancelScope(scope: ResourceScope): Promise<void>;
+    cancelApp(appId: string): Promise<void>;
+    shutdown(): Promise<void>;
+}
+export {};

package/dist/panels/resources/references.js

@@ -0,0 +1,422 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, readdir, realpath, rm } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join } from "node:path";
+import { Readable } from "node:stream";
+import { openResourceDirectory, resourceRelativePath, sameResourceIdentity, } from "./directories.js";
+import { mediaSourceIdentity, rangeBounds, resourceMimeType, resourceName } from "./library.js";
+import { mediaDirectory, mediaScopeKey, readMediaJson, writeMediaJson } from "./storage.js";
+const REFERENCE_ID = /^external-[a-f0-9]{64}$/;
+const MAX_REFERENCES = 4096;
+class ReferenceUnavailable extends Error {
+    state;
+    constructor(state) {
+        super(state === "missing"
+            ? "Referenced file is unavailable; reconnect it"
+            : "Referenced file changed; select it as a new reference");
+        this.state = state;
+    }
+}
+function referenceId(value) {
+    if (typeof value !== "string" || !REFERENCE_ID.test(value))
+        throw new Error("Invalid external reference ID");
+    return value;
+}
+function validIdentity(value) {
+    return value && Number.isSafeInteger(value.dev) && Number.isSafeInteger(value.ino);
+}
+function sameSource(a, b, relocating = false) {
+    return (a.dev === b.dev &&
+        a.ino === b.ino &&
+        a.size === b.size &&
+        a.mtimeMs === b.mtimeMs &&
+        (relocating || a.ctimeMs === b.ctimeMs));
+}
+function view(record, state = "available") {
+    return {
+        id: record.id,
+        kind: "external",
+        name: record.name,
+        mimeType: record.mimeType,
+        bytes: record.source.size,
+        lastModified: Math.trunc(record.source.mtimeMs),
+        createdAt: record.createdAt,
+        state,
+    };
+}
+/** Host-only source locations; public records contain no path and claim no content hash. */
+export class ExternalResourceReferences {
+    options;
+    closed = false;
+    queues = new Map();
+    streams = new Set();
+    constructor(options) {
+        this.options = options;
+    }
+    async authorize(scope, options = {}) {
+        mediaScopeKey(scope);
+        options.signal?.throwIfAborted();
+        if (this.closed || !(await this.options.isScopeAuthorized(scope)))
+            throw new Error("External resource access is no longer authorized");
+        await options.assertAuthorized?.();
+        options.signal?.throwIfAborted();
+    }
+    locked(scope, work) {
+        const key = mediaScopeKey(scope);
+        const next = (this.queues.get(key) ?? Promise.resolve()).catch(() => { }).then(work);
+        this.queues.set(key, next);
+        return next.finally(() => {
+            if (this.queues.get(key) === next)
+                this.queues.delete(key);
+        });
+    }
+    directory(scope, create = false) {
+        return mediaDirectory(this.options.rootDirectory, ["scopes", mediaScopeKey(scope), "references"], create);
+    }
+    async record(scope, id) {
+        referenceId(id);
+        await this.authorize(scope);
+        const raw = await readMediaJson(join(await this.directory(scope), `${id}.json`));
+        if (!raw ||
+            raw.schemaVersion !== 1 ||
+            raw.id !== id ||
+            Object.keys(raw).some((key) => ![
+                "schemaVersion",
+                "id",
+                "name",
+                "mimeType",
+                "createdAt",
+                "root",
+                "path",
+                "ancestors",
+                "source",
+            ].includes(key)) ||
+            typeof raw.name !== "string" ||
+            raw.name !== resourceName(raw.name) ||
+            typeof raw.mimeType !== "string" ||
+            resourceMimeType(raw.name, raw.mimeType) !== raw.mimeType ||
+            !Number.isSafeInteger(raw.createdAt) ||
+            raw.createdAt < 0 ||
+            typeof raw.root !== "string" ||
+            !isAbsolute(raw.root) ||
+            raw.root.length > 4096 ||
+            raw.root.includes("\0") ||
+            !Array.isArray(raw.ancestors) ||
+            raw.ancestors.length < 1 ||
+            raw.ancestors.length > 16 ||
+            raw.ancestors.some((identity) => !validIdentity(identity)) ||
+            !validIdentity(raw.source) ||
+            !Number.isSafeInteger(raw.source.size) ||
+            raw.source.size < 1 ||
+            raw.source.size > (this.options.maxFileBytes ?? 20 * 1024 ** 3) ||
+            !Number.isFinite(raw.source.mtimeMs) ||
+            !Number.isFinite(raw.source.ctimeMs))
+            throw new Error("Invalid stored external reference");
+        resourceRelativePath(raw.path);
+        if (raw.ancestors.length !== raw.path.split("/").length)
+            throw new Error("Invalid external reference ancestry");
+        await this.authorize(scope);
+        return raw;
+    }
+    async selected(scope, root, path, options = {}) {
+        await this.authorize(scope, options);
+        const directory = await openResourceDirectory(root, path, false, () => this.authorize(scope, options));
+        let file;
+        try {
+            file = await open(directory.path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+            const info = await file.stat();
+            const initial = mediaSourceIdentity(info);
+            if (!info.isFile() ||
+                !validIdentity(initial) ||
+                !Number.isSafeInteger(initial.size) ||
+                initial.size < 1 ||
+                initial.size > (this.options.maxFileBytes ?? 20 * 1024 ** 3))
+                throw new Error("External source must be a nonempty regular file within the resource limit");
+            if (options.expectedBytes !== undefined &&
+                (!Number.isSafeInteger(options.expectedBytes) || initial.size !== options.expectedBytes))
+                throw new Error("External source size changed after selection");
+            if (options.expectedLastModified !== undefined &&
+                (!Number.isSafeInteger(options.expectedLastModified) ||
+                    Math.trunc(initial.mtimeMs) !== options.expectedLastModified))
+                throw new Error("External source changed after selection");
+            const verify = async () => {
+                await directory.verify();
+                const named = await lstat(directory.path), held = await file.stat();
+                if (!named.isFile() ||
+                    named.isSymbolicLink() ||
+                    !sameSource(initial, mediaSourceIdentity(named)) ||
+                    !sameSource(initial, mediaSourceIdentity(held)))
+                    throw new ReferenceUnavailable("changed");
+            };
+            await verify();
+            let closing;
+            return {
+                directory,
+                file,
+                initial,
+                verify,
+                close: () => (closing ??= Promise.all([file.close(), directory.close()]).then(() => { })),
+            };
+        }
+        catch (error) {
+            await file?.close().catch(() => { });
+            await directory.close();
+            throw error;
+        }
+    }
+    async checked(scope, record, options = {}) {
+        await this.authorize(scope, options);
+        try {
+            if ((await realpath(record.root)) !== record.root)
+                throw new ReferenceUnavailable("changed");
+            const selected = await this.selected(scope, record.root, record.path, options);
+            if (!sameSource(record.source, selected.initial) ||
+                record.ancestors.length !== selected.directory.identities.length ||
+                record.ancestors.some((identity, index) => !sameResourceIdentity(identity, selected.directory.identities[index]))) {
+                await selected.close();
+                throw new ReferenceUnavailable("changed");
+            }
+            const verify = selected.verify;
+            selected.verify = async () => {
+                if ((await realpath(record.root)) !== record.root)
+                    throw new ReferenceUnavailable("changed");
+                await verify();
+            };
+            return selected;
+        }
+        catch (error) {
+            await this.authorize(scope, options);
+            if (error instanceof ReferenceUnavailable)
+                throw error;
+            const code = error.code;
+            throw new ReferenceUnavailable(["ENOENT", "ENOTDIR", "EACCES", "EPERM"].includes(code ?? "") ? "missing" : "changed");
+        }
+    }
+    /** Only call with a directory selected and authorized by the trusted Host. */
+    createFromDirectory(scope, root, path, options = {}) {
+        return this.locked(scope, async () => {
+            const selected = await this.selected(scope, root, resourceRelativePath(path), options);
+            try {
+                root = selected.directory.rootPath;
+                const id = `external-${createHash("sha256")
+                    .update(JSON.stringify([
+                    "external-reference-v1",
+                    mediaScopeKey(scope),
+                    root,
+                    path,
+                    selected.initial,
+                ]))
+                    .digest("hex")}`;
+                const directory = await this.directory(scope, true), location = join(directory, `${id}.json`);
+                try {
+                    const previous = await this.record(scope, id);
+                    if (previous.root !== root ||
+                        previous.path !== path ||
+                        !sameSource(previous.source, selected.initial))
+                        throw new Error("External reference identity mismatch");
+                    await selected.verify();
+                    return view(previous);
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT")
+                        throw error;
+                }
+                if ((await readdir(directory)).filter((name) => REFERENCE_ID.test(name.replace(/\.json$/, ""))).length >= MAX_REFERENCES)
+                    throw new Error("External reference count limit exceeded");
+                const record = {
+                    schemaVersion: 1,
+                    id,
+                    name: resourceName(options.name ?? basename(path)),
+                    mimeType: resourceMimeType(options.name ?? basename(path), options.mimeType),
+                    createdAt: Date.now(),
+                    root: selected.directory.rootPath,
+                    path,
+                    ancestors: selected.directory.identities,
+                    source: selected.initial,
+                };
+                await selected.verify();
+                await writeMediaJson(location, record);
+                try {
+                    await selected.verify();
+                }
+                catch (error) {
+                    await rm(location, { force: true });
+                    throw error;
+                }
+                return view(record);
+            }
+            finally {
+                await selected.close();
+            }
+        });
+    }
+    createFromSelectedPath(scope, path, options = {}) {
+        if (!isAbsolute(path) || path.includes("\0"))
+            throw new Error("Invalid Host-selected external file");
+        return this.createFromDirectory(scope, dirname(path), basename(path), options);
+    }
+    get(scope, id) {
+        return this.locked(scope, async () => {
+            const record = await this.record(scope, id);
+            try {
+                const source = await this.checked(scope, record);
+                await source.close();
+                return view(record);
+            }
+            catch (error) {
+                if (error instanceof ReferenceUnavailable)
+                    return view(record, error.state);
+                throw error;
+            }
+        });
+    }
+    relinkFromDirectory(scope, id, root, path, options = {}) {
+        return this.locked(scope, async () => {
+            const previous = await this.record(scope, id);
+            const selected = await this.selected(scope, root, resourceRelativePath(path), options);
+            try {
+                // Metadata alone cannot establish that an unrelated replacement is the original file.
+                if (!sameSource(previous.source, selected.initial, true))
+                    throw new Error("This is a different file; create a new external reference instead");
+                const record = {
+                    ...previous,
+                    root: selected.directory.rootPath,
+                    path,
+                    source: selected.initial,
+                    ancestors: selected.directory.identities,
+                };
+                await selected.verify();
+                await this.stopStreams((stream) => stream.scopeKey === mediaScopeKey(scope) && stream.id === id);
+                const location = join(await this.directory(scope), `${id}.json`);
+                await writeMediaJson(location, record);
+                try {
+                    await selected.verify();
+                }
+                catch (error) {
+                    await writeMediaJson(location, previous);
+                    throw error;
+                }
+                return view(record);
+            }
+            finally {
+                await selected.close();
+            }
+        });
+    }
+    relinkFromSelectedPath(scope, id, path, options = {}) {
+        if (!isAbsolute(path) || path.includes("\0"))
+            throw new Error("Invalid Host-selected external file");
+        return this.relinkFromDirectory(scope, id, dirname(path), basename(path), options);
+    }
+    forget(scope, id) {
+        return this.locked(scope, async () => {
+            await this.record(scope, id);
+            await this.stopStreams((stream) => stream.scopeKey === mediaScopeKey(scope) && stream.id === id);
+            await this.authorize(scope);
+            await rm(join(await this.directory(scope), `${id}.json`));
+            return { forgotten: true };
+        });
+    }
+    openRead(scope, id, options = {}) {
+        return this.locked(scope, async () => {
+            const record = await this.record(scope, id);
+            const source = await this.checked(scope, record, options);
+            const method = options.method ?? "GET";
+            if (!["GET", "HEAD"].includes(method)) {
+                await source.close();
+                return { status: 405, headers: { Allow: "GET, HEAD" }, body: null };
+            }
+            const headers = {
+                "Content-Type": record.mimeType,
+                "Accept-Ranges": "bytes",
+                "Cache-Control": "private, no-store",
+                "X-Content-Type-Options": "nosniff",
+                "Content-Security-Policy": "default-src 'none'; sandbox",
+                ETag: `"${record.id}"`,
+            };
+            if (!/^(?:audio|video|image)\//.test(record.mimeType))
+                headers["Content-Disposition"] =
+                    `attachment; filename*=UTF-8''${encodeURIComponent(record.name).replace(/['()*!]/g, (value) => `%${value.charCodeAt(0).toString(16).toUpperCase()}`)}`;
+            const bounds = options.range
+                ? rangeBounds(options.range, record.source.size)
+                : { start: 0, end: record.source.size - 1 };
+            if (!bounds) {
+                await source.close();
+                return {
+                    status: 416,
+                    headers: { ...headers, "Content-Range": `bytes */${record.source.size}` },
+                    body: null,
+                };
+            }
+            headers["Content-Length"] = String(bounds.end - bounds.start + 1);
+            if (options.range)
+                headers["Content-Range"] = `bytes ${bounds.start}-${bounds.end}/${record.source.size}`;
+            const status = options.range ? 206 : 200;
+            if (method === "HEAD") {
+                await source.close();
+                return { status, headers, body: null };
+            }
+            const stream = Readable.from((async function* () {
+                try {
+                    for (let offset = bounds.start; offset <= bounds.end;) {
+                        await source.verify();
+                        const buffer = Buffer.allocUnsafe(Math.min(256 * 1024, bounds.end - offset + 1));
+                        const { bytesRead } = await source.file.read(buffer, 0, buffer.length, offset);
+                        if (bytesRead !== buffer.length)
+                            throw new ReferenceUnavailable("changed");
+                        await source.verify();
+                        offset += bytesRead;
+                        yield buffer;
+                    }
+                }
+                finally {
+                    await source.close();
+                }
+            })(), { objectMode: false });
+            let closed;
+            const entry = {
+                scopeKey: mediaScopeKey(scope),
+                appId: scope.appId,
+                id,
+                stream,
+                closed: new Promise((resolve) => {
+                    closed = resolve;
+                }),
+            };
+            const abort = () => stream.destroy(new Error("External resource read was cancelled"));
+            stream.on("error", () => { });
+            stream.once("close", () => {
+                options.signal?.removeEventListener("abort", abort);
+                void source
+                    .close()
+                    .catch(() => { })
+                    .finally(() => {
+                    this.streams.delete(entry);
+                    closed();
+                });
+            });
+            this.streams.add(entry);
+            options.signal?.addEventListener("abort", abort, { once: true });
+            if (options.signal?.aborted)
+                abort();
+            return { status, headers, body: stream };
+        });
+    }
+    async stopStreams(match) {
+        const streams = [...this.streams].filter(match);
+        for (const entry of streams)
+            entry.stream.destroy(new Error("External resource access was revoked"));
+        await Promise.all(streams.map((entry) => entry.closed));
+    }
+    cancelScope(scope) {
+        return this.stopStreams((stream) => stream.scopeKey === mediaScopeKey(scope));
+    }
+    cancelApp(appId) {
+        return this.stopStreams((stream) => stream.appId === appId);
+    }
+    async shutdown() {
+        this.closed = true;
+        await this.stopStreams(() => true);
+        await Promise.allSettled([...this.queues.values()]);
+    }
+}

package/dist/panels/resources/service.d.ts

@@ -1,5 +1,7 @@
 import { ResourceLibrary } from "./library.js";
-import type { ResourceScope } from "./types.js";
+import { ExternalResourceReferences } from "./references.js";
+import type { MediaReadResult } from "./library.js";
+import type { ExternalResourceReference, ResourceAsset, ResourceScope } from "./types.js";
 export interface PanelResourceServiceOptions {
     rootDirectory: string;
     isScopeAuthorized(scope: ResourceScope): boolean | Promise<boolean>;
@@ -18,6 +20,7 @@ export declare class PanelResourceError extends Error {
 export declare class PanelResourceService {
     private readonly options;
     readonly library: ResourceLibrary;
+    readonly references: ExternalResourceReferences;
     private readonly uploads;
     private readonly directoryIdentities;
     private closed;
@@ -29,10 +32,19 @@ export declare class PanelResourceService {
         materialize: boolean;
         capture: boolean;
         resumableUploads: boolean;
+        externalReferences: boolean;
+        createReferences: boolean;
     };
     initialize(): Promise<void>;
     private authorize;
     private directory;
+    get(scope: ResourceScope, id: string): Promise<ResourceAsset | ExternalResourceReference>;
+    openRead(scope: ResourceScope, id: string, options?: {
+        range?: string;
+        method?: string;
+        signal?: AbortSignal;
+    }): Promise<MediaReadResult>;
+    private reference;
     private materialize;
     private capture;
     private read;

package/dist/panels/resources/service.js

@@ -5,6 +5,7 @@ import { ResourceLibrary, mediaSourceIdentity } from "./library.js";
 import { mediaScopeKey, normalizeMediaScope } from "./storage.js";
 import { openResourceDirectory, resourceRelativePath, sameResourceIdentity, } from "./directories.js";
 import { ResourceUploadIngest } from "./uploads.js";
+import { ExternalResourceReferences } from "./references.js";
 const CHUNK_BYTES = 32768;
 export class PanelResourceError extends Error {
     code;
@@ -28,7 +29,7 @@ function integer(value, min, max) {
     return Number(value);
 }
 function assetId(value) {
-    if (typeof value !== "string" || !/^asset-[a-f0-9]{64}$/.test(value))
+    if (typeof value !== "string" || !/^(?:asset|external)-[a-f0-9]{64}$/.test(value))
         throw new PanelResourceError("INVALID_RESOURCE_REQUEST", "Invalid resource ID");
     return value;
 }
@@ -36,12 +37,14 @@ function assetId(value) {
 export class PanelResourceService {
     options;
     library;
+    references;
     uploads;
     directoryIdentities = new Map();
     closed = false;
     constructor(options) {
         this.options = options;
         this.library = new ResourceLibrary(options);
+        this.references = new ExternalResourceReferences(options);
         this.uploads = new ResourceUploadIngest({ ...options, library: this.library });
     }
     capabilities() {
@@ -52,6 +55,8 @@ export class PanelResourceService {
             materialize: true,
             capture: true,
             resumableUploads: true,
+            externalReferences: true,
+            createReferences: true,
         };
     }
     initialize() {
@@ -90,11 +95,52 @@ export class PanelResourceService {
             throw new Error("Too many resource directory grants; reopen the panel");
         }
         this.directoryIdentities.set(key, { dev: held.rootIdentity.dev, ino: held.rootIdentity.ino });
-        return held;
+        return { ...held, root };
+    }
+    async get(scope, id) {
+        await this.authorize(scope);
+        return assetId(id).startsWith("external-")
+            ? this.references.get(scope, id)
+            : this.library.get(scope, id);
+    }
+    async openRead(scope, id, options = {}) {
+        await this.authorize(scope, options);
+        return assetId(id).startsWith("external-")
+            ? this.references.openRead(scope, id, options)
+            : this.library.openRead(scope, id, options);
+    }
+    async reference(scope, raw, context, relink = false) {
+        const input = object(raw, relink
+            ? ["id", "directoryHandle", "path"]
+            : ["directoryHandle", "path", "name", "mimeType", "expectedBytes", "expectedLastModified"]);
+        if ((input.name !== undefined &&
+            (typeof input.name !== "string" || !input.name || input.name.length > 240)) ||
+            (input.mimeType !== undefined &&
+                (typeof input.mimeType !== "string" || !input.mimeType || input.mimeType.length > 200)))
+            throw new PanelResourceError("INVALID_RESOURCE_REQUEST", "Invalid external reference metadata");
+        const directory = await this.directory(scope, input, context, false);
+        try {
+            const options = {
+                name: input.name,
+                mimeType: input.mimeType,
+                expectedBytes: input.expectedBytes,
+                expectedLastModified: input.expectedLastModified,
+                signal: context.signal,
+                assertAuthorized: directory.verify,
+            };
+            return {
+                reference: relink
+                    ? await this.references.relinkFromDirectory(scope, input.id, directory.root, input.path, options)
+                    : await this.references.createFromDirectory(scope, directory.root, input.path, options),
+            };
+        }
+        finally {
+            await directory.close();
+        }
     }
     async materialize(scope, raw, context) {
         const input = object(raw, ["assetId", "directoryHandle", "path"]);
-        const asset = await this.library.get(scope, assetId(input.assetId));
+        const asset = await this.get(scope, assetId(input.assetId));
         const directory = await this.directory(scope, input, context, true);
         const temporary = directory.location(`.${randomUUID()}.resource-partial`);
         let destination;
@@ -104,7 +150,7 @@ export class PanelResourceService {
             await directory.verify();
             destination = await open(temporary, constants.O_RDWR | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o600);
             identity = await destination.stat();
-            const source = await this.library.openRead(scope, asset.id);
+            const source = await this.openRead(scope, asset.id, { signal: context.signal });
             const hash = createHash("sha256");
             let bytes = 0;
             try {
@@ -126,7 +172,8 @@ export class PanelResourceService {
             finally {
                 source.body?.destroy();
             }
-            if (bytes !== asset.bytes || hash.digest("hex") !== asset.sha256)
+            const sha256 = hash.digest("hex");
+            if (bytes !== asset.bytes || ("sha256" in asset && sha256 !== asset.sha256))
                 throw new Error("Resource content failed integrity validation");
             await destination.sync();
             // A tool may share the granted directory. Verify the actual destination,
@@ -146,7 +193,7 @@ export class PanelResourceService {
             if (verified.size !== asset.bytes ||
                 verified.mtimeMs !== completed.mtimeMs ||
                 verified.ctimeMs !== completed.ctimeMs ||
-                copiedHash.digest("hex") !== asset.sha256)
+                copiedHash.digest("hex") !== sha256)
                 throw new Error("Materialized resource failed integrity verification");
             await destination.close();
             destination = undefined;
@@ -158,7 +205,7 @@ export class PanelResourceService {
             const current = await lstat(directory.path);
             if (!current.isFile() || current.isSymbolicLink() || !sameResourceIdentity(current, identity))
                 throw new Error("Resource output changed during publication");
-            return { assetId: asset.id, path: input.path, bytes: asset.bytes, sha256: asset.sha256 };
+            return { assetId: asset.id, path: input.path, bytes: asset.bytes, sha256 };
         }
         catch (error) {
             if (published && identity) {
@@ -224,14 +271,15 @@ export class PanelResourceService {
     }
     async read(scope, raw, context) {
         const input = object(raw, ["assetId", "offset", "length"]);
-        const asset = await this.library.get(scope, assetId(input.assetId));
+        const asset = await this.get(scope, assetId(input.assetId));
         const offset = integer(input.offset, 0, asset.bytes), length = integer(input.length, 1, CHUNK_BYTES);
         const expected = Math.min(length, asset.bytes - offset);
         const chunks = [];
         let bytes = 0;
         if (expected) {
-            const result = await this.library.openRead(scope, asset.id, {
+            const result = await this.openRead(scope, asset.id, {
                 range: `bytes=${offset}-${offset + expected - 1}`,
+                signal: context.signal,
             });
             try {
                 for await (const chunk of result.body) {
@@ -249,7 +297,7 @@ export class PanelResourceService {
             }
         }
         else
-            await this.library.resolvePath(scope, asset.id);
+            await this.openRead(scope, asset.id, { method: "HEAD", signal: context.signal });
         await this.authorize(scope, context);
         return {
             assetId: asset.id,
@@ -271,7 +319,15 @@ export class PanelResourceService {
                     return { assets: assets.slice(offset, offset + limit), total: assets.length };
                 }
                 case "resources.get":
-                    return { asset: await this.library.get(scope, assetId(object(raw, ["id"]).id)) };
+                    return { asset: await this.get(scope, assetId(object(raw, ["id"]).id)) };
+                case "resources.references.create":
+                    return await this.reference(scope, raw, context);
+                case "resources.references.get":
+                    return { reference: await this.references.get(scope, object(raw, ["id"]).id) };
+                case "resources.references.relink":
+                    return await this.reference(scope, raw, context, true);
+                case "resources.references.forget":
+                    return await this.references.forget(scope, object(raw, ["id"]).id);
                 case "resources.read":
                     return await this.read(scope, raw, context);
                 case "resources.materialize":
@@ -303,14 +359,17 @@ export class PanelResourceService {
     releaseDirectory(scope, handle) {
         this.directoryIdentities.delete(`${mediaScopeKey(scope)}:${handle}`);
     }
-    cancelScope(scope) {
-        return this.uploads.cancelScope(scope);
+    async cancelScope(scope) {
+        await this.references.cancelScope(scope);
+        await this.uploads.cancelScope(scope);
     }
-    cancelApp(appId) {
-        return this.uploads.cancelApp(appId);
+    async cancelApp(appId) {
+        await this.references.cancelApp(appId);
+        await this.uploads.cancelApp(appId);
     }
     async shutdown() {
         this.closed = true;
+        await this.references.shutdown();
         await this.uploads.shutdown();
         this.directoryIdentities.clear();
     }

package/dist/panels/resources/types.d.ts

@@ -12,5 +12,16 @@ export interface ResourceAsset {
     sha256: string;
     createdAt: number;
 }
+/** Mutable external storage is a reference, never an immutable content digest. */
+export interface ExternalResourceReference {
+    id: string;
+    kind: "external";
+    name: string;
+    mimeType: string;
+    bytes: number;
+    lastModified: number;
+    createdAt: number;
+    state: "available" | "missing" | "changed";
+}
 export type MediaScope = ResourceScope;
 export type MediaAsset = ResourceAsset;

package/dist/panels/runtime.js

@@ -681,6 +681,8 @@ export function createPanelRuntime(options) {
                     if ([
                         "resources.materialize",
                         "resources.capture",
+                        "resources.references.create",
+                        "resources.references.relink",
                         "credentials.connections.authorizeProcess",
                     ].includes(method) &&
                         !app.permissions.includes("process"))
@@ -786,7 +788,12 @@ export function createPanelRuntime(options) {
             send: (event, payload) => emit(grant, event, payload),
         };
         if (method.startsWith("resources.")) {
-            if (["resources.materialize", "resources.capture"].includes(method) &&
+            if ([
+                "resources.materialize",
+                "resources.capture",
+                "resources.references.create",
+                "resources.references.relink",
+            ].includes(method) &&
                 !grant.app.permissions.includes("process"))
                 error(403, "资源工具交接需要process权限。");
             return resources.dispatch({ appId: grant.app.id, projectPath: options.bindingCwd ?? options.cwd }, method, params, { resolveDirectory: (handle) => processes.directoryPath(processOwner, handle) });

package/dist/panels/tool-executor.js

@@ -26,7 +26,7 @@ function toolInput(value) {
     for (const resource of input.resources ?? []) {
         if (!resource ||
             Object.keys(resource).some((key) => !["assetId", "path"].includes(key)) ||
-            !/^asset-[a-f0-9]{64}$/.test(resource.assetId))
+            !/^(?:asset|external)-[a-f0-9]{64}$/.test(resource.assetId))
             throw new Error("Invalid tool resource");
         resourceRelativePath(resource.path);
         if (paths.has(resource.path))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cjhyy/code-shell-server",
-  "version": "0.9.13",
+  "version": "0.9.14",
   "description": "CodeShell server transport layer — mobile remote HTTP/WS host, pairing, passcode gate, tunnel, rooms, uploads, and session/attachment services. Electron-free; precursor of the auth gateway.",
   "type": "module",
   "main": "./dist/index.js",
@@ -51,13 +51,13 @@
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\""
   },
   "dependencies": {
-    "@cjhyy/code-shell-capability-coding": "0.9.13",
-    "@cjhyy/code-shell-core": "0.9.13",
-    "@cjhyy/code-shell-web": "0.9.13",
+    "@cjhyy/code-shell-capability-coding": "0.9.14",
+    "@cjhyy/code-shell-core": "0.9.14",
+    "@cjhyy/code-shell-web": "0.9.14",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "@types/ws": "^8.18.1",
     "ws": "^8.21.0",
-    "@cjhyy/code-shell-link": "0.9.13"
+    "@cjhyy/code-shell-link": "0.9.14"
   },
   "engines": {
     "node": ">=20.10"