@cjhyy/code-shell-server 0.9.9 → 0.9.11

package/dist/panels/tool-executor.js

@@ -0,0 +1,421 @@
+import { createHash } from "node:crypto";
+import { mkdir, lstat, realpath } 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";
+function toolInput(value) {
+    if (!value ||
+        typeof value !== "object" ||
+        Array.isArray(value) ||
+        Object.keys(value).some((key) => ![
+            "request",
+            "resources",
+            "directoryArguments",
+            "connectionIds",
+            "connectionArgument",
+        ].includes(key)))
+        throw new Error("Invalid tool job input");
+    const input = value;
+    if (!input.request || typeof input.request !== "object" || Array.isArray(input.request))
+        throw new Error("Tool request must be an object");
+    if (input.resources !== undefined &&
+        (!Array.isArray(input.resources) || input.resources.length > 128))
+        throw new Error("Too many tool resources");
+    const paths = new Set();
+    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))
+            throw new Error("Invalid tool resource");
+        resourceRelativePath(resource.path);
+        if (paths.has(resource.path))
+            throw new Error("Duplicate tool resource path");
+        paths.add(resource.path);
+    }
+    if (input.directoryArguments !== undefined &&
+        (!Array.isArray(input.directoryArguments) || input.directoryArguments.length > 4))
+        throw new Error("Too many tool directories");
+    const argumentsSeen = new Set();
+    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)))
+            throw new Error("Invalid tool directory argument");
+        if (argumentsSeen.has(item.argumentName))
+            throw new Error("Duplicate tool argument");
+        argumentsSeen.add(item.argumentName);
+        if (item.path !== undefined)
+            resourceRelativePath(item.path);
+    }
+    if (input.connectionIds !== undefined) {
+        panelConnectionIds(input.connectionIds);
+        if (!input.connectionArgument ||
+            !/^--[a-z][a-z0-9-]{0,63}$/.test(input.connectionArgument) ||
+            argumentsSeen.has(input.connectionArgument))
+            throw new Error("Invalid connection argument");
+    }
+    else if (input.connectionArgument !== undefined)
+        throw new Error("Connection selection is required");
+    return input;
+}
+async function childDirectory(root, relative) {
+    let path = await realpath(root);
+    for (const part of relative ? resourceRelativePath(relative).split("/") : []) {
+        path = join(path, part);
+        await mkdir(path, { mode: 0o700 }).catch((error) => {
+            if (error.code !== "EEXIST")
+                throw error;
+        });
+        const info = await lstat(path);
+        if (!info.isDirectory() || info.isSymbolicLink() || (await realpath(path)) !== path)
+            throw new Error("Tool directory changed");
+    }
+    return path;
+}
+/** The only background processor: launch a reviewed tool and transport bounded JSON/files. */
+export function createPanelToolExecutor(options) {
+    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);
+            }
+        },
+        async execute(job, context) {
+            const input = toolInput(job.input);
+            await options.authorize(job.scope);
+            let stdout = "", outputBytes = 0, result, failed;
+            let processId = "", terminal = false, stopped;
+            let progress = Promise.resolve();
+            let pendingProgress;
+            let reportingProgress = false;
+            let sequence = 0;
+            const pendingEvents = new Map();
+            let reconciling;
+            let finish;
+            const exit = new Promise((resolve) => {
+                finish = resolve;
+            });
+            const stop = () => {
+                stopped ??= (async () => {
+                    if (!processId || terminal)
+                        return;
+                    await options.processes.cancel(owner, { processId });
+                    await exit;
+                })();
+                return stopped;
+            };
+            const parse = (line) => {
+                if (!line.trim())
+                    return;
+                const message = JSON.parse(line);
+                if (!message || typeof message !== "object" || Array.isArray(message))
+                    throw new Error("Invalid tool response");
+                if (message.type === "progress") {
+                    if (!message.progress ||
+                        typeof message.progress !== "object" ||
+                        Array.isArray(message.progress))
+                        throw new Error("Invalid tool progress");
+                    pendingProgress = message.progress;
+                    if (!reportingProgress) {
+                        reportingProgress = true;
+                        progress = (async () => {
+                            while (pendingProgress !== undefined) {
+                                const update = pendingProgress;
+                                pendingProgress = undefined;
+                                await context.reportProgress(update);
+                            }
+                        })()
+                            .catch((error) => {
+                            failed ??= error instanceof Error ? error : new Error(String(error));
+                            void stop();
+                        })
+                            .finally(() => {
+                            reportingProgress = false;
+                        });
+                    }
+                }
+                else if (message.type === "result") {
+                    if (result !== undefined)
+                        throw new Error("Tool returned multiple results");
+                    result = message.result;
+                }
+                else if (message.type === "error") {
+                    failed ??= Object.assign(new Error(typeof message.message === "string" ? message.message.slice(0, 2000) : "Tool failed"), {
+                        ...(typeof message.code === "string" ? { code: message.code.slice(0, 100) } : {}),
+                        ...(typeof message.retryable === "boolean" ? { retryable: message.retryable } : {}),
+                    });
+                    void stop();
+                }
+                else
+                    throw new Error("Unsupported tool response");
+            };
+            const consume = (event, payload) => {
+                if (event === "process.exit") {
+                    terminal = true;
+                    finish({ code: payload.code, signal: payload.signal });
+                    return;
+                }
+                if (payload.stream !== "stdout" || typeof payload.text !== "string")
+                    return;
+                try {
+                    outputBytes += Buffer.byteLength(payload.text);
+                    if (outputBytes > processLimits.maxOutputBytes)
+                        throw new Error("Tool output exceeds the limit");
+                    stdout += payload.text;
+                    while (stdout.includes("\n")) {
+                        const end = stdout.indexOf("\n");
+                        const line = stdout.slice(0, end);
+                        stdout = stdout.slice(end + 1);
+                        parse(line);
+                    }
+                    if (Buffer.byteLength(stdout) > 256 * 1024)
+                        throw new Error("Tool response exceeds the limit");
+                }
+                catch (error) {
+                    failed ??= error instanceof Error ? error : new Error("Invalid tool output");
+                    void stop();
+                }
+            };
+            const receive = (event, payload) => {
+                if (processId && payload.processId !== processId)
+                    return;
+                if (!Number.isSafeInteger(payload.sequence)) {
+                    consume(event, payload);
+                    return;
+                }
+                const cursor = Number(payload.sequence);
+                if (cursor <= sequence)
+                    return;
+                pendingEvents.set(cursor, { event, payload });
+                if (pendingEvents.size > processLimits.maxEventsPerProcess) {
+                    failed ??= new Error("Too many missed tool events");
+                    void stop();
+                    return;
+                }
+                while (pendingEvents.has(sequence + 1)) {
+                    const item = pendingEvents.get(++sequence);
+                    pendingEvents.delete(sequence);
+                    consume(item.event, item.payload);
+                }
+            };
+            const owner = options.owner(job, receive);
+            const reconcile = () => {
+                if (!processId)
+                    return Promise.resolve();
+                return (reconciling ??= (async () => {
+                    const receipt = await options.processes.get(owner, {
+                        processId,
+                        afterSequence: sequence,
+                        limit: 256,
+                    });
+                    if (!receipt.found)
+                        throw new Error("Tool process receipt is unavailable");
+                    if (receipt.truncated)
+                        throw new Error("Tool output was lost before it could be read");
+                    for (const item of receipt.events)
+                        receive(item.event, item.payload);
+                })()
+                    .catch((error) => {
+                    failed ??= error instanceof Error ? error : new Error(String(error));
+                    void stop();
+                })
+                    .finally(() => {
+                    reconciling = undefined;
+                }));
+            };
+            const receiptTimer = setInterval(() => {
+                void reconcile();
+            }, 200);
+            receiptTimer.unref();
+            const abort = () => {
+                void stop();
+            };
+            context.signal.addEventListener("abort", abort, { once: true });
+            const cleanups = [];
+            const resourceDirectoryHandles = [];
+            let checking = false;
+            const authorizationTimer = setInterval(() => {
+                if (checking || terminal)
+                    return;
+                checking = true;
+                void options
+                    .authorize(job.scope)
+                    .catch(() => {
+                    failed ??= Object.assign(new Error("Tool task authorization was revoked"), {
+                        code: "APP_REVOKED",
+                        retryable: false,
+                    });
+                    return stop();
+                })
+                    .finally(() => {
+                    checking = false;
+                });
+            }, 1000);
+            authorizationTimer.unref();
+            try {
+                const executable = await options.processes.findExecutable(owner, { name: "node" });
+                if (!executable.available || !executable.handle)
+                    throw new Error("Node.js 20 or newer is required for installed tools");
+                const entry = await options.processes.resolveEntry(owner, {
+                    name: job.entry.name,
+                    executableHandle: executable.handle,
+                });
+                if (entry.sha256 !== job.entry.sha256)
+                    throw new Error("Installed tool changed; start a new job");
+                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 location = await childDirectory(root, item.path);
+                    const grant = await options.processes.grantDirectory(owner, location);
+                    const argument = await options.processes.grantDirectoryArgument(owner, {
+                        executableHandle: executable.handle,
+                        argumentName: item.argumentName,
+                        directoryHandle: grant.handle,
+                    });
+                    fileArgumentHandles.push(argument.handle);
+                }
+                if (input.connectionIds) {
+                    await options.authorizeConnections(job.scope);
+                    const sealed = await materializePanelConnections(options.sealedRoot, job.scope.projectPath, input.connectionIds);
+                    cleanups.push(sealed.cleanup);
+                    const argument = await options.processes.grantFileArgument(owner, {
+                        executableHandle: executable.handle,
+                        argumentName: input.connectionArgument,
+                        path: sealed.path,
+                        cleanup: sealed.cleanup,
+                    });
+                    fileArgumentHandles.push(argument.handle);
+                }
+                context.signal.throwIfAborted();
+                const launched = await options.processes.start(owner, {
+                    executableHandle: executable.handle,
+                    entryHandle: entry.handle,
+                    directoryHandle: directory.handle,
+                    fileArgumentHandles,
+                    args: [],
+                    stdin: "pipe",
+                });
+                processId = launched.processId;
+                // Capture this Host-only waiter before revocation can retire the owner's grants.
+                void options.processes
+                    .waitForExit(owner, { processId })
+                    .then((value) => {
+                    terminal = true;
+                    finish(value);
+                })
+                    .catch((error) => {
+                    // This can only be absent after the process has already closed and its
+                    // owner retired the receipt before the waiter attached.
+                    failed ??= error instanceof Error ? error : new Error(String(error));
+                    terminal = true;
+                    finish({ code: null, signal: null });
+                });
+                if (failed || context.signal.aborted) {
+                    stopped = undefined;
+                    await stop();
+                    context.signal.throwIfAborted();
+                    throw failed;
+                }
+                const request = JSON.stringify({
+                    ...input.request,
+                    jobId: job.id,
+                    scopeKey: createHash("sha256")
+                        .update(JSON.stringify([job.scope.appId, job.scope.projectPath]))
+                        .digest("hex"),
+                });
+                if (Buffer.byteLength(request) > processLimits.maxStdinBytes)
+                    throw new Error("Tool input exceeds the stdin limit");
+                // Slice by characters conservatively, preserving surrogate pairs across writes.
+                const characters = Array.from(request);
+                for (let i = 0; i < characters.length; i += 3000) {
+                    context.signal.throwIfAborted();
+                    await options.processes.write(owner, {
+                        processId,
+                        text: characters.slice(i, i + 3000).join(""),
+                    });
+                }
+                await options.processes.end(owner, { processId });
+                const receipt = await exit;
+                await reconciling;
+                await reconcile();
+                if (stdout.trim())
+                    parse(stdout);
+                await progress;
+                context.signal.throwIfAborted();
+                if (failed)
+                    throw failed;
+                if (receipt.code !== 0 || result === undefined)
+                    throw new Error("Tool did not return a completed result");
+                const value = result;
+                if (!value || typeof value !== "object" || Array.isArray(value))
+                    throw new Error("Tool result must be an object");
+                if (value.artifacts !== undefined) {
+                    if (!Array.isArray(value.artifacts) || value.artifacts.length > 128)
+                        throw new Error("Invalid tool output inventory");
+                    const assets = [];
+                    for (const artifact of value.artifacts) {
+                        if (!artifact ||
+                            typeof artifact !== "object" ||
+                            !/^[a-f0-9]{64}$/.test(artifact.sha256) ||
+                            artifact.assetId !== `asset-${artifact.sha256}`)
+                            throw new Error("Invalid tool artifact identity");
+                        resourceRelativePath(artifact.file);
+                        if (!Number.isSafeInteger(artifact.bytes) || artifact.bytes < 0)
+                            throw new Error("Invalid tool artifact size");
+                        const captured = await options.resources.dispatch(job.scope, "resources.capture", {
+                            directoryHandle: directory.handle,
+                            path: artifact.file,
+                            name: artifact.name ?? artifact.file.split("/").at(-1),
+                            mimeType: artifact.mimeType,
+                            expectedBytes: artifact.bytes,
+                            expectedSha256: artifact.sha256,
+                        }, {
+                            resolveDirectory: (handle) => options.processes.directoryPath(owner, handle),
+                            signal: context.signal,
+                        });
+                        assets.push({ ...artifact, asset: captured.asset });
+                    }
+                    value.artifacts = assets;
+                }
+                await options.authorize(job.scope);
+                return value;
+            }
+            finally {
+                clearInterval(receiptTimer);
+                clearInterval(authorizationTimer);
+                context.signal.removeEventListener("abort", abort);
+                if (processId && !terminal) {
+                    stopped = undefined;
+                    await stop().catch(() => { });
+                }
+                options.processes.revokeGuest(owner.guestId);
+                for (const handle of resourceDirectoryHandles)
+                    options.resources.releaseDirectory(job.scope, handle);
+                options.releaseOwner(owner);
+                for (const cleanup of cleanups)
+                    cleanup();
+            }
+        },
+    };
+}

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

