@cjhyy/code-shell-server 0.9.22 → 0.9.25

package/dist/panels/http.d.ts

@@ -1,20 +1,44 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { type PanelManagementHttpOptions } from "./management-http.js";
+import type { PanelDirectoryAuthorizer } from "./directory-bookmarks.js";
+import type { SharedPanelToolHost } from "./shared-tool-jobs.js";
+import type { PanelAutomationHost } from "./automations.js";
 import { type PanelAgentTaskHostOptions } from "./agent-task-host.js";
 export declare function createPanelHttp(options: PanelManagementHttpOptions & {
     dataDir: string;
     host: "hub" | "desktop";
     publicPathPrefix?: string;
     agentTaskOptions?: PanelAgentTaskHostOptions;
+    sharedToolJobs?: SharedPanelToolHost;
+    automations?: PanelAutomationHost;
+    authorizePanelDirectory?: PanelDirectoryAuthorizer;
 }): {
     service: {
-        snapshot: () => Promise<import("./types.js").PanelSnapshot>;
+        snapshot: (appId?: string) => Promise<import("./types.js").PanelSnapshot>;
+        packageHistory(context: import("./types.js").PanelOperationContext, id: unknown, expected: unknown): Promise<import("./types.js").PanelPackageHistory>;
+        previewRestore(context: import("./types.js").PanelOperationContext, id: unknown, digest: unknown, expected: unknown): Promise<import("./types.js").PanelPackageRestoreReview>;
+        cancelRestore(context: import("./types.js").PanelOperationContext, token: unknown): Promise<{
+            cancelled: boolean;
+        }>;
+        restore(context: import("./types.js").PanelOperationContext, token: unknown): Promise<{
+            id: string;
+            packageDigest: string;
+        }>;
         assertAuthorized: (context: import("./types.js").PanelOperationContext, expected?: number) => Promise<void>;
         discover(context: import("./types.js").PanelOperationContext, input: unknown): Promise<import("./types.js").PanelDiscovery>;
         preview: (context: import("./types.js").PanelOperationContext, input: unknown) => Promise<import("./types.js").PanelReview>;
         previewUpdate(context: import("./types.js").PanelOperationContext, id: unknown, expected: unknown): Promise<import("./types.js").PanelReview>;
-        install(context: import("./types.js").PanelOperationContext, token: unknown, bind?: boolean): Promise<{
+        previewProjectSource: (context: import("./types.js").PanelOperationContext, input: import("@cjhyy/code-shell-core").PanelAppSourceInput, expected?: {
+            id: string;
+            revision: string;
+        }) => Promise<import("./types.js").PanelProjectReview>;
+        previewProjectUpdate(context: import("./types.js").PanelOperationContext, id: unknown, expected: unknown): Promise<import("./types.js").PanelProjectReview>;
+        install(context: import("./types.js").PanelOperationContext, token: unknown, bind?: boolean, approval?: {
+            overwrite?: boolean;
+            expectedId?: string;
+        }): Promise<{
             id: string;
+            packageDigest: string | undefined;
         }>;
         binding(context: import("./types.js").PanelOperationContext, id: unknown, bound: unknown, expected: unknown): Promise<import("./types.js").PanelSnapshot>;
         remove(context: import("./types.js").PanelOperationContext, id: unknown, expected: unknown): Promise<{

package/dist/panels/http.js

@@ -2,9 +2,14 @@ import { createPanelManagementHttp } from "./management-http.js";
 import { createPanelRuntime, panelWebCompatibility } from "./runtime.js";
 import { createPanelAgentTaskHost } from "./agent-task-host.js";
 export function createPanelHttp(options) {
+    // Embedded Desktop hosts opt in once their native coordinator and protocol
+    // implement the same selection. The current Desktop composition does so.
+    const projectPackages = options.projectPackages ?? options.host === "hub";
     const management = createPanelManagementHttp({
         ...options,
-        compatibility: options.compatibility ?? panelWebCompatibility,
+        projectPackages,
+        compatibility: options.compatibility ??
+            ((app) => panelWebCompatibility(app, { automations: !!options.automations })),
         onChanged: async (id, kind) => {
             await runtime?.invalidate(id);
             await options.onChanged?.(id, kind);
@@ -12,6 +17,7 @@ export function createPanelHttp(options) {
     });
     const runtime = createPanelRuntime({
         ...options,
+        projectPackages,
         snapshot: management.service.snapshot,
         createAgentTasks: (hooks) => createPanelAgentTaskHost({ ...options.agentTaskOptions, ...hooks }),
     });

package/dist/panels/hub-automations.d.ts

@@ -0,0 +1,31 @@
+import { type CronJob, type CronJobLifecycleEvent, type CronRunRequest } from "@cjhyy/code-shell-core/internal";
+import { type PanelAutomationHost } from "./automations.js";
+/** A transport lost the outcome after dispatch. Never automatically replay it. */
+export declare class HubAutomationUncertainError extends Error {
+}
+export declare class HubAutomationCancelledError extends Error {
+}
+export interface HubPanelAutomationOptions {
+    cwd: string;
+    /** Canonical binding root when the workspace is a linked worktree. */
+    bindingCwd?: string;
+    dataDir: string;
+    sessionRootDir: string;
+    /** Must check the current project binding, permission and exact package revision.
+     * Throw to stop a task whose source is no longer authorized. Never uses a page grant.
+     */
+    assertExecutable(job: Readonly<CronJob>): Promise<void>;
+    /** Host-owned runner; must forward policy and cooperate with abort before resolving.
+     * The Hub composition must reserve the bound Session against interactive runs.
+     */
+    execute(request: CronRunRequest): Promise<void>;
+    onJobEvent?(event: CronJobLifecycleEvent): void;
+}
+/** Project-owned scheduling. The Hub supplies its shared Worker, approval
+ * policy and Session reservation; embedded hosts may supply equivalent runners.
+ */
+export declare function createHubPanelAutomationHost(options: HubPanelAutomationOptions): {
+    host: PanelAutomationHost;
+    close: () => Promise<void>;
+    activeCount: () => number;
+};

package/dist/panels/hub-automations.js

@@ -0,0 +1,352 @@
+import { randomUUID } from "node:crypto";
+import { mkdirSync, lstatSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { CronScheduler, CronStore, lockSync, resolveWritePolicy, } from "@cjhyy/code-shell-core/internal";
+import { panelExecutionGate } from "./execution-gate.js";
+import { readHubSessionState } from "../hub/session-management.js";
+import { panelAutomationCreationKey, panelAutomationRevision, assertPanelAutomationRevision, PanelAutomationConflictError, parsePanelAutomationCall, } from "./automations.js";
+/** A transport lost the outcome after dispatch. Never automatically replay it. */
+export class HubAutomationUncertainError extends Error {
+}
+export class HubAutomationCancelledError extends Error {
+}
+function summary(job) {
+    return {
+        id: job.id,
+        revision: panelAutomationRevision(job),
+        name: job.name,
+        schedule: job.schedule,
+        prompt: job.prompt,
+        enabled: job.enabled,
+        cwd: job.cwd ?? null,
+        timezone: job.timezone ?? null,
+        permissionLevel: job.permissionLevel ?? null,
+        resumeSessionId: job.resumeSessionId ?? null,
+        runCount: job.runCount,
+        createdAt: job.createdAt,
+        lastRun: job.lastRun ?? null,
+        nextRun: job.nextRun ?? null,
+        disabledReason: job.disabledReason ?? null,
+        panelSource: job.panelSource ? { ...job.panelSource } : null,
+        lastExecution: job.lastExecution ? { ...job.lastExecution } : null,
+    };
+}
+/** Project-owned scheduling. The Hub supplies its shared Worker, approval
+ * policy and Session reservation; embedded hosts may supply equivalent runners.
+ */
+export function createHubPanelAutomationHost(options) {
+    const cwd = resolve(options.cwd);
+    const directory = join(options.dataDir, "panel-automations");
+    const records = join(directory, "records");
+    const owner = join(directory, "owner");
+    for (const path of [directory, records, owner]) {
+        mkdirSync(path, { recursive: true, mode: 0o700 });
+        const info = lstatSync(path);
+        if (!info.isDirectory() || info.isSymbolicLink())
+            throw Error("Unsafe automation directory");
+    }
+    // The lifetime lease and bounded CronStore transaction lock use different
+    // directories; neither nests a second acquisition of the same lock.
+    let closed = false, compromised = false;
+    const leaseState = {};
+    const unlock = lockSync(owner, {
+        stale: 30000,
+        update: 10000,
+        retries: 0,
+        onCompromised: () => {
+            compromised = true;
+            leaseState.lost?.();
+        },
+    });
+    const identities = [directory, records, owner, `${owner}.lock`].map((path) => ({
+        path,
+        info: lstatSync(path),
+    }));
+    const store = new CronStore(join(records, "cron.json"), { strictRead: true });
+    const scheduler = new CronScheduler(store);
+    const active = new Set();
+    const assertStorage = () => {
+        if (compromised)
+            throw Error("Cloud automation owner is unavailable");
+        for (const { path, info } of identities) {
+            const current = lstatSync(path);
+            if (!current.isDirectory() ||
+                current.isSymbolicLink() ||
+                current.dev !== info.dev ||
+                current.ino !== info.ino)
+                throw Error("Cloud automation storage or owner directory changed");
+        }
+    };
+    const assertOwner = () => {
+        if (closed)
+            throw Error("Cloud automation owner is unavailable");
+        assertStorage();
+    };
+    const assertSession = (sessionId) => {
+        const state = readHubSessionState(options.sessionRootDir, sessionId);
+        if (resolve(state.cwd) !== cwd)
+            throw Error("Automation task is outside this project");
+    };
+    scheduler.setJobEventListener((event) => options.onJobEvent?.(event));
+    scheduler.setExecutor(async (live, signal) => {
+        active.add(live.id);
+        const job = structuredClone(live);
+        let releaseExecution;
+        try {
+            assertOwner();
+            if (job.panelSource) {
+                releaseExecution = panelExecutionGate.enter({
+                    appId: job.panelSource.appId,
+                    projectPath: options.bindingCwd ?? cwd,
+                });
+            }
+            try {
+                if (job.cwd !== cwd || !job.resumeSessionId || !job.panelSource)
+                    throw Error("Automation binding is incomplete");
+                assertSession(job.resumeSessionId);
+                await options.assertExecutable(job);
+            }
+            catch (error) {
+                if (signal.aborted || closed || compromised)
+                    return;
+                assertOwner();
+                const reason = error instanceof Error ? error.message : "Automation authorization unavailable";
+                scheduler.disableWithReason(job.id, reason);
+                return { stoppedReason: reason };
+            }
+            assertOwner();
+            if (signal.aborted)
+                return;
+            // Re-read task ownership after asynchronous package verification. A
+            // deleted/moved Session must not be recreated by an unattended run.
+            assertSession(job.resumeSessionId);
+            // A pending verification must not execute a deleted/replaced definition.
+            // A strict reload also refuses corrupt persistence before side effects.
+            const current = store.load().find((candidate) => candidate.id === job.id);
+            if (!current ||
+                current.createdAt !== job.createdAt ||
+                current.prompt !== job.prompt ||
+                current.resumeSessionId !== job.resumeSessionId ||
+                current.cwd !== job.cwd ||
+                current.panelSource?.appId !== job.panelSource?.appId ||
+                current.panelSource?.revision !== job.panelSource?.revision ||
+                current.permissionLevel !== job.permissionLevel)
+                throw Error("Automation changed while preparing execution");
+            if (current.lastExecution?.status === "running")
+                throw Error("Previous automation outcome is unknown; restart to reconcile before retrying");
+            const receipt = {
+                id: randomUUID(),
+                status: "running",
+                startedAt: Date.now(),
+            };
+            // Persist admission before any Worker frame or model/tool side effect.
+            store.mutate((jobs) => {
+                const latest = jobs.find((value) => value.id === job.id);
+                if (!latest ||
+                    latest.createdAt !== job.createdAt ||
+                    latest.prompt !== job.prompt ||
+                    latest.resumeSessionId !== job.resumeSessionId ||
+                    latest.cwd !== job.cwd ||
+                    latest.permissionLevel !== job.permissionLevel ||
+                    latest.panelSource?.appId !== job.panelSource?.appId ||
+                    latest.panelSource?.revision !== job.panelSource?.revision ||
+                    latest.lastExecution?.status === "running")
+                    throw Error("Automation changed or has an unresolved execution");
+                return {
+                    jobs: jobs.map((value) => value.id === job.id
+                        ? { ...value, lastExecution: receipt, lastRunId: receipt.id }
+                        : value),
+                    result: null,
+                };
+            });
+            job.lastRunId = live.lastRunId = receipt.id;
+            let failure;
+            let failed = false;
+            try {
+                await options.execute({
+                    job,
+                    prompt: job.prompt,
+                    signal,
+                    ...resolveWritePolicy(job.permissionLevel),
+                });
+            }
+            catch (error) {
+                failure = error;
+                failed = true;
+            }
+            const uncertain = failure instanceof HubAutomationUncertainError;
+            const status = uncertain
+                ? "interrupted"
+                : signal.aborted || failure instanceof HubAutomationCancelledError
+                    ? "cancelled"
+                    : failed
+                        ? "failed"
+                        : "completed";
+            const detail = failed
+                ? String(failure instanceof Error ? failure.message : failure)
+                    .replaceAll("\0", "")
+                    .slice(0, 2000)
+                : undefined;
+            assertStorage();
+            // A deleted task stays deleted; a replacement never receives this run's receipt.
+            // If saving fails, the running checkpoint remains and later fires refuse it.
+            store.mutate((jobs) => ({
+                jobs: jobs.map((value) => value.id === job.id && value.lastExecution?.id === receipt.id
+                    ? {
+                        ...value,
+                        lastExecution: {
+                            ...receipt,
+                            status,
+                            finishedAt: Math.max(Date.now(), receipt.startedAt),
+                            ...(detail ? { detail } : {}),
+                        },
+                        ...(uncertain
+                            ? { enabled: false, disabledReason: detail ?? "Execution outcome is unknown" }
+                            : {}),
+                    }
+                    : value),
+                result: null,
+            }));
+            scheduler.loadJobs();
+            if (failure instanceof HubAutomationCancelledError)
+                return { cancelled: true };
+            if (failed)
+                throw failure;
+        }
+        finally {
+            releaseExecution?.();
+            active.delete(job.id);
+        }
+    });
+    let closing;
+    const close = () => {
+        if (closing)
+            return closing;
+        closed = true;
+        clearInterval(leaseState.timer);
+        scheduler.setExecutionEnabled(false);
+        scheduler.stopAll();
+        closing = Promise.all([...active].map((id) => scheduler.abort(id))).then(() => {
+            if (!compromised)
+                unlock();
+        });
+        return closing;
+    };
+    leaseState.lost = () => {
+        void close().catch(() => { });
+    };
+    try {
+        // Validate ownership before loadJobs can arm timers or persist misfire stats.
+        if (store.load().some((job) => job.cwd !== cwd))
+            throw Error("Automation store belongs to another project");
+        if (store.load().some((job) => job.lastExecution?.status === "running")) {
+            store.mutate((jobs) => ({
+                jobs: jobs.map((job) => job.lastExecution?.status === "running"
+                    ? {
+                        ...job,
+                        enabled: false,
+                        disabledReason: "Previous execution was interrupted; inspect its results before resuming",
+                        lastExecution: {
+                            ...job.lastExecution,
+                            status: "interrupted",
+                            finishedAt: Math.max(Date.now(), job.lastExecution.startedAt),
+                            detail: "Host stopped before recording a terminal outcome",
+                        },
+                    }
+                    : job),
+                result: null,
+            }));
+        }
+        scheduler.loadJobs();
+    }
+    catch (error) {
+        scheduler.stopAll();
+        unlock();
+        throw error;
+    }
+    leaseState.timer = setInterval(() => {
+        try {
+            assertOwner();
+        }
+        catch {
+            compromised = true;
+            leaseState.lost?.();
+        }
+    }, 1000);
+    leaseState.timer.unref?.();
+    const host = {
+        conditionalMutations: true,
+        async call(scope, method, params) {
+            assertOwner();
+            const operation = parsePanelAutomationCall(method, params);
+            if (resolve(scope.cwd) !== cwd || !/^[a-z0-9][a-z0-9-]{0,127}$/.test(scope.appId))
+                throw Error("Automation scope does not match this project");
+            if (!(await scope.isAuthorized()))
+                throw Error("Panel automation authorization expired");
+            assertSession(scope.sessionId);
+            assertOwner();
+            if (!(await scope.isAuthorized()))
+                throw Error("Panel automation authorization expired");
+            assertOwner();
+            assertSession(scope.sessionId);
+            scheduler.loadJobs();
+            const owns = (job) => job.cwd === cwd &&
+                job.resumeSessionId === scope.sessionId &&
+                job.panelSource?.appId === scope.appId;
+            const guard = (job) => {
+                if (!owns(job))
+                    throw Error("Automation task is not available in this Panel project");
+                if (!["pause", "delete"].includes(operation.action) &&
+                    job.panelSource?.revision !== scope.revision)
+                    throw Error("Automation uses a different Panel revision; restore its package before continuing");
+            };
+            if (operation.action === "list")
+                return { automations: scheduler.list().filter(owns).map(summary) };
+            if (operation.action === "create") {
+                if (typeof scope.revision !== "string" || !/^[a-f0-9]{64}$/.test(scope.revision))
+                    throw Error("Automation requires a reviewed package revision");
+                return summary(scheduler.create(operation.input.name, operation.input.schedule, operation.input.prompt, {
+                    cwd,
+                    resumeSessionId: scope.sessionId,
+                    timezone: operation.input.timezone,
+                    permissionLevel: "full",
+                    panelSource: { appId: scope.appId, revision: scope.revision },
+                    ...(operation.key
+                        ? {
+                            creationKey: panelAutomationCreationKey(scope.appId, cwd, scope.sessionId, operation.key),
+                        }
+                        : {}),
+                }));
+            }
+            const job = scheduler.get(operation.id);
+            if (!job) {
+                if (operation.expectedRevision)
+                    return { ok: false, conflict: true };
+                throw Error("Automation task is unavailable");
+            }
+            guard(job);
+            const check = (current) => {
+                guard(current);
+                assertPanelAutomationRevision(current, operation.expectedRevision);
+            };
+            try {
+                if (operation.action === "update") {
+                    const updated = scheduler.update(job.id, operation.patch, check);
+                    if (operation.expectedRevision)
+                        return updated
+                            ? { ok: true, automation: summary(updated) }
+                            : { ok: false, conflict: true };
+                    return updated ? summary(updated) : null;
+                }
+                const ok = scheduler[operation.action](job.id, check);
+                return operation.expectedRevision && !ok ? { ok: false, conflict: true } : { ok };
+            }
+            catch (error) {
+                if (operation.expectedRevision && error instanceof PanelAutomationConflictError)
+                    return { ok: false, conflict: true };
+                throw error;
+            }
+        },
+    };
+    return { host, close, activeCount: () => active.size };
+}

package/dist/panels/management-http.d.ts

@@ -8,13 +8,31 @@ export interface PanelManagementHttpOptions extends PanelManagementOptions {
 /** Call only after the host's same-origin authentication boundary. */
 export declare function createPanelManagementHttp(options: PanelManagementHttpOptions): {
     service: {
-        snapshot: () => Promise<import("./types.js").PanelSnapshot>;
+        snapshot: (appId?: string) => Promise<import("./types.js").PanelSnapshot>;
+        packageHistory(context: PanelOperationContext, id: unknown, expected: unknown): Promise<import("./types.js").PanelPackageHistory>;
+        previewRestore(context: PanelOperationContext, id: unknown, digest: unknown, expected: unknown): Promise<import("./types.js").PanelPackageRestoreReview>;
+        cancelRestore(context: PanelOperationContext, token: unknown): Promise<{
+            cancelled: boolean;
+        }>;
+        restore(context: PanelOperationContext, token: unknown): Promise<{
+            id: string;
+            packageDigest: string;
+        }>;
         assertAuthorized: (context: PanelOperationContext, expected?: number) => Promise<void>;
         discover(context: PanelOperationContext, input: unknown): Promise<import("./types.js").PanelDiscovery>;
         preview: (context: PanelOperationContext, input: unknown) => Promise<import("./types.js").PanelReview>;
         previewUpdate(context: PanelOperationContext, id: unknown, expected: unknown): Promise<import("./types.js").PanelReview>;
-        install(context: PanelOperationContext, token: unknown, bind?: boolean): Promise<{
+        previewProjectSource: (context: PanelOperationContext, input: import("@cjhyy/code-shell-core").PanelAppSourceInput, expected?: {
+            id: string;
+            revision: string;
+        }) => Promise<import("./types.js").PanelProjectReview>;
+        previewProjectUpdate(context: PanelOperationContext, id: unknown, expected: unknown): Promise<import("./types.js").PanelProjectReview>;
+        install(context: PanelOperationContext, token: unknown, bind?: boolean, approval?: {
+            overwrite?: boolean;
+            expectedId?: string;
+        }): Promise<{
             id: string;
+            packageDigest: string | undefined;
         }>;
         binding(context: PanelOperationContext, id: unknown, bound: unknown, expected: unknown): Promise<import("./types.js").PanelSnapshot>;
         remove(context: PanelOperationContext, id: unknown, expected: unknown): Promise<{

package/dist/panels/management-http.js

@@ -83,12 +83,25 @@ export function createPanelManagementHttp(options) {
                     const input = await body(request, ["reviewToken", "bind"]);
                     result = await service.install(context, input.reviewToken, input.bind);
                 }
+                else if (url.pathname === ROOT + "/restore" && method === "POST") {
+                    result = await service.restore(context, (await body(request, ["reviewToken"])).reviewToken);
+                }
+                else if (url.pathname === ROOT + "/restore/review" && method === "DELETE") {
+                    result = await service.cancelRestore(context, (await body(request, ["reviewToken"])).reviewToken);
+                }
                 else {
-                    const match = /^\/api\/v1\/panels\/([^/]+)(?:\/(binding|update-preview))?$/.exec(url.pathname);
+                    const match = /^\/api\/v1\/panels\/([^/]+)(?:\/(binding|update-preview|versions|restore-preview))?$/.exec(url.pathname);
                     if (!match)
                         throw new PanelManagementError(404, "not_found", "找不到这个面板操作。");
                     const id = decodeURIComponent(match[1]);
-                    if (match[2] === "binding" && method === "PATCH") {
+                    if (match[2] === "versions" && method === "POST") {
+                        result = await service.packageHistory(context, id, (await body(request, ["expectedRevision"])).expectedRevision);
+                    }
+                    else if (match[2] === "restore-preview" && method === "POST") {
+                        const input = await body(request, ["packageDigest", "expectedRevision"]);
+                        result = await service.previewRestore(context, id, input.packageDigest, input.expectedRevision);
+                    }
+                    else if (match[2] === "binding" && method === "PATCH") {
                         const input = await body(request, ["bound", "expectedRevision"]);
                         result = await service.binding(context, id, input.bound, input.expectedRevision);
                     }

package/dist/panels/management.d.ts

@@ -1,6 +1,6 @@
-import { type PanelAppPreview } from "@cjhyy/code-shell-core";
+import { type PanelAppPreview, type PanelAppSourceInput } from "@cjhyy/code-shell-core";
 import { getRefCommit } from "@cjhyy/code-shell-core/internal/skills";
-import type { PanelCompatibility, PanelDiscovery, PanelOperationContext, PanelReview, PanelSnapshot } from "./types.js";
+import type { PanelCompatibility, PanelDiscovery, PanelOperationContext, PanelReview, PanelProjectReview, PanelSnapshot, PanelPackageHistory, PanelPackageRestoreReview } from "./types.js";
 export declare class PanelManagementError extends Error {
     readonly status: number;
     readonly code: string;
@@ -12,6 +12,10 @@ export interface PanelManagementOptions {
     cwd: string;
     /** Host-authorized main project for a worktree. Defaults to the exact cwd. */
     bindingCwd?: string;
+    /** Enable only when every runtime in this Host selects the project package. */
+    projectPackages?: boolean;
+    /** Explicit opt-in for a trusted native caller; never enabled on HTTP services. */
+    allowLocalSources?: boolean;
     /** Recheck a host-verified, frozen project/worktree association before use. */
     assertBinding?: () => void;
     withMutation?: <T>(write: () => Promise<T>) => Promise<T>;
@@ -22,13 +26,31 @@ export interface PanelManagementOptions {
     resolveCommit?: typeof getRefCommit;
 }
 export declare function createPanelManagement(options: PanelManagementOptions): {
-    snapshot: () => Promise<PanelSnapshot>;
+    snapshot: (appId?: string) => Promise<PanelSnapshot>;
+    packageHistory(context: PanelOperationContext, id: unknown, expected: unknown): Promise<PanelPackageHistory>;
+    previewRestore(context: PanelOperationContext, id: unknown, digest: unknown, expected: unknown): Promise<PanelPackageRestoreReview>;
+    cancelRestore(context: PanelOperationContext, token: unknown): Promise<{
+        cancelled: boolean;
+    }>;
+    restore(context: PanelOperationContext, token: unknown): Promise<{
+        id: string;
+        packageDigest: string;
+    }>;
     assertAuthorized: (context: PanelOperationContext, expected?: number) => Promise<void>;
     discover(context: PanelOperationContext, input: unknown): Promise<PanelDiscovery>;
     preview: (context: PanelOperationContext, input: unknown) => Promise<PanelReview>;
     previewUpdate(context: PanelOperationContext, id: unknown, expected: unknown): Promise<PanelReview>;
-    install(context: PanelOperationContext, token: unknown, bind?: boolean): Promise<{
+    previewProjectSource: (context: PanelOperationContext, input: PanelAppSourceInput, expected?: {
+        id: string;
+        revision: string;
+    }) => Promise<PanelProjectReview>;
+    previewProjectUpdate(context: PanelOperationContext, id: unknown, expected: unknown): Promise<PanelProjectReview>;
+    install(context: PanelOperationContext, token: unknown, bind?: boolean, approval?: {
+        overwrite?: boolean;
+        expectedId?: string;
+    }): Promise<{
         id: string;
+        packageDigest: string | undefined;
     }>;
     binding(context: PanelOperationContext, id: unknown, bound: unknown, expected: unknown): Promise<PanelSnapshot>;
     remove(context: PanelOperationContext, id: unknown, expected: unknown): Promise<{