@cjhyy/code-shell-server 0.9.22 → 0.9.23

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

@@ -0,0 +1,40 @@
+import type { InstalledPanelApp } from "@cjhyy/code-shell-core";
+import type { PanelTaskCookieHost } from "./task-cookie-host.js";
+import type { TaskCookieSelection } from "./task-cookies.js";
+import type { PanelToolJobService, ToolJob, ToolJobEvent, ToolJobRequest, ToolJobScope, ToolQueueState, ToolQueueUpdate, ToolQueueWriteResult } from "./tool-jobs.js";
+/** Host composition only: no paths, scopes, or execution revisions come from HTTP callers. */
+export interface SharedPanelToolBinding {
+    readonly scope: Readonly<ToolJobScope>;
+    start(request: ToolJobRequest, signal?: AbortSignal): Promise<ToolJob>;
+    list(): Promise<Array<ToolJob & {
+        readOnly: boolean;
+    }>>;
+    has(id: string): Promise<boolean>;
+    get(id: string): Promise<ToolJob & {
+        readOnly: boolean;
+    }>;
+    cancel(id: string): Promise<ToolJob>;
+    retry(id: string): Promise<ToolJob>;
+    find(requestKey: string): Promise<ToolJob | null>;
+    getQueue(): Promise<ToolQueueState>;
+    setQueue(update: ToolQueueUpdate): Promise<ToolQueueWriteResult>;
+    subscribe(listener: (job: ToolJobEvent) => void): () => void;
+    /** Host-only port. Materialized paths must never be returned to a browser. */
+    cookies?: {
+        list(url: string): ReturnType<PanelTaskCookieHost["list"]>;
+        check(selection: TaskCookieSelection): ReturnType<PanelTaskCookieHost["check"]>;
+        materialize?(selection: TaskCookieSelection): ReturnType<PanelTaskCookieHost["materialize"]>;
+    };
+}
+export interface SharedPanelToolHost {
+    /** Freeze the installed execution revision once; do not silently follow package updates. */
+    bind(app: InstalledPanelApp, projectPath: string): Promise<SharedPanelToolBinding>;
+    activeCount(projectPath: string): number;
+    invalidate(projectPath: string, appId?: string): Promise<void>;
+}
+/** Adapts the single owning coordinator without giving a transport shutdown authority. */
+export declare function createSharedPanelToolHost(options: {
+    service(): PanelToolJobService;
+    resolveScope(app: InstalledPanelApp, projectPath: string): Promise<ToolJobScope>;
+    cookies?: Pick<PanelTaskCookieHost, "list" | "check"> & Partial<Pick<PanelTaskCookieHost, "materialize">>;
+}): SharedPanelToolHost;

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

@@ -0,0 +1,37 @@
+/** Adapts the single owning coordinator without giving a transport shutdown authority. */
+export function createSharedPanelToolHost(options) {
+    return {
+        async bind(app, projectPath) {
+            const scope = Object.freeze({ ...(await options.resolveScope(app, projectPath)) });
+            const service = options.service();
+            return Object.freeze({
+                scope,
+                start: (request, signal) => service.start(scope, request, signal),
+                list: () => service.list(scope),
+                has: (id) => service.has(scope, id),
+                get: (id) => service.get(scope, id),
+                cancel: (id) => service.cancel(scope, id),
+                retry: (id) => service.retry(scope, id),
+                find: (requestKey) => service.find(scope, requestKey),
+                getQueue: () => service.getQueue(scope),
+                setQueue: (update) => service.setQueue(scope, update),
+                subscribe: (listener) => service.subscribe(scope, listener),
+                ...(options.cookies && app.permissions.includes("credentials.cookies")
+                    ? {
+                        cookies: {
+                            list: (url) => options.cookies.list(scope, url),
+                            check: (selection) => options.cookies.check(scope, selection),
+                            ...(options.cookies.materialize
+                                ? {
+                                    materialize: (selection) => options.cookies.materialize(scope, selection),
+                                }
+                                : {}),
+                        },
+                    }
+                    : {}),
+            });
+        },
+        activeCount: (projectPath) => options.service().activeCount(projectPath),
+        invalidate: (projectPath, appId) => options.service().cancelProject(projectPath, appId),
+    };
+}

package/dist/panels/storage-store.d.ts

