@cjhyy/code-shell-server 0.9.10 → 0.9.12

package/dist/index.panels.d.ts

@@ -7,3 +7,11 @@ export * from "./panels/agent-task-service.js";
 export * from "./panels/agent-task-models.js";
 export * from "./panels/agent-task-host.js";
 export type * from "./panels/types.js";
+export * from "./panels/resources/types.js";
+export * from "./panels/resources/library.js";
+export * from "./panels/resources/service.js";
+export { MAX_MEDIA_JSON_BYTES, normalizeMediaScope, mediaScopeKey, prepareMediaRoot, mediaDirectory, cloneMediaJson, readMediaJson, writeMediaJson, } from "./panels/resources/storage.js";
+export * from "./panels/bridge-contract.js";
+export * from "./panels/connections.js";
+export * from "./panels/tool-jobs.js";
+export * from "./panels/tool-executor.js";

package/dist/index.panels.js

@@ -6,3 +6,11 @@ export * from "./panels/process-service.js";
 export * from "./panels/agent-task-service.js";
 export * from "./panels/agent-task-models.js";
 export * from "./panels/agent-task-host.js";
+export * from "./panels/resources/types.js";
+export * from "./panels/resources/library.js";
+export * from "./panels/resources/service.js";
+export { MAX_MEDIA_JSON_BYTES, normalizeMediaScope, mediaScopeKey, prepareMediaRoot, mediaDirectory, cloneMediaJson, readMediaJson, writeMediaJson, } from "./panels/resources/storage.js";
+export * from "./panels/bridge-contract.js";
+export * from "./panels/connections.js";
+export * from "./panels/tool-jobs.js";
+export * from "./panels/tool-executor.js";

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

@@ -0,0 +1,72 @@
+export declare const panelRuntimeApiVersion = 14;
+export declare const panelProcessMethods: string[];
+export declare const panelResourceMethods: string[];
+export declare const panelToolJobMethods: string[];
+export declare const panelBridgeLimits: Readonly<{
+    maxParamsBytes: number;
+    maxResultBytes: number;
+    rateWindowMs: 10000;
+    maxCallsPerWindow: 30;
+    maxTransferCallsPerWindow: 512;
+    callTimeoutMs: 15000;
+    consentTimeoutMs: number;
+}>;
+export type PanelBridgeErrorCode = "PERMISSION_DENIED" | "REVOKED" | "NOT_SUPPORTED" | "RATE_LIMITED" | "PARAMS_TOO_LARGE" | "RESULT_TOO_LARGE" | "TIMEOUT" | "INVALID_ARGUMENT" | "OPERATION_FAILED";
+export declare class PanelBridgeError extends Error {
+    readonly code: PanelBridgeErrorCode;
+    readonly retryAfterMs?: number | undefined;
+    constructor(code: PanelBridgeErrorCode, message: string, retryAfterMs?: number | undefined);
+}
+/** IPC otherwise strips custom Error properties. Only the preload unwraps this envelope. */
+export declare function panelBridgeFailure(error: unknown): {
+    __codeshellPanelError: {
+        retryAfterMs?: number | undefined;
+        code: PanelBridgeErrorCode;
+        message: string;
+    };
+};
+export declare function panelRuntimeCapabilities(input: {
+    process: boolean;
+    resources?: unknown;
+    tasks?: unknown;
+    limits?: Partial<Record<keyof typeof panelBridgeLimits, number>>;
+}): {
+    tasks?: {} | undefined;
+    resources?: {
+        materialize: boolean;
+        capture: boolean;
+    } | undefined;
+    process?: Readonly<{
+        maxArguments: 256;
+        maxArgumentLength: 8192;
+        maxArgumentBytes: number;
+        maxConcurrentProcesses: 3;
+        maxFileArguments: 8;
+        maxEventChars: 16384;
+        maxOutputBytes: number;
+        maxLifetimeMs: number;
+        receiptTtlMs: number;
+        maxRetainedProcesses: 128;
+        maxRetainedProcessesPerGuest: 32;
+        maxEventsPerProcess: 256;
+        maxRetainedOutputBytes: number;
+        maxStdinChunkBytes: number;
+        maxStdinBytes: number;
+        maxStdinPendingBytes: number;
+        maxStdinPendingWrites: 4;
+        stdinWriteTimeoutMs: 10000;
+        maxEntryBytes: number;
+        maxEntryHandlesPerGuest: 64;
+    }> | undefined;
+    bridge: {
+        structuredErrors: boolean;
+        maxParamsBytes: number;
+        maxResultBytes: number;
+        rateWindowMs: number;
+        maxCallsPerWindow: number;
+        maxTransferCallsPerWindow: number;
+        callTimeoutMs: number;
+        consentTimeoutMs: number;
+    };
+    errors: string[];
+};

