@cjhyy/code-shell-server 0.9.22 → 0.9.25

package/dist/panels/tool-jobs.js

@@ -1,10 +1,13 @@
+import { panelExecutionGate } from "./execution-gate.js";
 import { createHash, randomUUID } from "node:crypto";
 import { opendir } from "node:fs/promises";
 import { isAbsolute, join, resolve } from "node:path";
 import { ToolJobStorage, toolJobJson } from "./tool-jobs-storage.js";
 export const toolJobLimits = Object.freeze({
     maxJobs: 2000,
-    maxQueuedPerScope: 32,
+    maxQueuedPerScope: 128,
+    maxQueues: 512,
+    maxQueueCatalogBytes: 4 * 1024 * 1024,
     maxConcurrent: 2,
     maxInputBytes: 2 * 1024 * 1024 + 8 * 1024,
     maxResultBytes: 2 * 1024 * 1024,
@@ -12,6 +15,43 @@ export const toolJobLimits = Object.freeze({
     maxProgressBytes: 4 * 1024,
     maxExaminedEntries: 4096,
 });
+const queueKey = (scope) => JSON.stringify(scopeValue(scope));
+function queueState(value) {
+    if (!value ||
+        typeof value.paused !== "boolean" ||
+        !Number.isSafeInteger(value.revision) ||
+        value.revision < 0 ||
+        !Number.isSafeInteger(value.maxConcurrent) ||
+        value.maxConcurrent < 1 ||
+        value.maxConcurrent > toolJobLimits.maxConcurrent)
+        throw new Error("Invalid tool queue state");
+    return { revision: value.revision, paused: value.paused, maxConcurrent: value.maxConcurrent };
+}
+async function waitPreparation(result, signal) {
+    signal?.throwIfAborted();
+    let abort;
+    try {
+        const outcome = signal
+            ? await Promise.race([
+                result,
+                new Promise((_resolve, reject) => {
+                    abort = () => reject(signal.reason ?? new Error("Tool request cancelled"));
+                    signal.addEventListener("abort", abort, { once: true });
+                    if (signal.aborted)
+                        abort();
+                }),
+            ])
+            : await result;
+        signal?.throwIfAborted();
+        if ("error" in outcome)
+            throw outcome.error;
+        return outcome.job;
+    }
+    finally {
+        if (abort)
+            signal?.removeEventListener("abort", abort);
+    }
+}
 const TERMINAL = new Set(["succeeded", "failed", "cancelled", "interrupted"]);
 const STATUSES = new Set([...TERMINAL, "queued", "running", "cancelling"]);
 function scopeValue(scope) {
@@ -63,6 +103,20 @@ function publicJob(job) {
     const { version: _version, requestKey: _requestKey, requestDigest: _requestDigest, ...value } = job;
     return toolJobJson(value, toolJobLimits.maxRecordBytes);
 }
+function packageValue(value) {
+    if (!value ||
+        typeof value.version !== "string" ||
+        !value.version ||
+        value.version.length > 128 ||
+        /[\u0000-\u001f\u007f]/.test(value.version) ||
+        typeof value.packageDigest !== "string" ||
+        !/^[a-f0-9]{64}$/.test(value.packageDigest))
+        throw new Error("Invalid tool job package identity");
+    return { version: value.version, packageDigest: value.packageDigest };
+}
+function packageError(code, message, retryable = true) {
+    return Object.assign(new Error(message), { code, retryable });
+}
 function storedValue(raw) {
     const job = toolJobJson(raw, toolJobLimits.maxRecordBytes);
     if (!job ||
@@ -80,6 +134,8 @@ function storedValue(raw) {
         throw new Error("invalid tool job record");
     job.scope = scopeValue(job.scope);
     job.entry = entryValue(job.entry);
+    if (job.package !== undefined)
+        job.package = packageValue(job.package);
     job.input = toolJobJson(job.input, toolJobLimits.maxInputBytes);
     if (job.result !== undefined)
         job.result = toolJobJson(job.result, toolJobLimits.maxResultBytes);
@@ -99,6 +155,7 @@ export class PanelToolJobService {
     options;
     storage;
     jobs = new Map();
+    queues = new Map();
     active = new Map();
     preparing = new Map();
     ready;
@@ -106,13 +163,31 @@ export class PanelToolJobService {
     stopping = false;
     pumping = false;
     shutdownPromise;
+    unregisterExecution;
     constructor(options) {
         this.options = options;
         this.storage = new ToolJobStorage(options.rootDir);
+        this.unregisterExecution = panelExecutionGate.register(() => this.executionScopes());
     }
-    activeCount() {
-        return (this.preparing.size +
-            [...this.jobs.values()].filter((job) => !TERMINAL.has(job.status)).length);
+    listeners = new Set();
+    /** Trusted Host subscription. Transports must recheck their viewer's authorization. */
+    subscribe(rawScope, send) {
+        const listener = { scope: scopeValue(rawScope), send };
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    executionScopes() {
+        return [
+            ...[...this.preparing.values()].map((item) => item.scope),
+            ...[...this.jobs.values()]
+                .filter((job) => !TERMINAL.has(job.status) || this.active.has(job.id))
+                .map((job) => job.scope),
+        ];
+    }
+    activeCount(projectPath) {
+        return this.executionScopes().filter((scope) => !projectPath || scope.projectPath === resolve(projectPath)).length;
     }
     now() {
         return this.options.now?.() ?? Date.now();
@@ -126,12 +201,46 @@ export class PanelToolJobService {
         if (this.options.isAuthorized && !(await this.options.isAuthorized(scope)))
             throw new Error("tool job owner is no longer authorized");
     }
+    async describePackage(scope) {
+        if (!this.options.describePackage)
+            return undefined;
+        try {
+            return packageValue(await this.options.describePackage(scope));
+        }
+        catch {
+            throw packageError("PACKAGE_UNAVAILABLE", "任务的项目安装包无法校验，请恢复原包后重试。");
+        }
+    }
+    async verifyPackage(job) {
+        if (!job.package && !this.options.describePackage)
+            return; // Legacy standalone embedders.
+        if (!job.package)
+            throw packageError("PACKAGE_UNKNOWN", "旧任务未记录安装包版本，请检查输入并重新提交任务。", false);
+        const current = await this.describePackage(job.scope);
+        if (!current)
+            throw packageError("PACKAGE_UNAVAILABLE", "当前 Host 无法校验此任务的原安装包。");
+        if (current.version !== job.package.version ||
+            current.packageDigest !== job.package.packageDigest)
+            throw packageError("PACKAGE_CHANGED", "项目安装包与任务启动时不一致，请恢复原版本，或检查输入并创建新任务。");
+    }
+    readOnly(job, scope) {
+        return (job.scope.revision !== scope.revision || (!!this.options.describePackage && !job.package));
+    }
     initialize() {
         return (this.ready ??= this.load());
     }
     async load() {
         await this.storage.initialize();
         try {
+            const queues = await this.storage.readQueueCatalog(toolJobLimits.maxQueueCatalogBytes);
+            if (!Array.isArray(queues) || queues.length > toolJobLimits.maxQueues)
+                throw new Error("Invalid tool queue catalog");
+            for (const raw of queues) {
+                const scope = scopeValue(raw?.scope), key = queueKey(scope);
+                if (this.queues.has(key))
+                    throw new Error("Duplicate tool queue scope");
+                this.queues.set(key, { scope, ...queueState(raw) });
+            }
             const listing = await opendir(await this.storage.directory());
             let examined = 0;
             for await (const item of listing) {
@@ -181,6 +290,17 @@ export class PanelToolJobService {
         catch {
             /* A caller may reconnect via list/get. */
         }
+        for (const listener of this.listeners) {
+            if (!sameScope(listener.scope, job.scope))
+                continue;
+            try {
+                const { input: _input, result: _result, ...event } = publicJob(job);
+                listener.send(event);
+            }
+            catch {
+                /* One viewer must not interrupt persistence. */
+            }
+        }
     }
     lookup(scope, id, mutate = false) {
         if (typeof id !== "string")
@@ -192,6 +312,16 @@ export class PanelToolJobService {
             throw new Error("old-revision tool jobs are read-only; create a new compatible task");
         return job;
     }
+    /** Scoped existence check for transports merging read-only legacy history. */
+    async has(rawScope, id) {
+        const scope = scopeValue(rawScope);
+        await this.initialize();
+        await this.authorize(scope);
+        if (typeof id !== "string")
+            throw new Error("tool job ID is required");
+        const job = this.jobs.get(id);
+        return !!job && sameScope(job.scope, scope, false);
+    }
     async list(rawScope) {
         const scope = scopeValue(rawScope);
         await this.initialize();
@@ -199,18 +329,91 @@ export class PanelToolJobService {
         return [...this.jobs.values()]
             .filter((job) => sameScope(job.scope, scope, false))
             .sort((a, b) => b.createdAt - a.createdAt)
-            .map((job) => ({ ...publicJob(job), readOnly: job.scope.revision !== scope.revision }));
+            .map((job) => ({ ...publicJob(job), readOnly: this.readOnly(job, scope) }));
     }
     async get(rawScope, id) {
         const scope = scopeValue(rawScope);
         await this.initialize();
         await this.authorize(scope);
         const job = this.lookup(scope, id);
-        return { ...publicJob(job), readOnly: job.scope.revision !== scope.revision };
+        return { ...publicJob(job), readOnly: this.readOnly(job, scope) };
+    }
+    async find(rawScope, requestKey) {
+        const scope = scopeValue(rawScope);
+        if (typeof requestKey !== "string" || !requestKey || requestKey.length > 160)
+            throw new Error("invalid tool job request key");
+        await this.initialize();
+        await this.authorize(scope);
+        const job = [...this.jobs.values()].find((item) => sameScope(item.scope, scope) && item.requestKey === requestKey);
+        return job ? publicJob(job) : null;
+    }
+    queueFor(scope) {
+        return queueState(this.queues.get(queueKey(scope)) ?? {
+            revision: 0,
+            paused: false,
+            maxConcurrent: toolJobLimits.maxConcurrent,
+        });
+    }
+    async getQueue(rawScope) {
+        const scope = scopeValue(rawScope);
+        await this.initialize();
+        await this.authorize(scope);
+        return this.queueFor(scope);
+    }
+    async setQueue(rawScope, update) {
+        const scope = scopeValue(rawScope);
+        const desired = queueState({
+            revision: update?.expectedRevision,
+            paused: update?.paused,
+            maxConcurrent: update?.maxConcurrent,
+        });
+        if (desired.revision >= Number.MAX_SAFE_INTEGER)
+            throw new Error("Tool queue revision exhausted");
+        await this.initialize();
+        await this.authorize(scope);
+        const result = await this.exclusive(async () => {
+            if (this.stopping)
+                throw new Error("tool job service is shutting down");
+            await this.authorize(scope);
+            const current = this.queueFor(scope);
+            if (current.revision !== desired.revision)
+                return { saved: false, queue: current };
+            const key = queueKey(scope);
+            if (!this.queues.has(key) && this.queues.size >= toolJobLimits.maxQueues)
+                throw new Error("Tool queue catalog is full");
+            const next = { scope, ...desired, revision: current.revision + 1 };
+            const catalog = new Map(this.queues);
+            catalog.set(key, next);
+            await this.storage.writeQueueCatalog([...catalog.values()], toolJobLimits.maxQueueCatalogBytes);
+            this.queues.set(key, next);
+            return { saved: true, queue: queueState(next) };
+        });
+        this.schedule();
+        return result;
+    }
+    runnable(job) {
+        if (job.status !== "queued")
+            return false;
+        const queue = this.queueFor(job.scope);
+        if (queue.paused)
+            return false;
+        let active = 0;
+        for (const id of this.active.keys()) {
+            const running = this.jobs.get(id);
+            if (running && sameScope(running.scope, job.scope))
+                active++;
+        }
+        return active < queue.maxConcurrent;
+    }
+    pendingCount(scope) {
+        return ([...this.jobs.values()].filter((job) => sameScope(job.scope, scope) && !TERMINAL.has(job.status)).length + [...this.preparing.values()].filter((job) => sameScope(job.scope, scope)).length);
     }
     async start(rawScope, request, signal) {
-        signal?.throwIfAborted();
         const scope = scopeValue(rawScope);
+        return panelExecutionGate.run(scope, () => this.startAdmitted(scope, request, signal));
+    }
+    async startAdmitted(scope, request, signal) {
+        signal?.throwIfAborted();
         const entry = entryValue(request?.entry);
         if (!["manual", "retry"].includes(request.recovery))
             throw new Error("tool job recovery must be manual or retry");
@@ -232,6 +435,8 @@ export class PanelToolJobService {
         await this.initialize();
         await this.authorize(scope);
         let done;
+        let settle;
+        let outcome;
         const reservation = await this.exclusive(async () => {
             signal?.throwIfAborted();
             if (this.stopping)
@@ -243,6 +448,12 @@ export class PanelToolJobService {
                         throw new Error("tool job request key was already used for different input");
                     return { existing };
                 }
+                const pending = [...this.preparing.values()].find((item) => sameScope(item.scope, scope) && item.requestKey === request.requestKey);
+                if (pending) {
+                    if (pending.requestDigest !== requestDigest)
+                        throw new Error("tool job request key was already used for different input");
+                    return { following: pending.result };
+                }
             }
             while (this.jobs.size + this.preparing.size >= toolJobLimits.maxJobs) {
                 const oldest = [...this.jobs.values()]
@@ -253,14 +464,18 @@ export class PanelToolJobService {
                 await this.storage.remove(oldest.id);
                 this.jobs.delete(oldest.id);
             }
-            const pending = [...this.jobs.values()].filter((job) => sameScope(job.scope, scope) && !TERMINAL.has(job.status)).length + [...this.preparing.values()].filter((job) => sameScope(job.scope, scope)).length;
-            if (pending >= toolJobLimits.maxQueuedPerScope)
+            if (this.pendingCount(scope) >= toolJobLimits.maxQueuedPerScope)
                 throw new Error("too many queued tool jobs for this workspace");
             const id = randomUUID();
             const controller = new AbortController();
             this.preparing.set(id, {
                 scope,
                 controller,
+                requestKey: request.requestKey,
+                requestDigest,
+                result: new Promise((resolveResult) => {
+                    settle = resolveResult;
+                }),
                 done: new Promise((resolve) => {
                     done = resolve;
                 }),
@@ -269,6 +484,12 @@ export class PanelToolJobService {
         });
         if (reservation.existing)
             return publicJob(reservation.existing);
+        if (reservation.following) {
+            const job = await waitPreparation(reservation.following, signal);
+            await this.authorize(scope);
+            signal?.throwIfAborted();
+            return toolJobJson(job, toolJobLimits.maxRecordBytes);
+        }
         const { id, controller } = reservation;
         const abort = () => controller.abort(signal?.reason);
         signal?.addEventListener("abort", abort, { once: true });
@@ -276,6 +497,7 @@ export class PanelToolJobService {
             abort();
         try {
             controller.signal.throwIfAborted();
+            const selectedPackage = await this.describePackage(scope);
             const workDir = await this.storage.directory(id, true, true);
             controller.signal.throwIfAborted();
             const prepared = this.options.prepareInput
@@ -286,6 +508,7 @@ export class PanelToolJobService {
                 id: id,
                 scope,
                 entry,
+                ...(selectedPackage ? { package: selectedPackage } : {}),
                 input: toolJobJson(prepared, toolJobLimits.maxInputBytes),
                 recovery: request.recovery,
                 status: "queued",
@@ -297,6 +520,7 @@ export class PanelToolJobService {
                 requestDigest,
             };
             await this.authorize(scope);
+            await this.verifyPackage(job);
             await this.exclusive(async () => {
                 if (this.stopping || controller.signal.aborted)
                     throw new Error("tool job input preparation was interrupted");
@@ -319,9 +543,12 @@ export class PanelToolJobService {
                 }
             });
             this.schedule();
-            return publicJob(job);
+            const result = publicJob(job);
+            outcome = { job: publicJob(job) };
+            return result;
         }
         catch (error) {
+            outcome = { error };
             const path = await this.storage.directory(id).catch(() => undefined);
             if (path && !this.jobs.has(id))
                 await this.storage.remove(id);
@@ -330,6 +557,7 @@ export class PanelToolJobService {
         finally {
             signal?.removeEventListener("abort", abort);
             this.preparing.delete(id);
+            settle(outcome);
             done();
         }
     }
@@ -342,7 +570,7 @@ export class PanelToolJobService {
                 this.pumping = false;
                 if (!this.stopping &&
                     this.active.size < toolJobLimits.maxConcurrent &&
-                    [...this.jobs.values()].some((job) => job.status === "queued"))
+                    [...this.jobs.values()].some((job) => this.runnable(job)))
                     this.schedule();
             }, () => {
                 this.pumping = false;
@@ -354,7 +582,7 @@ export class PanelToolJobService {
             const selected = await this.exclusive(async () => {
                 if (this.stopping)
                     return;
-                const current = [...this.jobs.values()].find((job) => job.status === "queued");
+                const current = [...this.jobs.values()].find((job) => this.runnable(job));
                 if (!current)
                     return;
                 const job = structuredClone(current);
@@ -390,6 +618,7 @@ export class PanelToolJobService {
         let failure;
         try {
             await this.authorize(job.scope);
+            await this.verifyPackage(job);
             if (this.stopping)
                 controller.abort();
             if (controller.signal.aborted)
@@ -472,6 +701,9 @@ export class PanelToolJobService {
     }
     async retry(rawScope, id) {
         const scope = scopeValue(rawScope);
+        return panelExecutionGate.run(scope, () => this.retryAdmitted(scope, id));
+    }
+    async retryAdmitted(scope, id) {
         await this.initialize();
         await this.authorize(scope);
         const job = await this.exclusive(async () => {
@@ -482,6 +714,9 @@ export class PanelToolJobService {
                 throw new Error("tool job must finish stopping before retry");
             if (current.recovery !== "retry" || !current.error?.retryable)
                 throw new Error("tool job requires a new manually reviewed request");
+            if (this.pendingCount(scope) >= toolJobLimits.maxQueuedPerScope)
+                throw new Error("too many queued tool jobs for this workspace");
+            await this.verifyPackage(current);
             const next = structuredClone(current);
             next.status = "queued";
             delete next.error;
@@ -494,12 +729,30 @@ export class PanelToolJobService {
         this.schedule();
         return job;
     }
-    async cancelApp(appId) {
+    async cancelProject(projectPath, appId) {
+        await this.initialize();
+        const project = resolve(projectPath);
+        const ids = appId
+            ? [appId]
+            : [
+                ...new Set([
+                    ...[...this.preparing.values()]
+                        .filter((item) => item.scope.projectPath === project)
+                        .map((item) => item.scope.appId),
+                    ...[...this.jobs.values()]
+                        .filter((job) => job.scope.projectPath === project)
+                        .map((job) => job.scope.appId),
+                ]),
+            ];
+        await Promise.all(ids.map((id) => this.cancelApp(id, project)));
+    }
+    async cancelApp(appId, projectPath) {
         await this.initialize();
+        const matches = (scope) => scope.appId === appId && (!projectPath || scope.projectPath === resolve(projectPath));
         for (const item of this.preparing.values())
-            if (item.scope.appId === appId)
+            if (matches(item.scope))
                 item.controller.abort();
-        const matching = [...this.jobs.values()].filter((job) => job.scope.appId === appId && !TERMINAL.has(job.status));
+        const matching = [...this.jobs.values()].filter((job) => matches(job.scope) && !TERMINAL.has(job.status));
         // Revocation bypasses the now-revoked caller grant but still waits for real exits.
         await this.exclusive(async () => {
             for (const current of matching) {
@@ -551,6 +804,8 @@ export class PanelToolJobService {
                 await this.commit(job);
             }
         });
+        this.listeners.clear();
         await this.storage.close();
+        this.unregisterExecution();
     }
 }

package/dist/panels/types.d.ts

@@ -12,6 +12,7 @@ export interface PanelGitSource {
     commit: string;
 }
 export interface ManagedPanel extends Omit<PanelAppPreview, "reviewToken" | "alreadyInstalled" | "warnings" | "source"> {
+    packageDigest?: string;
     revision: string;
     bound: boolean;
     enabled: boolean;
@@ -27,10 +28,21 @@ export interface ManagedPanel extends Omit<PanelAppPreview, "reviewToken" | "alr
     };
     compatibility: PanelCompatibility;
 }
+export interface PanelPackageIssue {
+    id: string;
+    revision: string;
+    code: "package_unavailable";
+    version?: string;
+    packageDigest?: string;
+    bound: boolean;
+    globalDisabled: boolean;
+}
 export interface PanelSnapshot {
     panels: ManagedPanel[];
+    issues?: PanelPackageIssue[];
     workspace: string;
     hasProject: boolean;
+    canRestorePackages?: boolean;
 }
 export interface PanelDiscovery {
     panels: GitPanelAppDiscoveryCandidate[];
@@ -46,7 +58,38 @@ export interface PanelReview {
     expectedRevision: string | null;
     compatibility: PanelCompatibility;
 }
+/** Trusted native hosts may review local sources without exposing paths to Web routes. */
+export interface PanelProjectReview extends Omit<PanelReview, "source"> {
+    installedVersion?: string;
+}
 export interface PanelOperationContext {
     ownerId: string;
     authorize: () => boolean | Promise<boolean>;
 }
+export interface PanelPackageVersion {
+    version: string;
+    packageDigest: string;
+    permissions: PanelAppPreview["permissions"];
+    compatibility: PanelCompatibility;
+}
+export interface PanelPackageHistory {
+    appId: string;
+    title: PanelAppPreview["title"];
+    expectedRevision: string;
+    current: {
+        version: string;
+        packageDigest?: string;
+        unavailable?: boolean;
+    };
+    versions: PanelPackageVersion[];
+    unavailablePackages: number;
+}
+export interface PanelPackageRestoreReview extends PanelPackageVersion {
+    appId: string;
+    title: PanelAppPreview["title"];
+    current: PanelPackageHistory["current"];
+    addedPermissions: PanelAppPreview["permissions"];
+    expectedRevision: string;
+    reviewToken: string;
+    expiresAt: number;
+}

package/dist/project-runtime/backup.d.ts

@@ -0,0 +1,26 @@
+export interface ProjectBackupOptions {
+    dataDir: string;
+    destination: string;
+    /** Locally available, administrator-reviewed Linux image containing tar. No pull occurs. */
+    helperImage: string;
+}
+export interface ProjectRestoreOptions {
+    source: string;
+    destination: string;
+    helperImage: string;
+}
+/** Offline, owner-only backup. It never stops projects or modifies their volumes. */
+export declare function backupProjectInstallation(options: ProjectBackupOptions): Promise<{
+    destination: string;
+    projects: number;
+    volumes: number;
+    installationId: string;
+}>;
+/** Restore into a new directory and new Docker volumes. Original installation is untouched. */
+export declare function restoreProjectInstallation(options: ProjectRestoreOptions): Promise<{
+    destination: string;
+    installationId: string;
+    previousInstallationId: string;
+    projects: number;
+    volumes: number;
+}>;