@@ -4,6 +4,27 @@ export declare const DEFAULT_PANEL_APP_STORAGE_QUOTA_BYTES: number;
 export type PanelAppStorage = Record<string, unknown>;
 export declare function panelAppStorageQuotaBytes(requested?: number): number;
 export declare function panelAppStorageKey(params: unknown): string;
+export interface PanelAppStorageSnapshot {
+    exists: boolean;
+    value: unknown;
+    /** Content revision, not an edit counter. null means the key is absent. */
+    revision: string | null;
+}
+export interface PanelAppStorageChange {
+    key: string;
+    expectedRevision: string | null;
+    remove: boolean;
+    value?: unknown;
+}
+/** Snapshot hashes include the key; legacy JSON files require no migration. */
+export declare function panelAppStorageSnapshot(storage: PanelAppStorage, key: string): PanelAppStorageSnapshot;
+/** Validate and copy before any async work, so a caller cannot change a pending write. */
+export declare function panelAppStorageChange(params: unknown): PanelAppStorageChange;
+/** Call only under the shared per-file lock; conflict never changes the store. */
+export declare function applyPanelAppStorageChange(storage: PanelAppStorage, change: PanelAppStorageChange): {
+    updated: boolean;
+    snapshot: PanelAppStorageSnapshot;
+};
 export declare function preparePanelAppStorage(file: string): Promise<void>;
 export declare function readPanelAppStorage(file: string, quotaBytes: number): Promise<PanelAppStorage>;
 export declare function writePanelAppStorage(file: string, storage: PanelAppStorage, quotaBytes: number, beforeCommit?: () => Promise<void>): Promise<void>;

package/dist/panels/storage-store.js

@@ -32,6 +32,49 @@ export function panelAppStorageKey(params) {
     }
     return key;
 }