package/dist/panels/bridge-contract.js

@@ -0,0 +1,92 @@
+import { processLimits } from "./process-state.js";
+export const panelRuntimeApiVersion = 14;
+export const panelProcessMethods = [
+    "process.find",
+    "process.info",
+    "process.resolveEntry",
+    "process.spawn",
+    "process.get",
+    "process.cancel",
+    "process.write",
+    "process.end",
+    "filesystem.getKnownDirectory",
+    "filesystem.pickDirectory",
+    "filesystem.openDirectory",
+];
+export const panelResourceMethods = [
+    "resources.list",
+    "resources.get",
+    "resources.read",
+    "resources.upload.begin",
+    "resources.upload.write",
+    "resources.upload.get",
+    "resources.upload.finish",
+    "resources.upload.cancel",
+    "resources.materialize",
+    "resources.capture",
+];
+export const panelToolJobMethods = [
+    "tasks.start",
+    "tasks.list",
+    "tasks.get",
+    "tasks.cancel",
+    "tasks.retry",
+];
+export const panelBridgeLimits = Object.freeze({
+    maxParamsBytes: 64 * 1024,
+    maxResultBytes: 256 * 1024,
+    rateWindowMs: 10000,
+    maxCallsPerWindow: 30,
+    maxTransferCallsPerWindow: 512,
+    callTimeoutMs: 15000,
+    consentTimeoutMs: 30 * 60 * 1000,
+});
+export class PanelBridgeError extends Error {
+    code;
+    retryAfterMs;
+    constructor(code, message, retryAfterMs) {
+        super(message);
+        this.code = code;
+        this.retryAfterMs = retryAfterMs;
+        this.name = "PanelBridgeError";
+    }
+}
+/** IPC otherwise strips custom Error properties. Only the preload unwraps this envelope. */
+export function panelBridgeFailure(error) {
+    return {
+        __codeshellPanelError: {
+            code: error instanceof PanelBridgeError ? error.code : "OPERATION_FAILED",
+            message: error instanceof Error ? error.message : String(error),
+            ...(error instanceof PanelBridgeError && error.retryAfterMs !== undefined
+                ? { retryAfterMs: error.retryAfterMs }
+                : {}),
+        },
+    };
+}
+export function panelRuntimeCapabilities(input) {
+    return {
+        bridge: { ...panelBridgeLimits, ...input.limits, structuredErrors: true },
+        errors: [
+            "PERMISSION_DENIED",
+            "REVOKED",
+            "NOT_SUPPORTED",
+            "RATE_LIMITED",
+            "PARAMS_TOO_LARGE",
+            "RESULT_TOO_LARGE",
+            "TIMEOUT",
+            "INVALID_ARGUMENT",
+            "OPERATION_FAILED",
+        ],
+        ...(input.process ? { process: processLimits } : {}),
+        ...(input.resources
+            ? {
+                resources: {
+                    ...input.resources,
+                    materialize: input.process,
+                    capture: input.process,
+                },
+            }
+            : {}),
+        ...(input.tasks ? { tasks: input.tasks } : {}),
+    };
+}

package/dist/panels/connections.d.ts

