@cjhyy/code-shell-server 0.9.47 → 0.9.49

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

@@ -11,7 +11,7 @@ export declare const panelBridgeLimits: Readonly<{
     callTimeoutMs: 15000;
     consentTimeoutMs: number;
 }>;
-export type PanelBridgeErrorCode = "PERMISSION_DENIED" | "REVOKED" | "SESSION_CHANGED" | "NOT_SUPPORTED" | "RATE_LIMITED" | "PARAMS_TOO_LARGE" | "RESULT_TOO_LARGE" | "TIMEOUT" | "INVALID_ARGUMENT" | "OPERATION_FAILED";
+export type PanelBridgeErrorCode = "PERMISSION_DENIED" | "REVOKED" | "SESSION_CHANGED" | "NOT_SUPPORTED" | "RATE_LIMITED" | "PARAMS_TOO_LARGE" | "RESULT_TOO_LARGE" | "TIMEOUT" | "INVALID_ARGUMENT" | "OPERATION_FAILED" | "SERVICE_CAPACITY" | "SERVICE_CONFIG_CONFLICT" | "SERVICE_REVISION_CONFLICT" | "SERVICE_REQUEST_KEY_CONFLICT";
 export declare class PanelBridgeError extends Error {
     readonly code: PanelBridgeErrorCode;
     readonly retryAfterMs?: number | undefined;

package/dist/panels/execution-gate.d.ts

@@ -1,6 +1,6 @@
 /** What holds an execution, so a refused change can name it. Host-assigned only. */
 export interface PanelExecutionHolder {
-    kind: "panel-call" | "agent-tool" | "process" | "agent-task" | "tool-job" | "automation";
+    kind: "panel-call" | "agent-tool" | "process" | "agent-task" | "tool-job" | "automation" | "service";
     /** Desktop WebContents id of the Panel instance that owns this execution. */
     guestId?: number;
     /** Trusted Host description, such as a native tool entry name. */
@@ -32,6 +32,12 @@ export declare class PanelExecutionBusyError extends Error {
 export declare class PanelExecutionGate {
     private readonly executions;
     private readonly sources;
+    private readonly settled;
+    private readonly serviceDrains;
+    registerServiceDrain(drain: (matches: (scope: PanelExecutionScope) => boolean) => Promise<void>): () => void;
+    /** Call only after validating the concrete authorized catalog mutation. */
+    drainServices(matches: (scope: PanelExecutionScope) => boolean): Promise<void>;
+    onMutationSettled(listener: () => void): () => void;
     private readonly mutations;
     enter(scope: PanelExecutionScope): () => void;
     run<T>(scope: PanelExecutionScope, work: () => Promise<T>): Promise<T>;
@@ -39,6 +45,8 @@ export declare class PanelExecutionGate {
     register(source: () => Iterable<PanelExecutionScope>): () => void;
     /** Executions that a change matching `matches` would wait for, grouped by holder. */
     blockers(matches: (scope: PanelExecutionScope) => boolean): PanelExecutionBlocker[];
-    mutate<T>(matches: (scope: PanelExecutionScope) => boolean, work: () => Promise<T>): Promise<T>;
+    mutate<T>(matches: (scope: PanelExecutionScope) => boolean, work: () => Promise<T>, 
+    /** Trusted Host preparation that validates a review before draining existing work. */
+    drain?: () => Promise<void>): Promise<T>;
 }
 export declare const panelExecutionGate: PanelExecutionGate;

package/dist/panels/execution-gate.js

@@ -27,6 +27,24 @@ export class PanelExecutionBusyError extends Error {
 export class PanelExecutionGate {
     executions = new Set();
     sources = new Set();
+    settled = new Set();
+    serviceDrains = new Set();
+    registerServiceDrain(drain) {
+        this.serviceDrains.add(drain);
+        return () => {
+            this.serviceDrains.delete(drain);
+        };
+    }
+    /** Call only after validating the concrete authorized catalog mutation. */
+    async drainServices(matches) {
+        await Promise.all([...this.serviceDrains].map((drain) => drain(matches)));
+    }
+    onMutationSettled(listener) {
+        this.settled.add(listener);
+        return () => {
+            this.settled.delete(listener);
+        };
+    }
     mutations = new Set();
     enter(scope) {
         const held = {
@@ -77,19 +95,35 @@ export class PanelExecutionGate {
         }
         return [...grouped.values()];
     }
-    async mutate(matches, work) {
+    async mutate(matches, work, 
+    /** Trusted Host preparation that validates a review before draining existing work. */
+    drain) {
         if (this.mutations.size)
             throw new PanelExecutionBusyError("另一个面板修改正在进行，请稍后重试。");
         // No await between the snapshot and installing the admission barrier.
         const blockers = this.blockers(matches);
-        if (blockers.length)
+        if (blockers.length && !drain)
             throw new PanelExecutionBusyError("面板还有正在提交、排队或运行的任务，请结束后再修改。", blockers);
         this.mutations.add(matches);
         try {
+            if (drain) {
+                await drain();
+                const remaining = this.blockers(matches);
+                if (remaining.length)
+                    throw new PanelExecutionBusyError("面板还有正在提交、排队或运行的任务，请结束后再修改。", remaining);
+            }
             return await work();
         }
         finally {
             this.mutations.delete(matches);
+            for (const listener of this.settled) {
+                try {
+                    listener();
+                }
+                catch {
+                    /* observer */
+                }
+            }
         }
     }
 }

package/dist/panels/http.d.ts

@@ -39,6 +39,7 @@ export declare function createPanelHttp(options: PanelManagementHttpOptions & {
         install(context: import("./types.js").PanelOperationContext, token: unknown, bind?: boolean, approval?: {
             overwrite?: boolean;
             expectedId?: string;
+            releaseExecutions?: (appId: string, matches: (scope: import("./execution-gate.js").PanelExecutionScope) => boolean) => Promise<void>;
         }): Promise<{
             id: string;
             packageDigest: string | undefined;

package/dist/panels/management-http.d.ts

@@ -30,6 +30,7 @@ export declare function createPanelManagementHttp(options: PanelManagementHttpOp
         install(context: PanelOperationContext, token: unknown, bind?: boolean, approval?: {
             overwrite?: boolean;
             expectedId?: string;
+            releaseExecutions?: (appId: string, matches: (scope: import("./execution-gate.js").PanelExecutionScope) => boolean) => Promise<void>;
         }): Promise<{
             id: string;
             packageDigest: string | undefined;

package/dist/panels/management.d.ts

@@ -1,3 +1,4 @@
+import { type PanelExecutionScope } from "./execution-gate.js";
 import { type PanelAppPreview, type PanelAppSourceInput } from "@cjhyy/code-shell-core";
 import type { PanelCompatibility, PanelDiscovery, PanelOperationContext, PanelReview, PanelProjectReview, PanelSnapshot, PanelPackageHistory, PanelPackageRestoreReview } from "./types.js";
 export declare class PanelManagementError extends Error {
@@ -50,6 +51,8 @@ export declare function createPanelManagement(options: PanelManagementOptions):
     install(context: PanelOperationContext, token: unknown, bind?: boolean, approval?: {
         overwrite?: boolean;
         expectedId?: string;
+        /** Trusted Host callback, never supplied by an HTTP request body. */
+        releaseExecutions?: (appId: string, matches: (scope: PanelExecutionScope) => boolean) => Promise<void>;
     }): Promise<{
         id: string;
         packageDigest: string | undefined;

package/dist/panels/management.js

@@ -3,7 +3,7 @@ import { panelPackageMutationMatches } from "./package-mutation.js";
 import { createHash, randomBytes } from "node:crypto";
 import { lstatSync, mkdirSync, statSync } from "node:fs";
 import { basename, extname, isAbsolute, join, resolve } from "node:path";
-import { SettingsManager, PanelAppAlreadyInstalledError, PanelAppInstallError, PanelAppReviewChangedError, assertSafePanelAppId, discoverGitPanelApps, installReviewedLocalPanelApp, invalidateSkillCache, listInstalledPanelApps, inspectProjectPanelApps, listRetainedPanelAppPackages, resolvePanelAppPackage, parsePanelAppPackagePins, retainInstalledPanelApp, userHome, panelAppsRoot, previewLocalPanelApp, resolveGitHubPanelAppCommit, resolvePanelAppBindingPolicy, uninstallPanelApp, } from "@cjhyy/code-shell-core";
+import { SettingsManager, PanelAppAlreadyInstalledError, PanelAppInstallError, PanelAppReviewChangedError, assertSafePanelAppId, discoverGitPanelApps, installReviewedLocalPanelApp, invalidateSkillCache, listInstalledPanelApps, inspectProjectPanelApps, listRetainedPanelAppPackages, resolvePanelAppPackage, parsePanelAppPackagePins, currentPanelAppPackagePins, installedPanelAppUpdatedAt, retainInstalledPanelApp, userHome, panelAppsRoot, previewLocalPanelApp, resolveGitHubPanelAppCommit, resolvePanelAppBindingPolicy, uninstallPanelApp, } from "@cjhyy/code-shell-core";
 import { mutateJsonFile } from "@cjhyy/code-shell-core/internal";
 import { parseGithubUrl } from "@cjhyy/code-shell-core/internal/skills";
 const REVIEW_TTL = 8 * 60_000;
@@ -177,14 +177,17 @@ export function createPanelManagement(options) {
             .update(JSON.stringify({
             app,
             digest,
-            ...(options.projectPackages
-                ? { pin: parsePanelAppPackagePins(project ?? projectSettings())[app.id] ?? null }
-                : {}),
+            ...(options.projectPackages ? { pin: selectedPin(app.id, project) } : {}),
             bound: current.boundApps.has(app.id),
             disabled: current.globalDisabledApps.has(app.id),
         }))
             .digest("hex");
     }
+    /** The pinned package identity; when it was pinned does not change the selection. */
+    function selectedPin(id, project) {
+        const pin = parsePanelAppPackagePins(project ?? projectSettings())[id];
+        return pin ? { version: pin.version, packageDigest: pin.packageDigest } : null;
+    }
     function projectSettings() {
         return new SettingsManager(workspace, "full").getRawForScope("project", workspace, {
             strict: true,
@@ -291,7 +294,7 @@ export function createPanelManagement(options) {
         // Never attach a new revision to stale displayed binding state. File and
         // package inspection above can yield to another device's mutation.
         for (const app of [...panels, ...issues]) {
-            const pin = options.projectPackages ? parsePanelAppPackagePins(project)[app.id] : undefined;
+            const pin = options.projectPackages ? currentPanelAppPackagePins(project)[app.id] : undefined;
             if (projectState(app.id, project) !== projectState(app.id) ||
                 current.globalDisabledApps.has(app.id) !== policy().globalDisabledApps.has(app.id) ||
                 (pin && (pin.packageDigest !== app.packageDigest || pin.version !== app.version)))
@@ -484,7 +487,7 @@ export function createPanelManagement(options) {
             return value;
         });
     }
-    async function mutate(context, change, work) {
+    async function mutate(context, change, work, prepare) {
         const expected = generation(context.ownerId);
         const guard = () => assertAuthorized(context, expected);
         const run = async () => {
@@ -493,12 +496,23 @@ export function createPanelManagement(options) {
                 await guard();
                 return work(guard);
             };
-            return panelExecutionGate.mutate(panelPackageMutationMatches({ ...change, projectPath: options.bindingCwd ?? options.cwd }), () => (options.withMutation ? options.withMutation(write) : write()));
+            const matches = panelPackageMutationMatches({
+                ...change,
+                projectPath: options.bindingCwd ?? options.cwd,
+            });
+            return panelExecutionGate.mutate(matches, () => (options.withMutation ? options.withMutation(write) : write()), prepare ? () => prepare(guard, matches) : undefined);
         };
         const next = catalogMutation.then(run, run);
         catalogMutation = next.catch(() => undefined);
         return next;
     }
+    async function drainSelectedServices(id, expected, guard, matches) {
+        const current = await selectedApp(id);
+        if (revision(current.app, current.digest) !== expected)
+            throw new PanelManagementError(409, "conflict", "面板已改变，请刷新后重试。");
+        await guard();
+        await panelExecutionGate.drainServices(matches);
+    }
     function setBinding(app, bound, expected) {
         options.assertBinding?.();
         if (!hasProject)
@@ -524,7 +538,20 @@ export function createPanelManagement(options) {
                 if (bound) {
                     if (!app.packageDigest)
                         throw new Error("Cannot bind an unverified Panel package");
-                    pins[app.id] = { version: app.version, packageDigest: app.packageDigest };
+                    const existing = pins[app.id];
+                    // Rebinding the package a current pin already selects changes nothing, so
+                    // it must not invalidate other devices' revisions or pending reviews.
+                    const unchanged = existing?.version === app.version &&
+                        existing.packageDigest === app.packageDigest &&
+                        !!currentPanelAppPackagePins({ panelAppPins: { [app.id]: existing } })[app.id];
+                    if (!unchanged)
+                        pins[app.id] = {
+                            version: app.version,
+                            packageDigest: app.packageDigest,
+                            // Holds this project only until the next global install or update, so it
+                            // must be strictly later than the install it was chosen after.
+                            pinnedAt: new Date(Math.max(now(), (installedPanelAppUpdatedAt(app.id) ?? 0) + 1)).toISOString(),
+                        };
                 }
                 else
                     delete pins[app.id];
@@ -638,10 +665,15 @@ export function createPanelManagement(options) {
                 throw new PanelManagementError(403, "review_owner", "请在当前设备重新审阅这个版本。");
             await assertAuthorized(context, held.generation);
             const review = held.public;
-            return mutate(context, { appId: review.appId, kind: "binding" }, async (guard) => {
-                await assertAuthorized(context, held.generation);
+            const assertReviewLease = () => {
+                if (closed || generation(context.ownerId) !== held.generation)
+                    throw new PanelManagementError(401, "login_required", "登录已失效，请重新登录。");
                 if (restores.get(token) !== held || held.public.expiresAt <= now())
                     throw new PanelManagementError(409, "review_expired", "版本审阅已失效，请重新选择。");
+            };
+            const validateReview = async (guard) => {
+                await assertAuthorized(context, held.generation);
+                assertReviewLease();
                 const current = await restorationSelection(review.appId);
                 if (current.revision !== review.expectedRevision)
                     throw new PanelManagementError(409, "conflict", "项目面板已改变，请重新审阅。");
@@ -650,12 +682,25 @@ export function createPanelManagement(options) {
                     throw new PanelManagementError(400, "unsupported", "这个版本无法在当前环境使用。");
                 await guard();
                 await assertAuthorized(context, held.generation);
-                if (restores.get(token) !== held || held.public.expiresAt <= now())
-                    throw new PanelManagementError(409, "review_expired", "版本审阅已失效，请重新选择。");
+                assertReviewLease();
+                if (projectState(review.appId) !== held.projectState)
+                    throw new PanelManagementError(409, "conflict", "项目面板配置已改变，请重新审阅。");
+                return target;
+            };
+            return mutate(context, { appId: review.appId, kind: "binding" }, async (guard) => {
+                const target = await validateReview(guard);
+                assertReviewLease();
                 setBinding(target, true, { projectState: held.projectState });
                 restores.delete(token);
                 await options.onChanged?.(review.appId, "binding");
                 return { id: review.appId, packageDigest: review.packageDigest };
+            }, async (guard, matches) => {
+                // A reviewed version selection changes the executor's package just like
+                // unbinding. Validate authority and exact retained bytes before drain,
+                // then revalidate them before writing. Other executions still block.
+                await validateReview(guard);
+                assertReviewLease();
+                await panelExecutionGate.drainServices(matches);
             });
         },
         assertAuthorized,
@@ -735,12 +780,20 @@ export function createPanelManagement(options) {
             await assertAuthorized(context, held.generation);
             if (approval?.expectedId && approval.expectedId !== held.public.preview.id)
                 invalid();
+            if (approval?.releaseExecutions && held.public.kind !== "update")
+                invalid();
             if (approval && held.public.kind === "update" && !approval.overwrite)
                 throw new PanelManagementError(409, "already_installed", "这个面板已经安装，请确认项目更新。");
-            return mutate(context, { appId: held.public.preview.id, kind: held.public.kind }, async (guard) => {
-                await assertAuthorized(context, held.generation);
-                if (reviews.get(token) !== held || held.public.expiresAt <= now())
+            let admitted = false;
+            const assertReviewLease = () => {
+                if (closed || generation(context.ownerId) !== held.generation)
+                    throw new PanelManagementError(401, "login_required", "登录已失效，请重新登录。");
+                if (!admitted && (reviews.get(token) !== held || held.public.expiresAt <= now()))
                     throw new PanelManagementError(409, "review_expired", "预览已失效，请重新检查来源。");
+            };
+            const validateReview = async (guard) => {
+                await assertAuthorized(context, held.generation);
+                assertReviewLease();
                 const id = held.public.preview.id;
                 if (held.public.kind === "update") {
                     const current = await selectedApp(id);
@@ -753,6 +806,12 @@ export function createPanelManagement(options) {
                 if (projectState(id) !== held.projectState)
                     throw new PanelManagementError(409, "conflict", "项目面板配置已改变，请重新预览。");
                 await guard();
+                assertReviewLease();
+            };
+            return mutate(context, { appId: held.public.preview.id, kind: held.public.kind }, async (guard) => {
+                await validateReview(guard);
+                assertReviewLease();
+                const id = held.public.preview.id;
                 const installed = await installReviewedLocalPanelApp(held.source, held.digest, new Date(now()).toISOString(), {
                     overwrite: held.public.kind === "update",
                     expectedId: id,
@@ -767,6 +826,7 @@ export function createPanelManagement(options) {
                         if (projectState(id) !== held.projectState)
                             throw new PanelManagementError(409, "conflict", "项目面板配置已改变，请重新预览。");
                         await guard();
+                        assertReviewLease();
                     },
                 });
                 reviews.delete(token);
@@ -782,7 +842,31 @@ export function createPanelManagement(options) {
                 invalidateSkillCache();
                 await options.onChanged?.(id, held.public.kind);
                 return { id, packageDigest: installed.packageDigest };
-            });
+            }, held.public.kind === "update"
+                ? async (guard, matches) => {
+                    await validateReview(guard);
+                    // A local directory/ZIP may have changed since preview. Check its
+                    // reviewed bytes before cancelling work, then recheck mutable
+                    // project/catalog authority after the source read.
+                    const preview = await previewLocalPanelApp(held.source);
+                    if (preview.id !== held.public.preview.id || preview.reviewToken !== held.digest)
+                        throw new PanelManagementError(409, "conflict", "来源已改变，请重新检查更新。");
+                    await validateReview(guard);
+                    assertReviewLease();
+                    if (approval?.releaseExecutions) {
+                        // Force owns the review while its holders exit. TTL expiry during
+                        // cancellation must not invalidate consent; revocation is checked.
+                        admitted = true;
+                        reviews.delete(token);
+                        await approval.releaseExecutions(held.public.preview.id, matches);
+                    }
+                    else {
+                        // Ordinary updates drain only services. Other executions still
+                        // block, and failed publication must leave this review retryable.
+                        await panelExecutionGate.drainServices(matches);
+                    }
+                }
+                : undefined);
         },
         async binding(context, id, bound, expected) {
             assertId(id);
@@ -793,18 +877,18 @@ export function createPanelManagement(options) {
                 const current = await selectedApp(id);
                 if (bound && !compatibility(current.app).supported)
                     throw new PanelManagementError(400, "unsupported", "这个面板需要当前 Web 环境未提供的能力。");
-                // Legacy installs need a retained copy before the project can pin them.
-                // An already pinned project must keep its selected version, not the catalog's.
+                // An unpinned (or superseded) selection needs a retained copy before the
+                // project can pin it. A current pin must keep its selected version.
                 const app = bound &&
                     options.projectPackages &&
-                    !parsePanelAppPackagePins(projectSettings())[current.app.id]
+                    !currentPanelAppPackagePins(projectSettings())[current.app.id]
                     ? await retainInstalledPanelApp(current.app.id, current.app.packageDigest)
                     : current.app;
                 await guard();
                 setBinding(app, bound, { ...current, revision: expected });
                 await options.onChanged?.(id, "binding");
                 return snapshot();
-            });
+            }, (guard, matches) => drainSelectedServices(id, expected, guard, matches));
         },
         async remove(context, id, expected) {
             assertId(id);
@@ -830,7 +914,7 @@ export function createPanelManagement(options) {
                 invalidateSkillCache();
                 await options.onChanged?.(id, "remove");
                 return { removed: true };
-            });
+            }, (guard, matches) => drainSelectedServices(id, expected, guard, matches));
         },
         cancelOwner(owner) {
             generations.set(owner, generation(owner) + 1);

package/dist/panels/package-mutation.d.ts

@@ -4,5 +4,5 @@ export interface PanelPackageMutation {
     projectPath: string;
     kind: "install" | "update" | "binding" | "remove";
 }
-/** Pinned projects retain their bytes when a different project updates the catalog. */
+/** A catalog install or update supersedes every project's pin, so it reaches every project. */
 export declare function panelPackageMutationMatches(change: PanelPackageMutation): (scope: PanelExecutionScope) => boolean;

package/dist/panels/package-mutation.js

@@ -1,6 +1,6 @@
-import { projectPanelAppPackagePins, resolvePanelAppBindingProjectPath, } from "@cjhyy/code-shell-core";
+import { resolvePanelAppBindingProjectPath } from "@cjhyy/code-shell-core";
 import { panelExecutionProject } from "./execution-gate.js";
-/** Pinned projects retain their bytes when a different project updates the catalog. */
+/** A catalog install or update supersedes every project's pin, so it reaches every project. */
 export function panelPackageMutationMatches(change) {
     const project = panelExecutionProject(resolvePanelAppBindingProjectPath(change.projectPath));
     return (scope) => {
@@ -11,13 +11,6 @@ export function panelPackageMutationMatches(change) {
         const bindingProject = resolvePanelAppBindingProjectPath(scope.projectPath);
         if (panelExecutionProject(bindingProject) === project)
             return true;
-        if (change.kind === "binding")
-            return false;
-        try {
-            return !projectPanelAppPackagePins(bindingProject, change.appId)[change.appId];
-        }
-        catch {
-            return true;
-        } // An unreadable project cannot prove that it is insulated.
+        return change.kind !== "binding";
     };
 }

package/dist/panels/process-files.js

@@ -3,6 +3,7 @@ import { lstat, open, opendir, realpath } from "node:fs/promises";
 import { extname, isAbsolute, join, resolve } from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
+import { rangeBounds } from "../http-byte-range.js";
 const MAX_DOWNLOAD_BYTES = 2 * 1024 * 1024 * 1024;
 const MAX_ENTRIES = 200;
 const MAX_EXAMINED = 4096;
@@ -227,20 +228,44 @@ export async function handlePanelProcessDirectory(request, response, options) {
             fail(404, "下载文件已经改变。");
         await verifyDirectory();
         await authorize();
-        response.writeHead(200, {
+        // Directory outputs are mutable and have no stable representation validator.
+        // An If-Range condition cannot be confirmed, so return the complete file.
+        const range = request.headers["if-range"] === undefined ? request.headers.range : undefined;
+        const bounds = range === undefined
+            ? { start: 0, end: metadata.size - 1 }
+            : metadata.size > 0
+                ? rangeBounds(range, metadata.size)
+                : null;
+        const headers = {
             "Content-Type": "application/octet-stream",
             "Content-Disposition": disposition(name),
-            "Content-Length": metadata.size,
+            "Accept-Ranges": "bytes",
             "Content-Security-Policy": "default-src 'none'; sandbox",
             "Cache-Control": "no-store",
             "X-Content-Type-Options": "nosniff",
             "Referrer-Policy": "no-referrer",
+        };
+        if (!bounds) {
+            response.writeHead(416, {
+                ...headers,
+                "Content-Range": `bytes */${metadata.size}`,
+                "Content-Length": 0,
+            });
+            response.end();
+            return;
+        }
+        response.writeHead(range === undefined ? 200 : 206, {
+            ...headers,
+            "Content-Length": bounds.end - bounds.start + 1,
+            ...(range === undefined
+                ? {}
+                : { "Content-Range": `bytes ${bounds.start}-${bounds.end}/${metadata.size}` }),
         });
         if (request.method === "HEAD" || metadata.size === 0) {
             response.end();
             return;
         }
-        const input = file.createReadStream({ autoClose: false, start: 0, end: metadata.size - 1 });
+        const input = file.createReadStream({ autoClose: false, ...bounds });
         let checking = false;
         const timer = setInterval(() => {
             if (checking)

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 { rangeBounds } from "../../http-byte-range.js";
 export declare function resourceMimeType(name: string, requested?: string): string;
 export interface MediaLibraryOptions {
     rootDirectory: string;
@@ -33,10 +34,6 @@ 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

@@ -3,6 +3,8 @@ import { constants } from "node:fs";
 import { lstat, mkdir, open, readdir, rename, rm } from "node:fs/promises";
 import { basename, extname, join } from "node:path";
 import { mediaDirectory, mediaScopeKey, readMediaJson, writeMediaJson } from "./storage.js";
+import { rangeBounds } from "../../http-byte-range.js";
+export { rangeBounds } from "../../http-byte-range.js";
 const ASSET_ID = /^asset-[a-f0-9]{64}$/;
 const MIME_BY_EXTENSION = {
     ".mp4": "video/mp4",
@@ -93,24 +95,6 @@ function assetRecord(raw, id) {
         createdAt: value.createdAt,
     };
 }
-export function rangeBounds(range, size) {
-    const match = /^bytes=(\d*)-(\d*)$/.exec(range);
-    if (!match || (!match[1] && !match[2]))
-        return null;
-    const first = match[1] ? Number(match[1]) : undefined;
-    const last = match[2] ? Number(match[2]) : undefined;
-    if ((first !== undefined && !Number.isSafeInteger(first)) ||
-        (last !== undefined && !Number.isSafeInteger(last)))
-        return null;
-    if (first === undefined) {
-        if (!last || last <= 0)
-            return null;
-        return { start: Math.max(0, size - last), end: size - 1 };
-    }
-    if (first >= size || (last !== undefined && last < first))
-        return null;
-    return { start: first, end: Math.min(last ?? size - 1, size - 1) };
-}
 /**
  * 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/references.js

@@ -25,12 +25,11 @@ function referenceId(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));
+// Like other editors, recognize an original by file, size and modification time.
+// ctime is not identity: macOS changes it for tags, "last opened" and other
+// extended attributes, which would otherwise turn unchanged originals "changed".
+function sameSource(a, b) {
+    return a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeMs === b.mtimeMs;
 }
 function view(record, state = "available") {
     return {
@@ -221,7 +220,21 @@ export class ExternalResourceReferences {
                     if (error.code !== "ENOENT")
                         throw error;
                 }
-                if ((await readdir(directory)).filter((name) => REFERENCE_ID.test(name.replace(/\.json$/, ""))).length >= MAX_REFERENCES)
+                const names = (await readdir(directory)).filter((name) => REFERENCE_ID.test(name.replace(/\.json$/, "")));
+                // IDs include the ctime seen at creation. Choosing the same unchanged
+                // original again must return its reference, not a duplicate asset.
+                for (const name of names) {
+                    const existing = await this.record(scope, name.replace(/\.json$/, "")).catch(() => undefined);
+                    if (existing?.root === root &&
+                        existing.path === path &&
+                        sameSource(existing.source, selected.initial) &&
+                        existing.ancestors.length === selected.directory.identities.length &&
+                        existing.ancestors.every((identity, index) => sameResourceIdentity(identity, selected.directory.identities[index]))) {
+                        await selected.verify();
+                        return view(existing);
+                    }
+                }
+                if (names.length >= MAX_REFERENCES)
                     throw new Error("External reference count limit exceeded");
                 const record = {
                     schemaVersion: 1,
@@ -302,7 +315,7 @@ export class ExternalResourceReferences {
             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))
+                if (!sameSource(previous.source, selected.initial))
                     throw new Error("This is a different file; create a new external reference instead");
                 const record = {
                     ...previous,

package/dist/panels/runtime.js

@@ -349,7 +349,7 @@ function bridgeScript(id, origin) {
         call: ask,
         callResult: (method, params) => ask(method, params).then(value => ({ ok: true, value }), error => ({ ok: false, error: { code: error.code || "OPERATION_FAILED", message: error.message, ...(typeof error.retryAfterMs === "number" ? { retryAfterMs: error.retryAfterMs } : {}) } })),
         on: (name, listener) => {
-          if (!["context.changed", "process.output", "process.exit", "agent.task.changed", "tasks.changed", "media.job.changed"].includes(name) || typeof listener !== "function") {
+          if (!["context.changed", "process.output", "process.exit", "agent.task.changed", "tasks.changed", "services.changed", "media.job.changed"].includes(name) || typeof listener !== "function") {
             throw new Error("Invalid event listener");
           }
           let list = listeners.get(name);

package/dist/panels/tool-jobs.d.ts

@@ -47,6 +47,8 @@ export interface ToolJobProgress {
 export type ToolJobStatus = "queued" | "running" | "cancelling" | "succeeded" | "failed" | "cancelled" | "interrupted";
 export interface ToolJob {
     id: string;
+    /** Caller-owned idempotency identity, returned with its authorized receipt. */
+    requestKey?: string;
     scope: ToolJobScope;
     entry: ToolJobEntry;
     package?: ToolJobPackage;

package/dist/panels/tool-jobs.js

@@ -100,7 +100,7 @@ function progressValue(progress) {
     }, toolJobLimits.maxProgressBytes);
 }
 function publicJob(job) {
-    const { version: _version, requestKey: _requestKey, requestDigest: _requestDigest, ...value } = job;
+    const { version: _version, requestDigest: _requestDigest, ...value } = job;
     return toolJobJson(value, toolJobLimits.maxRecordBytes);
 }
 function packageValue(value) {