@fungi.computer/computer 0.0.0-stage → 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,282 @@
+import { Workspace, WorkspaceProxy, WorkspaceServiceProxy, type WorkspaceStubHost } from "@fungi.computer/cloudflare-computer";
+import { type WorkerShellBackendOptions } from "@fungi.computer/cloudflare-computer/backends/worker-shell";
+import { type IWorkspaceContainerAPI } from "@fungi.computer/cloudflare-computer/backends/container";
+import { DurableObject } from "cloudflare:workers";
+import type { FilesPort } from "@fungi.computer/knapsack";
+import { z } from "zod";
+import { type ComputerExecutionBudget, type ComputerExecRequest, type ComputerOperationResult, type ComputerFileReadInput, type ComputerFileByteReadInput, type ComputerFileReplacement, type ComputerFileReplacementResult, type ComputerValue, writeInputSchema, writeOutputSchema, type ComputerProcess } from "./operation-contract.js";
+import { createWorkspaceFilesPort } from "./files.js";
+import { OnBoxVmContainerHost, type OnBoxVmEnv, type OnBoxVmPlacement } from "./on-box-vm.js";
+import { type AttachedBackend, type AttachedBackendView, type BackendNeed, type BackendRoute, type ContainerRuntimeStart, type HostedBacking } from "./computer-backends.js";
+import { LocalBackendConnections } from "./local-backend.js";
+/** The exact RPC surface of one Computer Durable Object. */
+export type ComputerRpc = WorkspaceStubHost & Readonly<{
+    getCapabilities: ComputerDO["getCapabilities"];
+    call: (capabilityId: ComputerValue, input: ComputerValue) => Promise<ComputerValue>;
+    readFile: (input: ComputerFileReadInput) => Promise<ReadableStream<Uint8Array>>;
+    writeFile: (input: ComputerFileReadInput, content: ReadableStream<Uint8Array>) => Promise<void>;
+    exposePort: (input: {
+        port: number;
+    }) => Promise<{
+        port: number;
+        exposed: boolean;
+    }>;
+    listPorts: () => Promise<{
+        ports: number[];
+    }>;
+    unexposePort: (input: {
+        port: number;
+    }) => Promise<{
+        port: number;
+        removed: boolean;
+    }>;
+    replaceFileIfUnchanged: (input: ComputerFileReplacement) => Promise<ComputerFileReplacementResult>;
+}>;
+/** The Cloudflare binding projection needed to select one named Computer. */
+export type ComputerNamespace = Readonly<{
+    getByName: (name: string) => ComputerRpc;
+}>;
+/** Cloudflare bindings required by the first durable Computer host. */
+export type ComputerEnv = OnBoxVmEnv & Readonly<{
+    /** Host-supplied native loopback binding; not a process environment variable. */
+    COMPUTER_EGRESS?: (options: {
+        props: {
+            computerObjectId: string;
+        };
+    }) => Fetcher;
+    /** Platform kill switch for container-backed Computer operations. */
+    HOSTED_COMPUTERS?: string;
+    LOADER?: NonNullable<WorkerShellBackendOptions["loader"]>;
+}>;
+/** A command could not be placed on an attached backend. */
+export declare class ComputerBackendUnavailableError extends Error {
+    readonly code: "no_backend" | "backend_unavailable";
+    constructor(code: "no_backend" | "backend_unavailable");
+}
+declare class ComputerDurableObject extends DurableObject<ComputerEnv> {
+    get bindings(): ComputerEnv;
+    get state(): DurableObjectState;
+}
+declare const ContainerComputerBase: typeof ComputerDurableObject & (new (...args: any[]) => ComputerDurableObject & {
+    getWorkspaceContainer(): import("@fungi.computer/cloudflare-computer/backends/container").WorkspaceContainerAPI;
+});
+/**
+ * The Computer owns its Workspace. `@cloudflare/computer` fixes a Workspace's
+ * backends when it is constructed, so the Workspace is rebuilt whenever the
+ * attached set changes; the previous generation is closed and a command still
+ * running on it ends as a transport failure. A local machine connecting or
+ * leaving changes status, not the set, and rebuilds nothing.
+ */
+declare class ContainerComputer extends ContainerComputerBase {
+    #private;
+    /** Parked dial-ins from attached machines; survives Workspace rebuilds. */
+    readonly localConnections: LocalBackendConnections;
+    constructor(ctx: DurableObjectState, env: ComputerEnv);
+    getWorkspaceContainer(): import("@fungi.computer/cloudflare-computer/backends/container").WorkspaceContainerAPI;
+    /**
+     * This Computer's attached backends, in attach order. The standalone
+     * runtime attaches its Worker's default host; a Computer owner (Hub)
+     * overrides this with the list its Team projected down.
+     */
+    protected attachedBackends(): readonly AttachedBackend[];
+    /** A runtime of a hosted backend started; owners meter it. */
+    protected containerRuntimeStarted(start: ContainerRuntimeStart): void;
+    /** The single routing decision over this Computer's attached backends. */
+    protected routeBackend(backend: string | undefined, need: BackendNeed): Extract<BackendRoute, {
+        kind: "routed";
+    }>;
+    /**
+     * The hosted backend that terminals, processes and ports use: the first in
+     * the default order, or none when only local machines are attached.
+     */
+    protected hostedRoute(): Readonly<{
+        id: string;
+        backing: HostedBacking;
+    }> | undefined;
+    /** The hosted route, or the typed failure a caller maps to unavailable. */
+    protected requireHostedRoute(): Readonly<{
+        id: string;
+        backing: HostedBacking;
+    }>;
+    /** This Computer's attached backends with their live status. */
+    protected describeBackends(): AttachedBackendView[];
+    /** The metered container host behind one hosted backend. */
+    protected hostedContainerHost(backing: HostedBacking): IWorkspaceContainerAPI;
+    /** The on-box VM host service for `hostId`, one per placement. */
+    protected onBoxVmHost(hostId: string): OnBoxVmContainerHost;
+    /** Let the consuming owner admit boots while preserving the runtime host seam. */
+    protected createOnBoxVmHost(placement: OnBoxVmPlacement): OnBoxVmContainerHost;
+    /** Whether a hosted backend's runtime is running now. */
+    protected containerRunning(backing: HostedBacking): Promise<boolean>;
+    /** A consuming host supplies its admitted shell loopback context. */
+    protected workerShellContext(): Pick<DurableObjectState, "exports">;
+    /** The Workspace for the current attached set, rebuilt when it changes. */
+    protected workspace(): Workspace;
+    /**
+     * The current Workspace once its mount index is ready and its guest mount
+     * root exists. Every backend mounts `/workspace`, so a host write there
+     * (such as a Workflow step's one-shot Git credential file) must not depend
+     * on a guest having booted first.
+     */
+    protected readyWorkspace(): Promise<Workspace>;
+    /** `getWorkspace(stub)` reaches the current generation through this door. */
+    __getWorkspaceStub(): Promise<import("@fungi.computer/cloudflare-computer").WorkspaceStub>;
+    /**
+     * Backend doors. An attached machine dials in on its public connect path.
+     * A container backend's `/ws` upgrade and egress: the platform container's
+     * arrive as `/ws` through WorkspaceProxy; an on-box VM's through the
+     * verified ingress door as `/__vm/<hostId>/ws`.
+     */
+    fetch(request: Request): Promise<Response>;
+}
+/** One upstream Cloudflare Workspace that advertises and runs its capabilities. */
+export declare class ComputerDO extends ContainerComputer {
+    #private;
+    /** Persist the bounded set of ports admitted for preview on this Computer. */
+    exposePort(input: {
+        port: number;
+    }): Promise<{
+        port: number;
+        exposed: boolean;
+    }>;
+    /** Host checks current authority at the write boundary. */
+    protected exposePortAfterAcceptance(input: {
+        port: number;
+    }, accept: () => void): Promise<{
+        port: number;
+        exposed: boolean;
+    }>;
+    /** List only the durable port-admission metadata for this Computer. */
+    listPorts(): Promise<{
+        ports: number[];
+    }>;
+    /** Host checks current authority before returning the admitted port set. */
+    protected listPortsAfterAcceptance(accept: () => void): Promise<{
+        ports: number[];
+    }>;
+    /** Remove one port from the Computer's durable preview admission set. */
+    unexposePort(input: {
+        port: number;
+    }): Promise<{
+        port: number;
+        removed: boolean;
+    }>;
+    /** Host checks current authority at the write boundary. */
+    protected unexposePortAfterAcceptance(input: {
+        port: number;
+    }, accept: () => void): Promise<{
+        port: number;
+        removed: boolean;
+    }>;
+    /**
+     * Proxy one admitted request to this Computer's container. The host must
+     * pass a Request whose URL is service-relative, using the `http://localhost`
+     * placeholder origin and a path/query with the Hub route prefix removed.
+     */
+    protected portPreviewAfterAcceptance(portInput: number, request: Request, accept: () => void): Promise<Response>;
+    getCapabilities(): Promise<{
+        id: string;
+        name: string;
+        kind: string;
+        description: string;
+        parameters: Record<string, unknown>;
+        output: Record<string, unknown>;
+    }[]>;
+    /** Read bounded native bytes before releasing the single-owner Workspace. */
+    readFile(input: ComputerFileReadInput): Promise<ReadableStream<Uint8Array>>;
+    /** Resource hosts may accept authority after the file queue and Workspace are ready. */
+    protected readFileAfterAcceptance(input: ComputerFileByteReadInput, accept: () => void, maximumBytes?: number): Promise<{
+        offset: number;
+        total: number;
+        length: number;
+        body: ReadableStream<Uint8Array<ArrayBufferLike>>;
+    }>;
+    /** Completion means the maintained Workspace writer consumed and committed the stream. */
+    writeFile(input: ComputerFileReadInput, content: ReadableStream<Uint8Array>): Promise<void>;
+    /** Resource hosts may accept authority after the file queue and Workspace are ready. */
+    protected writeFileAfterAcceptance(input: ComputerFileReadInput, content: ReadableStream<Uint8Array>, accept: () => void): Promise<void>;
+    /** Keep one Workspace lease around one authorized structured Files operation. */
+    protected withFilesAfterAcceptance<A>(accept: () => void, operation: (files: ReturnType<typeof createWorkspaceFilesPort>) => Promise<A>): Promise<A>;
+    /** A Files write uses the packaged native engine and the ordinary metered backend. */
+    protected applyPatchAfterAcceptance(input: {
+        patch: string;
+    }, accept: () => void): Promise<{
+        status: "completed" | "failed" | "cancelled";
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+        truncated: boolean;
+    } | {
+        status: "completed" | "failed" | "cancelled";
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+        truncated: boolean;
+        error: {
+            kind: "mismatch";
+        };
+    }>;
+    /** Write bounded UTF-8 text after the resource host accepts local authority. */
+    protected writeTextAfterAcceptance(input: z.output<typeof writeInputSchema>, accept: () => void): Promise<z.output<typeof writeOutputSchema>>;
+    call(capabilityId: ComputerValue, input: ComputerValue): Promise<ComputerValue>;
+    /** Resource hosts may accept authority once the Workspace is ready to dispatch. */
+    protected callAfterAcceptance(capabilityId: ComputerValue, input: ComputerValue, accept: () => void): Promise<ComputerValue>;
+    /**
+     * Execute a host request once, after the host accepts current authority.
+     * `exec` runs on the Workspace's built-in Worker shell unless it names an
+     * attached backend; `bash` always runs on an attached backend, the named one
+     * or the first available in the default order.
+     */
+    protected executeOperationAfterAcceptance(input: ComputerExecRequest, accept: () => void, kind: "exec" | "bash", budget?: ComputerExecutionBudget, signal?: AbortSignal): Promise<ComputerOperationResult>;
+    /**
+     * Run one command on a routed backend. Owners admit and meter hosted
+     * backends here; a member's own machine is neither reserved nor metered.
+     */
+    protected runOnBackend<T>(route: Extract<BackendRoute, {
+        kind: "routed";
+    }>, run: () => Promise<T>): Promise<T>;
+    /** Start one long-running container process with a durable identity. */
+    startProcess(input: ComputerValue): Promise<ComputerProcess>;
+    /** The host accepts authority when the running slot is reserved. */
+    protected startProcessAfterAcceptance(input: ComputerValue, accept: () => void): Promise<ComputerProcess>;
+    /** List this Computer's processes, reconciling live ones with computerd. */
+    listProcesses(): Promise<{
+        processes: ComputerProcess[];
+    }>;
+    protected listProcessesAfterAcceptance(accept: () => void): Promise<{
+        processes: ComputerProcess[];
+    }>;
+    /** Send SIGTERM to one running process; its exit is recorded when observed. */
+    killProcess(input: ComputerValue): Promise<{
+        process: ComputerProcess;
+        signalled: boolean;
+    }>;
+    protected killProcessAfterAcceptance(input: ComputerValue, accept: () => void): Promise<{
+        process: ComputerProcess;
+        signalled: boolean;
+    }>;
+    protected getOperationStatusAfterAcceptance(requestId: string, accept: () => void): ComputerOperationResult;
+    /**
+     * Relay one authorized terminal upgrade to this Computer's own terminal
+     * server, which keeps the PTY for `session` across socket reconnects.
+     */
+    protected terminalAfterAcceptance(request: Request, principalKey: string, accept: () => void): Promise<Response>;
+    protected withHostedResponse(_backing: HostedBacking, run: () => Promise<Response>): Promise<Response>;
+    /** Host-owned display labels only; never credentials or provider URLs. */
+    protected terminalDisplayEnvironment(): Promise<Record<string, string>>;
+    /** Atomically replace one bounded file only when its raw contents still match. */
+    replaceFileIfUnchanged(input: ComputerFileReplacement): Promise<ComputerFileReplacementResult>;
+    /** Stale-safe replacement with authority checked at the transaction boundary. */
+    protected replaceFileIfUnchangedAfterAcceptance(input: ComputerFileReplacement, accept: () => void): Promise<ComputerFileReplacementResult>;
+}
+export { WorkspaceProxy, WorkspaceServiceProxy };
+export { OnBoxVmContainerHost, onBoxVmPlacement, onBoxVmIngress, type OnBoxVmEnv, type OnBoxVmState, } from "./on-box-vm.js";
+export { computerContainerSleepAfterMs } from "./container-policy.js";
+export * from "./computer-backends.js";
+export { LocalBackendOfflineError, localBackendAudience, localBackendDialPath, verifyLocalBackendDial, } from "./local-backend.js";
+/** Keep each native Workspace lease inside the operation that uses it. */
+export declare function createComputerFilesPort(computer: ComputerRpc): FilesPort;
+export { createWorkspaceFilesPort, type WorkspaceFilesOwner } from "./files.js";
+export * from "./operation-contract.js";
+export { ComputerOperationConflictError, ComputerOperationLimitError, ComputerRequestInvalidError, } from "./operation-record.js";
+export type { ContainerComputer };