@@ -0,0 +1,31 @@
+import { SettingsManager } from "@cjhyy/code-shell-core";
+import { type CatalogEntry } from "@cjhyy/code-shell-core/internal";
+/** Resolve existing credentials only; provider workflows and request formats stay in tools. */
+export declare function panelConnections(cwd: string, selectedIds?: string[]): {
+    connections: Record<string, any>[];
+    defaults: {
+        text?: string | undefined;
+        image?: string | undefined;
+        video?: string | undefined;
+        audio?: string | undefined;
+        speech?: string | undefined;
+        auxText?: string | undefined;
+    };
+};
+export declare function resolvePanelConnections(settings: Pick<ReturnType<SettingsManager["get"]>, "modelConnections" | "credentials" | "defaults">, catalog: CatalogEntry[], selectedIds?: string[]): {
+    connections: Record<string, any>[];
+    defaults: {
+        text?: string | undefined;
+        image?: string | undefined;
+        video?: string | undefined;
+        audio?: string | undefined;
+        speech?: string | undefined;
+        auxText?: string | undefined;
+    };
+};
+export declare function panelConnectionIds(input: unknown): string[];
+/** Sealed launch argument, never sent to a Guest or persisted in job input. */
+export declare function materializePanelConnections(root: string, cwd: string, selectedIds: string[]): Promise<{
+    path: string;
+    cleanup: () => void;
+}>;

package/dist/panels/connections.js