@@ -0,0 +1,16 @@
+export declare function toolJobJson<T>(value: T, limit: number): T;
+/** A private Host directory, with each descendant checked before file operations. */
+export declare class ToolJobStorage {
+    private readonly configuredRoot;
+    private root;
+    private identity;
+    private nonce;
+    private readonly directories;
+    constructor(configuredRoot: string);
+    initialize(): Promise<void>;
+    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>;
+    close(): Promise<void>;
+    remove(id: string): Promise<void>;
+}

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

@@ -0,0 +1,169 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, realpath, rename, rm } from "node:fs/promises";
+import { dirname, isAbsolute, join } from "node:path";
+export function toolJobJson(value, limit) {
+    let text;
+    try {
+        text = JSON.stringify(value);
+    }
+    catch {
+        /* reject below */
+    }
+    if (text === undefined || Buffer.byteLength(text) > limit)
+        throw new Error("tool job JSON exceeds its limit or is not serializable");
+    return JSON.parse(text);
+}
+/** A private Host directory, with each descendant checked before file operations. */
+export class ToolJobStorage {
+    configuredRoot;
+    root = "";
+    identity = "";
+    nonce = "";
+    directories = new Map();
+    constructor(configuredRoot) {
+        this.configuredRoot = configuredRoot;
+    }
+    async initialize() {
+        if (!isAbsolute(this.configuredRoot))
+            throw new Error("tool job root must be absolute");
+        await mkdir(this.configuredRoot, { recursive: true, mode: 0o700 });
+        const initial = await lstat(this.configuredRoot);
+        if (!initial.isDirectory() || initial.isSymbolicLink())
+            throw new Error("invalid tool job root");
+        this.root = await realpath(this.configuredRoot);
+        this.identity = `${initial.dev}:${initial.ino}`;
+        const lockPath = join(this.root, "owner.lock");
+        const create = () => open(lockPath, "wx", 0o600);
+        let lock;
+        try {
+            lock = await create();
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const current = (await this.read(lockPath, 1024));
+            let alive = false;
+            if (Number.isSafeInteger(current.pid) && Number(current.pid) > 1) {
+                try {
+                    process.kill(Number(current.pid), 0);
+                    alive = true;
+                }
+                catch (cause) {
+                    if (cause.code !== "ESRCH")
+                        alive = true;
+                }
+            }
+            else
+                throw new Error("invalid tool job ownership lock", { cause: error });
+            if (alive)
+                throw new Error("tool job storage is already owned by a running Host", { cause: error });
+            await rm(lockPath);
+            lock = await create();
+        }
+        this.nonce = randomUUID();
+        try {
+            await lock.writeFile(JSON.stringify({ pid: process.pid, nonce: this.nonce }));
+            await lock.sync();
+        }
+        finally {
+            await lock.close();
+        }
+    }
+    async directory(id, work = false, create = false) {
+        const info = await lstat(this.root);
+        if (!info.isDirectory() ||
+            info.isSymbolicLink() ||
+            `${info.dev}:${info.ino}` !== this.identity ||
+            (await realpath(this.root)) !== this.root)
+            throw new Error("tool job root was replaced");
+        let path = this.root;
+        for (const part of id === undefined ? [] : [id, ...(work ? ["work"] : [])]) {
+            if (part !== "work" && !/^[a-f0-9-]{36}$/.test(part))
+                throw new Error("invalid tool job directory");
+            path = join(path, part);
+            if (create)
+                await mkdir(path, { mode: 0o700 }).catch((error) => {
+                    if (error.code !== "EEXIST")
+                        throw error;
+                });
+            const child = await lstat(path);
+            if (!child.isDirectory() || child.isSymbolicLink())
+                throw new Error("invalid tool job directory");
+            const identity = `${child.dev}:${child.ino}`;
+            const expected = this.directories.get(path);
+            if (expected && expected !== identity)
+                throw new Error("tool job directory was replaced");
+            this.directories.set(path, identity);
+        }
+        return path;
+    }
+    async read(path, limit) {
+        const file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        try {
+            const info = await file.stat();
+            if (!info.isFile() || info.nlink !== 1 || info.size > limit)
+                throw new Error("invalid tool job record");
+            const bytes = Buffer.alloc(info.size + 1);
+            let count = 0;
+            while (count < bytes.length) {
+                const { bytesRead } = await file.read(bytes, count, bytes.length - count, count);
+                if (!bytesRead)
+                    break;
+                count += bytesRead;
+            }
+            const after = await file.stat();
+            if (count !== info.size ||
+                after.size !== info.size ||
+                after.mtimeMs !== info.mtimeMs ||
+                after.nlink !== 1)
+                throw new Error("tool job record changed while reading");
+            return JSON.parse(bytes.subarray(0, count).toString("utf8"));
+        }
+        finally {
+            await file.close();
+        }
+    }
+    async write(id, value, limit) {
+        const directory = await this.directory(id, false, true);
+        const path = join(directory, "job.json");
+        const temporary = join(directory, `${randomUUID()}.tmp`);
+        const file = await open(temporary, "wx", 0o600);
+        try {
+            await file.writeFile(JSON.stringify(toolJobJson(value, limit)));
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        try {
+            await this.directory(id);
+            await rename(temporary, path);
+            const parent = await open(dirname(path), "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;
+        const path = join(await this.directory(), "owner.lock");
+        const lock = (await this.read(path, 1024));
+        if (lock.nonce === this.nonce)
+            await rm(path);
+        this.nonce = "";
+        this.directories.clear();
+    }
+    async remove(id) {
+        const path = await this.directory(id);
+        await rm(path, { recursive: true, force: true });
+        for (const key of this.directories.keys())
+            if (key === path || key.startsWith(`${path}/`))
+                this.directories.delete(key);
+    }
+}