+/** Snapshot hashes include the key; legacy JSON files require no migration. */
+export function panelAppStorageSnapshot(storage, key) {
+    const exists = Object.hasOwn(storage, key);
+    const value = exists ? storage[key] : null;
+    return {
+        exists,
+        value,
+        revision: exists
+            ? `sha256:${createHash("sha256")
+                .update(JSON.stringify([key, value]))
+                .digest("hex")}`
+            : null,
+    };
+}
+/** Validate and copy before any async work, so a caller cannot change a pending write. */
+export function panelAppStorageChange(params) {
+    const key = panelAppStorageKey(params);
+    const input = params;
+    const expectedRevision = input.expectedRevision;
+    if (expectedRevision !== null &&
+        (typeof expectedRevision !== "string" || !/^sha256:[0-9a-f]{64}$/.test(expectedRevision)))
+        throw new Error("storage.compareAndSet requires expectedRevision (sha256 or null)");
+    if (input.remove !== undefined && typeof input.remove !== "boolean")
+        throw new Error("storage remove must be a boolean");
+    const remove = input.remove === true;
+    if (remove && Object.hasOwn(input, "value"))
+        throw new Error("storage removal cannot also include a value");
+    const encoded = remove ? undefined : JSON.stringify(input.value);
+    if (!remove && encoded === undefined)
+        throw new Error("Panel App storage only accepts JSON values");
+    return { key, expectedRevision, remove, ...(remove ? {} : { value: JSON.parse(encoded) }) };
+}
+/** Call only under the shared per-file lock; conflict never changes the store. */
+export function applyPanelAppStorageChange(storage, change) {
+    const current = panelAppStorageSnapshot(storage, change.key);
+    if (current.revision !== change.expectedRevision)
+        return { updated: false, snapshot: current };
+    if (change.remove)
+        delete storage[change.key];
+    else
+        storage[change.key] = change.value;
+    return { updated: true, snapshot: panelAppStorageSnapshot(storage, change.key) };
+}
 function emptyStorage() {
     // A null prototype is important here: valid app keys include names such as
     // `__proto__`, `constructor`, and `toString`. They must remain data keys and

package/dist/panels/task-cookie-host.d.ts

@@ -0,0 +1,26 @@
+import { type PanelTaskCookieOptions, type TaskCookieScope, type TaskCookieSelection } from "./task-cookies.js";
+/** One Host owns this private root. Stop its native tasks before shutdown. */
+export declare class PanelTaskCookieHost {
+    private readonly options;
+    private readonly storage;
+    private initializing?;
+    private closing?;
+    private stopped;
+    private readonly pending;
+    private readonly leases;
+    constructor(options: Omit<PanelTaskCookieOptions, "revisionKey">);
+    private ready;
+    private open;
+    private run;
+    initialize(): Promise<void>;
+    list(scope: TaskCookieScope, url: string): Promise<{
+        accounts: import("./task-cookies.js").TaskCookieAccount[];
+    }>;
+    check(scope: TaskCookieScope, selection: TaskCookieSelection): Promise<import("./task-cookies.js").TaskCookieAccount>;
+    materialize(scope: TaskCookieScope, selection: TaskCookieSelection): Promise<{
+        cleanup: () => Promise<void>;
+        path: string;
+        count: number;
+    }>;
+    shutdown(): Promise<void>;
+}

package/dist/panels/task-cookie-host.js

@@ -0,0 +1,145 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { chmod, open, readdir, rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { ToolJobStorage } from "./tool-jobs-storage.js";
+import { PanelTaskCookieService, } from "./task-cookies.js";
+/** One Host owns this private root. Stop its native tasks before shutdown. */
+export class PanelTaskCookieHost {
+    options;
+    storage;
+    initializing;
+    closing;
+    stopped = false;
+    pending = new Set();
+    leases = new Set();
+    constructor(options) {
+        this.options = options;
+        this.storage = new ToolJobStorage(options.rootDirectory);
+    }
+    ready() {
+        return (this.initializing ??= this.open());
+    }
+    async open() {
+        await this.storage.initialize();
+        try {
+            const root = await this.storage.directory();
+            await chmod(root, 0o700);
+            const keyPath = join(root, "revision-key.json");
+            let record;
+            try {
+                record = await this.storage.read(keyPath, 1024);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+                record = { version: 1, key: randomBytes(32).toString("hex") };
+                const temporary = join(root, `${randomUUID()}.tmp`);
+                try {
+                    const file = await open(temporary, "wx", 0o600);
+                    try {
+                        await file.writeFile(JSON.stringify(record));
+                        await file.sync();
+                    }
+                    finally {
+                        await file.close();
+                    }
+                    await this.storage.directory();
+                    await rename(temporary, keyPath);
+                    const parent = await open(root, "r");
+                    try {
+                        await parent.sync();
+                    }
+                    finally {
+                        await parent.close();
+                    }
+                }
+                finally {
+                    await rm(temporary, { force: true });
+                }
+            }
+            const value = record;
+            if (!value ||
+                value.version !== 1 ||
+                typeof value.key !== "string" ||
+                !/^[a-f0-9]{64}$/.test(value.key))
+                throw new Error("Invalid task Cookie Host key");
+            await chmod(keyPath, 0o600);
+            // Ownership is exclusive, so these belong to an exited Host. Never sweep by age
+            // while another Host can be running, and never touch unrelated root entries.
+            for (const name of await readdir(root)) {
+                if (/^cookies-[a-zA-Z0-9]{6}$/.test(name) || /^[a-f0-9-]{36}\.tmp$/.test(name)) {
+                    await this.storage.directory();
+                    await rm(join(root, name), { recursive: true, force: true });
+                }
+            }
+            return new PanelTaskCookieService({
+                ...this.options,
+                rootDirectory: root,
+                revisionKey: Buffer.from(value.key, "hex"),
+                authorize: async (scope) => {
+                    if (this.stopped)
+                        throw new Error("Task Cookie Host is stopping");
+                    await this.storage.directory();
+                    await this.options.authorize(scope);
+                },
+            });
+        }
+        catch (error) {
+            await this.storage.close();
+            throw error;
+        }
+    }
+    run(operation) {
+        if (this.stopped)
+            return Promise.reject(new Error("Task Cookie Host is stopping"));
+        const pending = this.ready().then((service) => {
+            if (this.stopped)
+                throw new Error("Task Cookie Host is stopping");
+            return operation(service);
+        });
+        this.pending.add(pending);
+        void pending.then(() => this.pending.delete(pending), () => this.pending.delete(pending));
+        return pending;
+    }
+    initialize() {
+        return this.run(async () => { });
+    }
+    list(scope, url) {
+        return this.run((service) => service.list(scope, url));
+    }
+    check(scope, selection) {
+        return this.run((service) => service.check(scope, selection));
+    }
+    materialize(scope, selection) {
+        return this.run(async (service) => {
+            const lease = await service.materialize(scope, selection);
+            if (this.stopped) {
+                await lease.cleanup();
+                throw new Error("Task Cookie Host is stopping");
+            }
+            const cleanup = async () => {
+                await lease.cleanup();
+                this.leases.delete(cleanup);
+            };
+            this.leases.add(cleanup);
+            return { ...lease, cleanup };
+        });
+    }
+    shutdown() {
+        this.stopped = true;
+        return (this.closing ??= (async () => {
+            if (!this.initializing)
+                return;
+            // open() releases ownership itself on initialization failure.
+            const opened = await this.initializing.then(() => true, () => false);
+            await Promise.allSettled([...this.pending]);
+            if (!opened)
+                return;
+            const results = await Promise.allSettled([...this.leases].map((cleanup) => cleanup()));
+            const errors = results.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+            if (errors.length)
+                throw new AggregateError(errors, "Task Cookie cleanup failed");
+            await this.storage.close();
+        })());
+    }
+}

package/dist/panels/task-cookies.d.ts

@@ -0,0 +1,51 @@
+import { type Credential } from "@cjhyy/code-shell-core";
+export interface TaskCookieScope {
+    appId: string;
+    projectPath: string;
+    revision: string;
+}
+export interface TaskCookieSelection {
+    credentialId: string;
+    url: string;
+    /** Opaque Host-keyed version, bound to the app, project and reviewed package. */
+    revision: string;
+}
+export interface TaskCookieAccount {
+    id: string;
+    label: string;
+    domain: string;
+    revision: string;
+}
+export interface PanelTaskCookieOptions {
+    /** Private Host directory, never a workspace or task artifact directory. */
+    rootDirectory: string;
+    /** At least 32 random bytes, persisted privately by the Host across restarts. */
+    revisionKey: Uint8Array;
+    /** Host trust, installed package, project binding and credentials.cookies permission. */
+    authorize(scope: TaskCookieScope): Promise<void>;
+    /** Host-owned vault adapter. Values must never cross the UI bridge. */
+    credentials(scope: TaskCookieScope): Promise<Credential[]>;
+    now?(): number;
+}
+export declare function taskCookieSelection(raw: unknown): TaskCookieSelection;
+/** Read only the selected credential reference from a native task envelope. */
+export declare function taskCookieFromInput(raw: unknown): TaskCookieSelection | undefined;
+/** Cookie custody only. Admission/retry consent belongs to the calling Host, not this vault. */
+export declare class PanelTaskCookieService {
+    private readonly options;
+    private readonly key;
+    constructor(options: PanelTaskCookieOptions);
+    private version;
+    private cookies;
+    private snapshot;
+    list(scope: TaskCookieScope, url: string): Promise<{
+        accounts: TaskCookieAccount[];
+    }>;
+    private selected;
+    check(scope: TaskCookieScope, selection: TaskCookieSelection): Promise<TaskCookieAccount>;
+    materialize(scope: TaskCookieScope, selection: TaskCookieSelection): Promise<{
+        path: string;
+        count: number;
+        cleanup: () => Promise<void>;
+    }>;
+}

package/dist/panels/task-cookies.js

@@ -0,0 +1,183 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { chmod, lstat, mkdir, mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { formatNetscapeCookies, parseCookieJar, } from "@cjhyy/code-shell-core";
+function targetUrl(raw) {
+    if (typeof raw !== "string" || raw.length > 2048)
+        throw new Error("Cookie selection requires an HTTPS URL");
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error("Cookie selection requires an HTTPS URL");
+    }
+    if (url.protocol !== "https:" || url.username || url.password || !url.hostname)
+        throw new Error("Cookie selection requires an HTTPS URL");
+    return url;
+}
+function domain(raw) {
+    if (typeof raw !== "string")
+        return;
+    const value = raw.toLowerCase().replace(/^\./, "");
+    if (value.length > 253 ||
+        !value.includes(".") ||
+        !value.split(".").every((label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label)))
+        return;
+    return value;
+}
+function beneath(host, root) {
+    return host === root || host.endsWith(`.${root}`);
+}
+export function taskCookieSelection(raw) {
+    if (!raw ||
+        typeof raw !== "object" ||
+        Array.isArray(raw) ||
+        Object.keys(raw).some((key) => !["credentialId", "url", "revision"].includes(key)))
+        throw new Error("Invalid task Cookie selection");
+    const input = raw;
+    if (typeof input.credentialId !== "string" ||
+        !input.credentialId.trim() ||
+        input.credentialId.length > 160 ||
+        /[\x00-\x1f\x7f]/.test(input.credentialId) ||
+        typeof input.revision !== "string" ||
+        !/^[a-f0-9]{64}$/.test(input.revision))
+        throw new Error("Invalid task Cookie selection");
+    targetUrl(input.url);
+    return { credentialId: input.credentialId, url: input.url, revision: input.revision };
+}
+/** Read only the selected credential reference from a native task envelope. */
+export function taskCookieFromInput(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return;
+    const argument = raw.cookieArgument;
+    if (argument === undefined)
+        return;
+    if (!argument || typeof argument !== "object" || Array.isArray(argument))
+        throw new Error("Invalid task Cookie argument");
+    const { argumentName, ...selection } = argument;
+    if (typeof argumentName !== "string" || !/^--[a-z][a-z0-9-]{0,63}$/.test(argumentName))
+        throw new Error("Invalid task Cookie argument");
+    return taskCookieSelection(selection);
+}
+/** Cookie custody only. Admission/retry consent belongs to the calling Host, not this vault. */
+export class PanelTaskCookieService {
+    options;
+    key;
+    constructor(options) {
+        this.options = options;
+        if (!(options.revisionKey instanceof Uint8Array) || options.revisionKey.byteLength < 32)
+            throw new Error("Task Cookie revisions require a private Host key");
+        if (!isAbsolute(options.rootDirectory))
+            throw new Error("Task Cookie root must be absolute");
+        this.key = Buffer.from(options.revisionKey);
+    }
+    version(scope, credential, root) {
+        return createHmac("sha256", this.key)
+            .update(JSON.stringify([
+            "codeshell-task-cookie-v1",
+            scope.appId,
+            scope.projectPath,
+            scope.revision,
+            credential.id,
+            credential.label,
+            root,
+            credential.secret,
+        ]))
+            .digest("hex");
+    }
+    cookies(credential, root) {
+        const now = (this.options.now?.() ?? Date.now()) / 1000;
+        if (typeof credential.secret !== "string" ||
+            Buffer.byteLength(credential.secret) > 4 * 1024 * 1024)
+            return [];
+        const jar = parseCookieJar(credential.secret);
+        if (jar.length > 10000)
+            return [];
+        return jar.filter((cookie) => {
+            if (!cookie ||
+                typeof cookie !== "object" ||
+                typeof cookie.name !== "string" ||
+                typeof cookie.value !== "string" ||
+                !cookie.name ||
+                /[\x00-\x1f\x7f]/.test(cookie.name + cookie.value) ||
+                (cookie.path !== undefined &&
+                    (typeof cookie.path !== "string" ||
+                        !cookie.path.startsWith("/") ||
+                        /[\x00-\x1f\x7f]/.test(cookie.path))))
+                return false;
+            const cookieDomain = domain(cookie.domain);
+            if (!cookieDomain || !beneath(cookieDomain, root))
+                return false;
+            if (cookie.expirationDate !== undefined &&
+                (typeof cookie.expirationDate !== "number" ||
+                    !Number.isFinite(cookie.expirationDate) ||
+                    (cookie.expirationDate > 0 && cookie.expirationDate <= now)))
+                return false;
+            return true;
+        });
+    }
+    async snapshot(scope, url) {
+        await this.options.authorize(scope);
+        const result = (await this.options.credentials(scope)).flatMap((credential) => {
+            const root = domain(credential.meta?.domain);
+            if (credential.type !== "cookie" || !root || !beneath(url.hostname.toLowerCase(), root))
+                return [];
+            const cookies = this.cookies(credential, root);
+            if (!cookies.length)
+                return [];
+            return [
+                {
+                    account: {
+                        id: credential.id,
+                        label: credential.label,
+                        domain: root,
+                        revision: this.version(scope, credential, root),
+                    },
+                    cookies,
+                },
+            ];
+        });
+        await this.options.authorize(scope);
+        return result;
+    }
+    async list(scope, url) {
+        return { accounts: (await this.snapshot(scope, targetUrl(url))).map((item) => item.account) };
+    }
+    async selected(scope, raw) {
+        const input = taskCookieSelection(raw);
+        const matches = (await this.snapshot(scope, targetUrl(input.url))).filter((item) => item.account.id === input.credentialId);
+        const item = matches.length === 1 ? matches[0] : undefined;
+        if (!item ||
+            !timingSafeEqual(Buffer.from(item.account.revision, "hex"), Buffer.from(input.revision, "hex")))
+            throw new Error("Selected Cookie login changed or is unavailable; select and authorize it again");
+        return item;
+    }
+    async check(scope, selection) {
+        return (await this.selected(scope, selection)).account;
+    }
+    async materialize(scope, selection) {
+        const { cookies } = await this.selected(scope, selection);
+        const root = this.options.rootDirectory;
+        await mkdir(root, { recursive: true, mode: 0o700 });
+        const info = await lstat(root);
+        if (!info.isDirectory() || info.isSymbolicLink())
+            throw new Error("Invalid task Cookie root");
+        await chmod(root, 0o700);
+        const directory = await mkdtemp(join(await realpath(root), "cookies-"));
+        await chmod(directory, 0o700);
+        const path = join(directory, "cookies.txt");
+        let cleaning;
+        const cleanup = () => (cleaning ??= rm(directory, { recursive: true, force: true }));
+        try {
+            await writeFile(path, formatNetscapeCookies(cookies), { mode: 0o600, flag: "wx" });
+            // Recheck after asynchronous filesystem work, before releasing a secret to the program.
+            await this.check(scope, selection);
+            return { path, count: cookies.length, cleanup };
+        }
+        catch (error) {
+            await cleanup();
+            throw error;
+        }
+    }
+}

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

@@ -1,5 +1,6 @@
 import { PanelAppProcessService, type PanelProcessOwner } from "./process-service.js";
 import { PanelResourceService } from "./resources/service.js";
+import { type PanelTaskCookieService, type TaskCookieSelection } from "./task-cookies.js";
 interface Scope {
     appId: string;
     projectPath: string;
@@ -23,19 +24,28 @@ interface ExecutionContext {
         message?: string;
     }): Promise<void>;
 }
+interface ToolResource {
+    assetId: string;
+    path: string;
+    /** "read": no copy; the Host lists the verified original under `path` in the sealed manifest. */
+    access?: "copy" | "read";
+}
 interface ToolInput {
     request: Record<string, unknown>;
-    resources?: Array<{
-        assetId: string;
-        path: string;
-    }>;
+    resources?: ToolResource[];
     directoryArguments?: Array<{
         argumentName: string;
-        directory: "job" | "app-data";
+        directory: "job" | "app-data" | "bookmark";
+        bookmark?: string;
         path?: string;
     }>;
     connectionIds?: string[];
     connectionArgument?: string;
+    /** Required with `access: "read"` resources: the sealed manifest's launch argument. */
+    originalsArgument?: string;
+    cookieArgument?: TaskCookieSelection & {
+        argumentName: string;
+    };
 }
 export interface PanelToolExecutorOptions {
     processes: PanelAppProcessService;
@@ -44,9 +54,15 @@ export interface PanelToolExecutorOptions {
     owner(job: Job, send: PanelProcessOwner["send"]): PanelProcessOwner;
     releaseOwner(owner: PanelProcessOwner): void;
     appDataDirectory(scope: Scope): Promise<string>;
+    /** Resolve a saved Host grant in this exact app/project; never accept a caller path. */
+    resolveDirectoryBookmark?(scope: Scope, bookmark: string): Promise<string>;
     authorize(scope: Scope): Promise<void>;
     authorizeConnections(scope: Scope): Promise<void>;
+    /** Grants `access: "read"` resources; hosts without it refuse direct reads. */
+    authorizeDirectRead?(scope: Scope): Promise<void>;
     sealedRoot: string;
+    /** Configure only when start/retry admission obtains explicit selected-account consent. */
+    cookies?: Pick<PanelTaskCookieService, "check" | "materialize">;
 }
 /** The only background processor: launch a reviewed tool and transport bounded JSON/files. */
 export declare function createPanelToolExecutor(options: PanelToolExecutorOptions): {