@@ -0,0 +1,118 @@
+import { createHash } from "node:crypto";
+import { SettingsManager } from "@cjhyy/code-shell-core";
+import { getMergedCatalog, resolveInstance, } from "@cjhyy/code-shell-core/internal";
+import { mkdir, mkdtemp, writeFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+/** Resolve existing credentials only; provider workflows and request formats stay in tools. */
+export function panelConnections(cwd, selectedIds) {
+    const settings = new SettingsManager(cwd, "full").get();
+    return resolvePanelConnections(settings, getMergedCatalog(), selectedIds);
+}
+export function resolvePanelConnections(settings, catalog, selectedIds) {
+    const connections = (settings.modelConnections ?? []).flatMap((connection) => {
+        if (selectedIds && !selectedIds.includes(connection.id))
+            return [];
+        const value = resolveInstance(connection, settings.credentials ?? [], catalog);
+        if (!value)
+            return [];
+        const identity = {
+            id: connection.id,
+            catalogId: connection.catalogId,
+            tag: connection.tag,
+            adapterKind: value.adapterKind,
+            model: value.model,
+            hasCredentials: !!value.apiKey || !value.needsKey,
+        };
+        if (selectedIds)
+            return [
+                {
+                    ...identity,
+                    baseUrl: value.baseUrl,
+                    apiKey: value.apiKey ?? "",
+                    entry: value.entry,
+                    preset: value.preset,
+                    paramValues: value.paramValues,
+                },
+            ];
+        const secretName = /(?:authorization|api.?key|token|secret|password|credential|header|cookie)/i;
+        const parameters = (value.preset?.params ?? [])
+            .filter((param) => !secretName.test(param.name))
+            .map((param) => ({
+            name: param.name,
+            control: param.control,
+            ...(param.control === "enum"
+                ? {
+                    options: param.options ?? [],
+                    ...(typeof param.default === "string" && param.options?.includes(param.default)
+                        ? { default: param.default }
+                        : {}),
+                }
+                : {}),
+            ...(param.control === "number"
+                ? {
+                    min: param.min,
+                    max: param.max,
+                    ...(typeof param.default === "number" ? { default: param.default } : {}),
+                }
+                : {}),
+            ...(param.control === "toggle" && typeof param.default === "boolean"
+                ? { default: param.default }
+                : {}),
+        }));
+        const paramValues = Object.fromEntries(parameters.flatMap((param) => {
+            const current = value.paramValues[param.name];
+            return (param.control === "enum" &&
+                typeof current === "string" &&
+                param.options?.includes(current)) ||
+                (param.control === "number" && typeof current === "number" && Number.isFinite(current)) ||
+                (param.control === "toggle" && typeof current === "boolean")
+                ? [[param.name, current]]
+                : [];
+        }));
+        return [
+            {
+                ...identity,
+                fingerprint: createHash("sha256")
+                    .update(JSON.stringify([connection.id, connection.catalogId, value.model, value.baseUrl]))
+                    .digest("hex")
+                    .slice(0, 32),
+                providerName: value.entry.displayName,
+                entry: { displayName: value.entry.displayName, tag: value.entry.tag },
+                preset: value.preset
+                    ? { value: value.preset.value, label: value.preset.label, params: parameters }
+                    : undefined,
+                paramValues,
+            },
+        ];
+    });
+    if (selectedIds?.some((id) => !connections.some((connection) => connection.id === id)))
+        throw new Error("Selected connection is unavailable");
+    return { connections, defaults: settings.defaults ?? {} };
+}
+export function panelConnectionIds(input) {
+    if (!Array.isArray(input) ||
+        !input.length ||
+        input.length > 8 ||
+        input.some((id) => typeof id !== "string" || !id || id.length > 200) ||
+        new Set(input).size !== input.length)
+        throw new Error("Select between one and eight configured connections");
+    return input;
+}
+/** Sealed launch argument, never sent to a Guest or persisted in job input. */
+export async function materializePanelConnections(root, cwd, selectedIds) {
+    const value = panelConnections(cwd, panelConnectionIds(selectedIds));
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    const directory = await mkdtemp(join(root, "connections-"));
+    const path = join(directory, "connections.json");
+    const cleanup = () => {
+        void rm(directory, { recursive: true, force: true }).catch(() => { });
+    };
+    try {
+        await writeFile(path, JSON.stringify(value), { mode: 0o600, flag: "wx" });
+    }
+    catch (error) {
+        cleanup();
+        throw error;
+    }
+    return { path, cleanup };
+}

package/dist/panels/process-entry.d.ts

@@ -0,0 +1,2 @@
+/** The callback supplies an installed, reviewed entry, never a Guest-provided path. */
+export declare function verifyProcessEntry(path: string, sha256: string): Promise<string>;

package/dist/panels/process-entry.js

@@ -0,0 +1,52 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, realpath } from "node:fs/promises";
+import { isAbsolute } from "node:path";
+import { processLimits } from "./process-state.js";
+function identity(info) {
+    return [info.dev, info.ino, info.size, info.mtimeMs, info.ctimeMs, info.mode].join(":");
+}
+/** The callback supplies an installed, reviewed entry, never a Guest-provided path. */
+export async function verifyProcessEntry(path, sha256) {
+    if (!isAbsolute(path) || !/^[a-f0-9]{64}$/.test(sha256))
+        throw new Error("invalid reviewed package entry");
+    if ((await realpath(path)) !== path)
+        throw new Error("package entry path contains a symbolic link");
+    const before = await lstat(path);
+    if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1)
+        throw new Error("package entry must be an unlinked regular file");
+    if (before.size > processLimits.maxEntryBytes)
+        throw new Error("package entry exceeds size limit");
+    const file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const opened = await file.stat();
+        if (identity(opened) !== identity(before))
+            throw new Error("package entry changed while opening");
+        const hash = createHash("sha256");
+        const buffer = Buffer.alloc(64 * 1024);
+        let total = 0;
+        while (true) {
+            const { bytesRead } = await file.read(buffer, 0, buffer.length, null);
+            if (!bytesRead)
+                break;
+            total += bytesRead;
+            if (total > processLimits.maxEntryBytes)
+                throw new Error("package entry exceeds size limit");
+            hash.update(buffer.subarray(0, bytesRead));
+        }
+        const after = await file.stat();
+        const current = await lstat(path);
+        if (identity(opened) !== identity(after) ||
+            identity(opened) !== identity(current) ||
+            current.isSymbolicLink() ||
+            current.nlink !== 1 ||
+            (await realpath(path)) !== path ||
+            total !== opened.size ||
+            hash.digest("hex") !== sha256)
+            throw new Error("reviewed package entry changed or failed its hash check");
+        return identity(opened);
+    }
+    finally {
+        await file.close();
+    }
+}

