@cjhyy/code-shell-server 0.9.22 → 0.9.23

package/dist/panels/tool-executor.js

@@ -1,9 +1,23 @@
 import { createHash } from "node:crypto";
-import { mkdir, lstat, realpath } from "node:fs/promises";
+import { mkdir, mkdtemp, lstat, realpath, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { processLimits } from "./process-state.js";
 import { resourceRelativePath } from "./resources/directories.js";
 import { materializePanelConnections, panelConnectionIds } from "./connections.js";
+import { taskCookieSelection, } from "./task-cookies.js";
+function directReads(input) {
+    return (input.resources ?? []).filter((resource) => resource.access === "read");
+}
+function originalUnavailable(state, during = false) {
+    return state === "missing"
+        ? Object.assign(new Error("A read-only original is unavailable; reconnect it and retry"), {
+            code: "INPUT_MISSING",
+            retryable: true,
+        })
+        : Object.assign(new Error(during
+            ? "A read-only original changed while the tool ran; check it before running again"
+            : "A read-only original changed; select it again"), { code: "INPUT_CHANGED", retryable: false });
+}
 function toolInput(value) {
     if (!value ||
         typeof value !== "object" ||
@@ -14,6 +28,8 @@ function toolInput(value) {
             "directoryArguments",
             "connectionIds",
             "connectionArgument",
+            "originalsArgument",
+            "cookieArgument",
         ].includes(key)))
         throw new Error("Invalid tool job input");
     const input = value;
@@ -25,8 +41,11 @@ function toolInput(value) {
     const paths = new Set();
     for (const resource of input.resources ?? []) {
         if (!resource ||
-            Object.keys(resource).some((key) => !["assetId", "path"].includes(key)) ||
-            !/^(?:asset|external)-[a-f0-9]{64}$/.test(resource.assetId))
+            Object.keys(resource).some((key) => !["assetId", "path", "access"].includes(key)) ||
+            !/^(?:asset|external)-[a-f0-9]{64}$/.test(resource.assetId) ||
+            (resource.access !== undefined && !["copy", "read"].includes(resource.access)) ||
+            // Library assets are Host custody; only a user-selected original may be read in place.
+            (resource.access === "read" && !resource.assetId.startsWith("external-")))
             throw new Error("Invalid tool resource");
         resourceRelativePath(resource.path);
         if (paths.has(resource.path))
@@ -40,9 +59,13 @@ function toolInput(value) {
     for (const item of input.directoryArguments ?? []) {
         if (!item ||
             !/^--[a-z][a-z0-9-]{0,63}$/.test(item.argumentName) ||
-            !["job", "app-data"].includes(item.directory) ||
-            Object.keys(item).some((key) => !["argumentName", "directory", "path"].includes(key)))
+            !["job", "app-data", "bookmark"].includes(item.directory) ||
+            Object.keys(item).some((key) => !["argumentName", "directory", "path", "bookmark"].includes(key)))
             throw new Error("Invalid tool directory argument");
+        if (item.directory === "bookmark"
+            ? typeof item.bookmark !== "string" || !/^[a-f0-9-]{36}$/i.test(item.bookmark)
+            : item.bookmark !== undefined)
+            throw new Error("Invalid tool directory bookmark");
         if (argumentsSeen.has(item.argumentName))
             throw new Error("Duplicate tool argument");
         argumentsSeen.add(item.argumentName);
@@ -55,9 +78,31 @@ function toolInput(value) {
             !/^--[a-z][a-z0-9-]{0,63}$/.test(input.connectionArgument) ||
             argumentsSeen.has(input.connectionArgument))
             throw new Error("Invalid connection argument");
+        argumentsSeen.add(input.connectionArgument);
     }
     else if (input.connectionArgument !== undefined)
         throw new Error("Connection selection is required");
+    if (directReads(input).length) {
+        if (!input.originalsArgument ||
+            !/^--[a-z][a-z0-9-]{0,63}$/.test(input.originalsArgument) ||
+            argumentsSeen.has(input.originalsArgument))
+            throw new Error("Invalid originals argument");
+        argumentsSeen.add(input.originalsArgument);
+    }
+    else if (input.originalsArgument !== undefined)
+        throw new Error("Invalid originals argument: no resource uses read access");
+    if (input.cookieArgument !== undefined) {
+        const value = input.cookieArgument;
+        if (!value ||
+            typeof value !== "object" ||
+            Array.isArray(value) ||
+            typeof value.argumentName !== "string" ||
+            !/^--[a-z][a-z0-9-]{0,63}$/.test(value.argumentName) ||
+            argumentsSeen.has(value.argumentName))
+            throw new Error("Invalid Cookie argument");
+        const { argumentName: _argumentName, ...selection } = value;
+        taskCookieSelection(selection);
+    }
     return input;
 }
 async function childDirectory(root, relative) {
@@ -76,32 +121,77 @@ async function childDirectory(root, relative) {
 }
 /** The only background processor: launch a reviewed tool and transport bounded JSON/files. */
 export function createPanelToolExecutor(options) {
+    const bookmarkDirectory = async (scope, bookmark) => {
+        if (!options.resolveDirectoryBookmark)
+            throw new Error("This Host does not support task directory bookmarks");
+        return options.resolveDirectoryBookmark(scope, bookmark);
+    };
+    const authorize = async (scope, input) => {
+        await options.authorize(scope);
+        await authorizeDirectRead(scope, input);
+        for (const directory of input.directoryArguments ?? [])
+            if (directory.directory === "bookmark")
+                await bookmarkDirectory(scope, directory.bookmark);
+        if (input.cookieArgument) {
+            if (!options.cookies)
+                throw new Error("This Host does not support task Cookie authorization");
+            const { argumentName: _argumentName, ...selection } = input.cookieArgument;
+            await options.cookies.check(scope, selection);
+        }
+    };
+    const authorizeDirectRead = async (scope, input) => {
+        if (!directReads(input).length)
+            return;
+        if (!options.authorizeDirectRead)
+            throw new Error("This host cannot hand originals to tools; copy the resource instead");
+        await options.authorizeDirectRead(scope);
+    };
+    const materialize = async (scope, resources, workDir, signal) => {
+        const handle = createHash("sha256").update(workDir).digest("hex");
+        try {
+            for (const { assetId, path } of resources) {
+                await options.resources.dispatch(scope, "resources.materialize", { assetId, path, directoryHandle: handle }, {
+                    signal,
+                    resolveDirectory: async () => {
+                        await options.authorize(scope);
+                        return workDir;
+                    },
+                });
+            }
+        }
+        finally {
+            options.resources.releaseDirectory(scope, handle);
+        }
+    };
+    /** Verify each original now; keys are the Guest's names, paths never leave the Host. */
+    const verifiedOriginals = async (scope, input, signal) => {
+        const originals = Object.create(null);
+        for (const resource of directReads(input)) {
+            const reference = await options.resources.references.get(scope, resource.assetId);
+            if (reference.state !== "available")
+                throw originalUnavailable(reference.state);
+            originals[resource.path] = {
+                path: await options.resources.references.location(scope, resource.assetId, { signal }),
+                bytes: reference.bytes,
+            };
+        }
+        return originals;
+    };
     return {
         async prepareInput(scope, raw, workDir, signal) {
             const input = toolInput(raw);
-            await options.authorize(scope);
-            const handle = createHash("sha256").update(workDir).digest("hex");
-            try {
-                for (const resource of input.resources ?? []) {
-                    await options.resources.dispatch(scope, "resources.materialize", { ...resource, directoryHandle: handle }, {
-                        signal,
-                        resolveDirectory: async () => {
-                            await options.authorize(scope);
-                            return workDir;
-                        },
-                    });
-                }
-                if (input.connectionIds)
-                    await options.authorizeConnections(scope);
-                return input;
-            }
-            finally {
-                options.resources.releaseDirectory(scope, handle);
-            }
+            await authorize(scope, input);
+            await materialize(scope, (input.resources ?? []).filter((resource) => resource.access !== "read"), workDir, signal);
+            // Originals are verified again and sealed at each launch, so a retry cannot run
+            // against a file that changed after the task was admitted.
+            await verifiedOriginals(scope, input, signal);
+            if (input.connectionIds)
+                await options.authorizeConnections(scope);
+            return input;
         },
         async execute(job, context) {
             const input = toolInput(job.input);
-            await options.authorize(job.scope);
+            await authorize(job.scope, input);
             let stdout = "", outputBytes = 0, result, failed;
             let processId = "", terminal = false, stopped;
             let progress = Promise.resolve();
@@ -257,8 +347,7 @@ export function createPanelToolExecutor(options) {
                 if (checking || terminal)
                     return;
                 checking = true;
-                void options
-                    .authorize(job.scope)
+                void authorize(job.scope, input)
                     .catch(() => {
                     failed ??= Object.assign(new Error("Tool task authorization was revoked"), {
                         code: "APP_REVOKED",
@@ -281,11 +370,17 @@ export function createPanelToolExecutor(options) {
                 });
                 if (entry.sha256 !== job.entry.sha256)
                     throw new Error("Installed tool changed; start a new job");
+                await authorizeDirectRead(job.scope, input);
+                const originals = await verifiedOriginals(job.scope, input, context.signal);
                 const directory = await options.processes.grantDirectory(owner, context.workDir);
                 resourceDirectoryHandles.push(directory.handle);
                 const fileArgumentHandles = [];
                 for (const item of input.directoryArguments ?? []) {
-                    const root = item.directory === "job" ? context.workDir : await options.appDataDirectory(job.scope);
+                    const root = item.directory === "job"
+                        ? context.workDir
+                        : item.directory === "bookmark"
+                            ? await bookmarkDirectory(job.scope, item.bookmark)
+                            : await options.appDataDirectory(job.scope);
                     const location = await childDirectory(root, item.path);
                     const grant = await options.processes.grantDirectory(owner, location);
                     const argument = await options.processes.grantDirectoryArgument(owner, {
@@ -307,6 +402,47 @@ export function createPanelToolExecutor(options) {
                     });
                     fileArgumentHandles.push(argument.handle);
                 }
+                if (Object.keys(originals).length) {
+                    // A manifest rather than links: a Guest-chosen name must never redirect a tool's
+                    // writes onto the user's file. The tool opens an original only on purpose.
+                    await mkdir(options.sealedRoot, { recursive: true, mode: 0o700 });
+                    const sealed = await mkdtemp(join(options.sealedRoot, "originals-"));
+                    const cleanup = () => rm(sealed, { recursive: true, force: true }).catch(() => { });
+                    cleanups.push(cleanup);
+                    const path = join(sealed, "originals.json");
+                    await writeFile(path, JSON.stringify({ originals }), { mode: 0o600, flag: "wx" });
+                    const argument = await options.processes.grantFileArgument(owner, {
+                        executableHandle: executable.handle,
+                        argumentName: input.originalsArgument,
+                        path,
+                        cleanup,
+                        // The approval may wait, and a reference may be forgotten or relinked
+                        // while the child runs. Reuse the process grant's launch/live checks.
+                        validate: async () => {
+                            await authorize(job.scope, input);
+                            const current = await verifiedOriginals(job.scope, input, context.signal);
+                            for (const [key, original] of Object.entries(originals)) {
+                                if (current[key]?.path !== original.path || current[key]?.bytes !== original.bytes)
+                                    throw originalUnavailable("changed", true);
+                            }
+                        },
+                    });
+                    fileArgumentHandles.push(argument.handle);
+                }
+                if (input.cookieArgument) {
+                    const { argumentName, ...selection } = input.cookieArgument;
+                    const sealed = await options.cookies.materialize(job.scope, selection);
+                    cleanups.push(sealed.cleanup);
+                    const argument = await options.processes.grantFileArgument(owner, {
+                        executableHandle: executable.handle,
+                        argumentName,
+                        path: sealed.path,
+                        cleanup: () => {
+                            void sealed.cleanup().catch(() => { });
+                        },
+                    });
+                    fileArgumentHandles.push(argument.handle);
+                }
                 context.signal.throwIfAborted();
                 const launched = await options.processes.start(owner, {
                     executableHandle: executable.handle,
@@ -365,6 +501,11 @@ export function createPanelToolExecutor(options) {
                 context.signal.throwIfAborted();
                 if (failed)
                     throw failed;
+                for (const resource of directReads(input)) {
+                    const reference = await options.resources.references.get(job.scope, resource.assetId);
+                    if (reference.state !== "available")
+                        throw originalUnavailable(reference.state, true);
+                }
                 if (receipt.code !== 0 || result === undefined)
                     throw new Error("Tool did not return a completed result");
                 const value = result;
@@ -398,7 +539,7 @@ export function createPanelToolExecutor(options) {
                     }
                     value.artifacts = assets;
                 }
-                await options.authorize(job.scope);
+                await authorize(job.scope, input);
                 return value;
             }
             finally {
@@ -414,7 +555,7 @@ export function createPanelToolExecutor(options) {
                     options.resources.releaseDirectory(job.scope, handle);
                 options.releaseOwner(owner);
                 for (const cleanup of cleanups)
-                    cleanup();
+                    await cleanup();
             }
         },
     };

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

@@ -11,6 +11,8 @@ export declare class ToolJobStorage {
     directory(id?: string, work?: boolean, create?: boolean): Promise<string>;
     read(path: string, limit: number): Promise<unknown>;
     write(id: string, value: unknown, limit: number): Promise<void>;
+    readQueueCatalog(limit: number): Promise<unknown>;
+    writeQueueCatalog(value: unknown, limit: number): Promise<void>;
     close(): Promise<void>;
     remove(id: string): Promise<void>;
 }

package/dist/panels/tool-jobs-storage.js

@@ -149,6 +149,40 @@ export class ToolJobStorage {
             await rm(temporary, { force: true }).catch(() => { });
         }
     }
+    async readQueueCatalog(limit) {
+        try {
+            return await this.read(join(await this.directory(), "queues.json"), limit);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return [];
+            throw error;
+        }
+    }
+    async writeQueueCatalog(value, limit) {
+        const directory = await this.directory();
+        const temporary = join(directory, `${randomUUID()}.tmp`);
+        try {
+            const file = await open(temporary, "wx", 0o600);
+            try {
+                await file.writeFile(JSON.stringify(toolJobJson(value, limit)));
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+            await this.directory();
+            await rename(temporary, join(directory, "queues.json"));
+            const parent = await open(directory, "r").catch(() => null);
+            if (parent) {
+                await parent.sync().catch(() => { });
+                await parent.close();
+            }
+        }
+        finally {
+            await rm(temporary, { force: true }).catch(() => { });
+        }
+    }
     async close() {
         if (!this.nonce)
             return;

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

@@ -1,6 +1,8 @@
 export declare const toolJobLimits: Readonly<{
     maxJobs: 2000;
-    maxQueuedPerScope: 32;
+    maxQueuedPerScope: 128;
+    maxQueues: 512;
+    maxQueueCatalogBytes: number;
     maxConcurrent: 2;
     maxInputBytes: number;
     maxResultBytes: number;
@@ -13,10 +15,30 @@ export interface ToolJobScope {
     projectPath: string;
     revision: string;
 }
+/** Scope-owned scheduling; pausing stops admission to execution, not active processes. */
+export interface ToolQueueState {
+    revision: number;
+    paused: boolean;
+    maxConcurrent: number;
+}
+export interface ToolQueueWriteResult {
+    saved: boolean;
+    queue: ToolQueueState;
+}
+export interface ToolQueueUpdate {
+    expectedRevision: number;
+    paused: boolean;
+    maxConcurrent: number;
+}
 export interface ToolJobEntry {
     name: string;
     sha256: string;
 }
+/** Host-selected package identity, never supplied by the task request. */
+export interface ToolJobPackage {
+    version: string;
+    packageDigest: string;
+}
 export interface ToolJobProgress {
     fraction?: number;
     stage?: string;
@@ -27,6 +49,7 @@ export interface ToolJob {
     id: string;
     scope: ToolJobScope;
     entry: ToolJobEntry;
+    package?: ToolJobPackage;
     input: unknown;
     recovery: "manual" | "retry";
     status: ToolJobStatus;
@@ -44,6 +67,7 @@ export interface ToolJob {
     };
     result?: unknown;
 }
+export type ToolJobEvent = Omit<ToolJob, "input" | "result">;
 export interface ToolJobRequest {
     entry: ToolJobEntry;
     input: unknown;
@@ -62,6 +86,8 @@ export interface PanelToolJobServiceOptions {
     /** Freeze authorized inputs into workDir; persist only relative names and safe JSON. */
     prepareInput?(scope: ToolJobScope, input: unknown, workDir: string, signal: AbortSignal): Promise<unknown>;
     isAuthorized?(scope: ToolJobScope): boolean | Promise<boolean>;
+    /** Resolve and inspect the authorized project package, including its full content digest. */
+    describePackage?(scope: ToolJobScope): Promise<ToolJobPackage>;
     onEvent?(job: ToolJob): void;
     now?: () => number;
 }
@@ -70,6 +96,7 @@ export declare class PanelToolJobService {
     private readonly options;
     private readonly storage;
     private readonly jobs;
+    private readonly queues;
     private readonly active;
     private readonly preparing;
     private ready?;
@@ -77,28 +104,47 @@ export declare class PanelToolJobService {
     private stopping;
     private pumping;
     private shutdownPromise?;
+    private readonly unregisterExecution;
     constructor(options: PanelToolJobServiceOptions);
-    activeCount(): number;
+    private readonly listeners;
+    /** Trusted Host subscription. Transports must recheck their viewer's authorization. */
+    subscribe(rawScope: ToolJobScope, send: (job: ToolJobEvent) => void): () => void;
+    private executionScopes;
+    activeCount(projectPath?: string): number;
     private now;
     private exclusive;
     private authorize;
+    private describePackage;
+    private verifyPackage;
+    private readOnly;
     initialize(): Promise<void>;
     private load;
     private commit;
     private lookup;
+    /** Scoped existence check for transports merging read-only legacy history. */
+    has(rawScope: ToolJobScope, id: string): Promise<boolean>;
     list(rawScope: ToolJobScope): Promise<Array<ToolJob & {
         readOnly: boolean;
     }>>;
     get(rawScope: ToolJobScope, id: string): Promise<ToolJob & {
         readOnly: boolean;
     }>;
+    find(rawScope: ToolJobScope, requestKey: string): Promise<ToolJob | null>;
+    private queueFor;
+    getQueue(rawScope: ToolJobScope): Promise<ToolQueueState>;
+    setQueue(rawScope: ToolJobScope, update: ToolQueueUpdate): Promise<ToolQueueWriteResult>;
+    private runnable;
+    private pendingCount;
     start(rawScope: ToolJobScope, request: ToolJobRequest, signal?: AbortSignal): Promise<ToolJob>;
+    private startAdmitted;
     private schedule;
     private pump;
     private run;
     cancel(rawScope: ToolJobScope, id: string): Promise<ToolJob>;
     retry(rawScope: ToolJobScope, id: string): Promise<ToolJob>;
-    cancelApp(appId: string): Promise<void>;
+    private retryAdmitted;
+    cancelProject(projectPath: string, appId?: string): Promise<void>;
+    cancelApp(appId: string, projectPath?: string): Promise<void>;
     shutdown(): Promise<void>;
     private stop;
 }