package/dist/panels/process-service.d.ts

@@ -1,3 +1,4 @@
+export { processLimits } from "./process-state.js";
 export interface PanelProcessApprovalScope {
     appId: string;
     revision: string;
@@ -32,6 +33,13 @@ export interface PanelAppProcessServiceOptions {
     }): Promise<boolean>;
     isExecutionApproved?(scope: PanelProcessApprovalScope): Promise<boolean>;
     rememberExecutionApproval?(scope: PanelProcessApprovalScope): Promise<void>;
+    /** Resolve a declared entry in this app revision; return a canonical, reviewed file. */
+    resolvePackageEntry?(owner: PanelProcessOwner, name: string): Promise<{
+        path: string;
+        sha256: string;
+    }>;
+    /** Clock injection for bounded receipt retention; does not alter process deadlines. */
+    now?: () => number;
 }
 export declare function panelProcessInfo(platform?: NodeJS.Platform, arch?: string, report?: unknown): {
     platform: NodeJS.Platform;
@@ -53,12 +61,16 @@ export declare class PanelAppProcessService {
     private readonly executables;
     private readonly directories;
     private readonly fileArguments;
+    private readonly entries;
     private readonly processes;
+    private readonly retiring;
+    private readonly receipts;
     private readonly approvedExecutables;
     private readonly guestEpochs;
     private readonly reservations;
     private closed;
     constructor(options: PanelAppProcessServiceOptions);
+    private now;
     private epoch;
     private assertLive;
     private authorize;
@@ -81,7 +93,20 @@ export declare class PanelAppProcessService {
     }): Promise<{
         handle: string;
     }>;
+    /** Seal an already authorized directory as a long-option argument for one executable. */
+    grantDirectoryArgument(owner: PanelProcessOwner, input: {
+        executableHandle: unknown;
+        argumentName: unknown;
+        directoryHandle: unknown;
+    }): Promise<{
+        handle: string;
+    }>;
     directoryPath(owner: PanelProcessOwner, handle: unknown): string;
+    resolveEntry(owner: PanelProcessOwner, params: unknown): Promise<{
+        handle: string;
+        name: string;
+        sha256: string;
+    }>;
     start(owner: PanelProcessOwner, params: unknown): Promise<{
         processId: string;
         executable: string;
@@ -89,6 +114,42 @@ export declare class PanelAppProcessService {
     cancel(owner: PanelProcessOwner, params: unknown): {
         cancelled: boolean;
     };
+    /** Host-only wait captured while the owner is live; never exposes output after revocation. */
+    waitForExit(owner: PanelProcessOwner, params: {
+        processId: string;
+    }): Promise<{
+        code: number | null;
+        signal: string | null;
+    }>;
+    get(owner: PanelProcessOwner, params: unknown): Promise<{
+        found: false;
+        processId: string;
+    } | {
+        cancelRequested: boolean;
+        sequence: number;
+        nextSequence: number;
+        events: import("./process-state.js").PanelProcessEvent[];
+        truncated: boolean;
+        hasMore: boolean;
+        signal?: string | null | undefined;
+        code?: number | null | undefined;
+        expiresAt?: number | undefined;
+        exitedAt?: number | undefined;
+        found: true;
+        processId: string;
+        status: "running" | "stopping" | "exited";
+        startedAt: number;
+    }>;
+    private writableProcess;
+    write(owner: PanelProcessOwner, params: unknown): Promise<{
+        bytesWritten: number;
+        totalBytes: number;
+    }>;
+    end(owner: PanelProcessOwner, params: unknown): Promise<{
+        ended: true;
+        totalBytes: number;
+    }>;
+    private sendInput;
     revokeGuest(guestId: number): void;
     /** Permanently shut down all guests, including operations awaiting approval. */
     close(): void;