@fungi.computer/computer 0.0.0-stage → 0.0.1

package/dist/container-policy.d.ts

@@ -0,0 +1,7 @@
+export declare const computerContainerSleepAfterMs: number;
+export declare function hostedComputerContainersPaused(hostedComputers: string | undefined): boolean;
+export declare class ComputerContainersPausedError extends Error {
+    constructor();
+}
+export declare function assertComputerContainersEnabled(hostedComputers: string | undefined): void;
+export declare function configureComputerContainer(container: Pick<Container, "setInactivityTimeout"> | undefined): Promise<void>;

package/dist/container-policy.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+export const computerContainerSleepAfterMs = 15 * 60 * 1_000;
+const hostedComputersSchema = z
+    .enum(["enabled", "paused"])
+    .default("enabled")
+    .catch("paused");
+export function hostedComputerContainersPaused(hostedComputers) {
+    return hostedComputersSchema.parse(hostedComputers) === "paused";
+}
+export class ComputerContainersPausedError extends Error {
+    constructor() {
+        super("Hosted Computer containers are paused");
+        this.name = "ComputerContainersPausedError";
+    }
+}
+export function assertComputerContainersEnabled(hostedComputers) {
+    if (hostedComputerContainersPaused(hostedComputers))
+        throw new ComputerContainersPausedError();
+}
+export async function configureComputerContainer(container) {
+    if (container === undefined)
+        throw new Error("Computer Durable Object is not container-enabled");
+    await container.setInactivityTimeout(computerContainerSleepAfterMs);
+}

package/dist/container-system-trust.d.ts

@@ -0,0 +1,8 @@
+import type { BackendHandle } from "@fungi.computer/cloudflare-computer";
+import { CloudflareContainerBackend, type CloudflareContainerBackendOptions } from "@fungi.computer/cloudflare-computer/backends/container";
+/** Prepare intercepted HTTPS trust after the native backend installs its CA. */
+export declare class SystemTrustContainerBackend extends CloudflareContainerBackend {
+    #private;
+    constructor(options: CloudflareContainerBackendOptions);
+    connect(): Promise<BackendHandle>;
+}

package/dist/container-system-trust.js

@@ -0,0 +1,66 @@
+import { CloudflareContainerBackend, } from "@fungi.computer/cloudflare-computer/backends/container";
+/** Prepare intercepted HTTPS trust after the native backend installs its CA. */
+export class SystemTrustContainerBackend extends CloudflareContainerBackend {
+    #intercepted;
+    constructor(options) {
+        super(options);
+        this.#intercepted = options.egress?.mode === "http-gateway";
+    }
+    async connect() {
+        const handle = await super.connect();
+        if (!this.#intercepted)
+            return handle;
+        try {
+            await installContainerSystemTrust(handle.rpc.shell);
+            return handle;
+        }
+        catch (error) {
+            await handle.close().catch((cause) => {
+                console.error("Computer trust setup cleanup failed", cause);
+                return undefined;
+            });
+            throw error;
+        }
+    }
+}
+async function installContainerSystemTrust(shell) {
+    // computerd runs without root, so create its OpenSSL bundle in /tmp. The
+    // atomic rename lets simultaneous connections prepare the same CA safely.
+    // Await it before Workspace can dispatch caller commands.
+    const execution = await shell.exec({
+        source: "set -eu; " +
+            "test -r /etc/cloudflare/certs/cloudflare-containers-ca.crt || exit 78; " +
+            "trust_tmp=$(mktemp /tmp/fungi-ca-XXXXXX); " +
+            'cat /etc/ssl/certs/ca-certificates.crt /etc/cloudflare/certs/cloudflare-containers-ca.crt > "$trust_tmp"; ' +
+            'chmod 0644 "$trust_tmp"; ' +
+            'mv "$trust_tmp" /tmp/fungi-ca-bundle.crt',
+        cwd: "/",
+        timeoutMs: 10_000,
+    });
+    const reader = execution.events.getReader();
+    try {
+        let exitCode;
+        for (;;) {
+            const event = await reader.read();
+            if (event.done)
+                break;
+            if (event.value.name === "exit")
+                exitCode = event.value.code;
+        }
+        if (exitCode === 78)
+            throw new Error("Computer runtime interception CA is missing or unreadable");
+        if (exitCode !== 0)
+            throw new Error(`Computer intercepted HTTPS trust setup failed (exit ${String(exitCode)})`);
+    }
+    catch (error) {
+        await shell.disposeExec({ id: execution.id }).catch((cause) => {
+            console.error("Computer trust setup cleanup failed", cause);
+            return undefined;
+        });
+        throw error;
+    }
+    finally {
+        reader.releaseLock();
+    }
+    await shell.disposeExec({ id: execution.id });
+}

package/dist/egress-policy.d.ts

@@ -0,0 +1,89 @@
+export type PublicGitRoute = Readonly<{
+    readonly host: "github.com" | "gitlab.com" | "codeberg.org";
+    readonly repository: string;
+    /** `push` is GitHub receive-pack only, and never tried anonymously. */
+    readonly access: "read" | "push";
+}>;
+export type ComputerEgressDecision = Readonly<{
+    kind: "team-git";
+    route: PublicGitRoute;
+}> | Readonly<{
+    kind: "public";
+}> | Readonly<{
+    kind: "internal-git";
+}> | Readonly<{
+    kind: "origin-git";
+}> | Readonly<{
+    kind: "denied";
+    reason: "origin" | "method" | "path";
+}>;
+/** An HTTPS URL with the default port and no userinfo or fragment. */
+export declare function egressHttpsUrl(url: URL): boolean;
+/** Whether `url` is plain HTTPS on the host's configured root origin. An
+ * absent origin admits nothing; a malformed one is a configuration error. */
+export declare function sameOriginHttps(url: URL, origin: string | undefined): boolean;
+/**
+ * The host's own Git, as one more host entry: its configured origin and the
+ * smart-HTTP grammar its Git door serves. Classification grants no transport
+ * authority; the host's door still authenticates every exchange.
+ */
+export type OriginGitHost = Readonly<{
+    origin: string | undefined;
+    route(request: Pick<Request, "method">, url: URL): object | null;
+}>;
+/** One owner for origin, method and route decisions at Computer egress. */
+export declare function decideComputerEgress(request: Pick<Request, "method">, url: URL, host?: OriginGitHost): ComputerEgressDecision;
+/** Remove all caller credentials and forward only transport headers needed by
+ * anonymous registries and Git smart HTTP. `body: "move"` hands the caller's
+ * stream over once (a push, which never has an anonymous attempt). */
+export declare function anonymousRequest(request: Request, url: URL, options?: Readonly<{
+    body: "clone" | "move";
+}>): Request;
+export declare function anonymousResponse(response: Response): Response;
+export declare function disabledTeamIds(raw: string | undefined): ReadonlySet<string>;
+export declare class ComputerEgressConfigError extends Error {
+    readonly issues: readonly string[];
+    readonly name = "ComputerEgressConfigError";
+    constructor(issues: readonly string[]);
+}
+/** Public egress is on by default; only the explicit global kill switch
+ * (`COMPUTER_PUBLIC_EGRESS=disabled`) turns it off. Any other configured
+ * value fails closed with a typed config error rather than silently denying
+ * or enabling egress. */
+export declare function publicEgressEnabled(raw: string | undefined): boolean;
+export type PublicLaneDecision = Readonly<{
+    kind: "allowed";
+}> | Readonly<{
+    kind: "denied";
+    reason: "globally-disabled" | "team-disabled" | "computer-disabled";
+}>;
+/** The public lane's one on/off decision, in the order its switches are
+ * owned: the global kill switch, then the per-Team off list, then this
+ * Computer's own switch. Either of the first two overrides this Computer's
+ * own "on". */
+export declare function decidePublicLane(input: Readonly<{
+    publicEgressEnabled: boolean;
+    teamDisabled: boolean;
+    computerInternetAccessEnabled: boolean;
+}>): PublicLaneDecision;
+/** One structured line per egress decision, whichever host serves it. */
+export type ComputerEgressEvent = Readonly<{
+    event: "computer.egress";
+    computerId: string;
+    teamId: string | null;
+    lane: "team-git" | "public" | "internal-git" | "origin-git" | "denied";
+    host: string;
+    method: string;
+    status: number;
+    decision: string;
+    contentLength: string | null;
+}>;
+export declare function recordComputerEgress(event: ComputerEgressEvent): void;
+/** The policy refusal every host returns; the reason stays in the log. */
+export declare function computerEgressDenied(input: Omit<ComputerEgressEvent, "event" | "lane" | "contentLength">): Response;
+/**
+ * An admitted origin-git exchange as a fresh request to the host's own Git
+ * door. Only the guest's own credential (an owner key or workflow Git pass
+ * Shed sets as `http.<remote>.extraHeader`) travels; the gateway adds none.
+ */
+export declare function originGitRequest(request: Request, url: URL): Request;

package/dist/egress-policy.js

@@ -0,0 +1,240 @@
+/**
+ * The one host policy for a Computer's network egress: which origin, method
+ * and route each outbound request names. Every host's egress gateway decides
+ * here and refuses with the same response; a host serves only the lanes it
+ * offers (Hub: team, public and its own App Git; standalone Oyster: its own
+ * origin's Git) and refuses every other decision.
+ */
+import { z } from "zod";
+const publicGitHosts = new Set(["github.com", "gitlab.com", "codeberg.org"]);
+const packageHosts = new Set([
+    "registry.npmjs.org",
+    "registry.yarnpkg.com",
+    "pypi.org",
+    "files.pythonhosted.org",
+    "crates.io",
+    "static.crates.io",
+    "proxy.golang.org",
+    "deb.debian.org",
+    "archive.ubuntu.com",
+]);
+const releaseHosts = new Set([
+    "objects.githubusercontent.com",
+    "release-assets.githubusercontent.com",
+]);
+const anonymousRequestHeaders = [
+    "accept",
+    "accept-encoding",
+    "content-type",
+    "if-modified-since",
+    "if-none-match",
+    "range",
+    "user-agent",
+    "git-protocol",
+];
+const publicResponseHeaders = [
+    "accept-ranges",
+    "cache-control",
+    "content-encoding",
+    "content-length",
+    "content-range",
+    "content-type",
+    "etag",
+    "last-modified",
+    "location",
+];
+/** An HTTPS URL with the default port and no userinfo or fragment. */
+export function egressHttpsUrl(url) {
+    return (url.protocol === "https:" &&
+        url.port === "" &&
+        url.username === "" &&
+        url.password === "" &&
+        url.hash === "");
+}
+function publicGitRoute(url, method) {
+    if (!publicGitHosts.has(url.hostname))
+        return null;
+    const match = /^\/([A-Za-z0-9_.-]{1,128})\/([A-Za-z0-9_.-]{1,128})\.git\/(info\/refs|git-upload-pack|git-receive-pack)$/.exec(url.pathname);
+    const owner = match?.[1];
+    const repository = match?.[2];
+    const endpoint = match?.[3];
+    if (owner === undefined || repository === undefined || endpoint === undefined)
+        return null;
+    const exchange = (service) => (method === "GET" &&
+        endpoint === "info/refs" &&
+        url.search === `?service=${service}`) ||
+        (method === "POST" && endpoint === service && url.search === "");
+    const host = url.hostname;
+    if (host !== "github.com" && host !== "gitlab.com" && host !== "codeberg.org")
+        return null;
+    const access = exchange("git-upload-pack")
+        ? "read"
+        : // Only a Team's GitHub connection can push; other hosts stay read-only.
+            host === "github.com" && exchange("git-receive-pack")
+                ? "push"
+                : null;
+    if (access === null)
+        return null;
+    return { host, repository: `${owner}/${repository}`, access };
+}
+function isGetOrHead(method) {
+    return method === "GET" || method === "HEAD";
+}
+/** Whether `url` is plain HTTPS on the host's configured root origin. An
+ * absent origin admits nothing; a malformed one is a configuration error. */
+export function sameOriginHttps(url, origin) {
+    if (origin === undefined || !egressHttpsUrl(url))
+        return false;
+    const configured = new URL(z.url().parse(origin));
+    return (configured.pathname === "/" &&
+        configured.search === "" &&
+        configured.hash === "" &&
+        configured.username === "" &&
+        configured.password === "" &&
+        url.origin === configured.origin);
+}
+/** One owner for origin, method and route decisions at Computer egress. */
+export function decideComputerEgress(request, url, host) {
+    if (!egressHttpsUrl(url))
+        return { kind: "denied", reason: "origin" };
+    if (url.hostname === "git.team.internal" ||
+        url.hostname === "build.team.internal")
+        return { kind: "internal-git" };
+    if (host !== undefined &&
+        sameOriginHttps(url, host.origin) &&
+        host.route(request, url) !== null)
+        return { kind: "origin-git" };
+    const gitRoute = publicGitRoute(url, request.method);
+    if (gitRoute !== null)
+        return { kind: "team-git", route: gitRoute };
+    if (!isGetOrHead(request.method))
+        return { kind: "denied", reason: "method" };
+    if (packageHosts.has(url.hostname) || releaseHosts.has(url.hostname))
+        return { kind: "public" };
+    if (url.hostname === "github.com" &&
+        /^\/[A-Za-z0-9_.-]{1,128}\/[A-Za-z0-9_.-]{1,128}\/releases\/download\/[^/]+\/[^/]+(?:\/.*)?$/.test(url.pathname))
+        return { kind: "public" };
+    if (url.hostname === "codeload.github.com" &&
+        /^\/[A-Za-z0-9_.-]{1,128}\/[A-Za-z0-9_.-]{1,128}\/(?:legacy\.(?:zip|tar\.gz)|archive)\//.test(url.pathname))
+        return { kind: "public" };
+    return { kind: "denied", reason: "origin" };
+}
+/** Remove all caller credentials and forward only transport headers needed by
+ * anonymous registries and Git smart HTTP. `body: "move"` hands the caller's
+ * stream over once (a push, which never has an anonymous attempt). */
+export function anonymousRequest(request, url, options = { body: "clone" }) {
+    const headers = new Headers();
+    for (const name of anonymousRequestHeaders) {
+        const value = request.headers.get(name);
+        if (value !== null)
+            headers.set(name, value);
+    }
+    const init = {
+        method: request.method,
+        headers,
+        redirect: "manual",
+        signal: request.signal,
+    };
+    if (request.method !== "GET" && request.method !== "HEAD") {
+        // A GitHub public read can return 401/404 before Team custody is tried;
+        // retain a second stream for that existing authorized fallback.
+        const body = options.body === "move" ? request.body : request.clone().body;
+        Object.assign(init, { body, duplex: "half" });
+    }
+    return new Request(url, init);
+}
+export function anonymousResponse(response) {
+    const headers = new Headers();
+    for (const name of publicResponseHeaders) {
+        const value = response.headers.get(name);
+        if (value !== null)
+            headers.set(name, value);
+    }
+    return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+    });
+}
+export function disabledTeamIds(raw) {
+    return new Set((raw ?? "")
+        .split(",")
+        .map((teamId) => teamId.trim())
+        .filter((teamId) => teamId.length > 0));
+}
+export class ComputerEgressConfigError extends Error {
+    issues;
+    name = "ComputerEgressConfigError";
+    constructor(issues) {
+        super(`Invalid Computer egress configuration: ${issues.join("; ")}`);
+        this.issues = issues;
+    }
+}
+const publicEgressSwitchSchema = z.enum(["enabled", "disabled"]).optional();
+/** Public egress is on by default; only the explicit global kill switch
+ * (`COMPUTER_PUBLIC_EGRESS=disabled`) turns it off. Any other configured
+ * value fails closed with a typed config error rather than silently denying
+ * or enabling egress. */
+export function publicEgressEnabled(raw) {
+    const parsed = publicEgressSwitchSchema.safeParse(raw);
+    if (!parsed.success)
+        throw new ComputerEgressConfigError(parsed.error.issues.map(({ message }) => message));
+    return parsed.data !== "disabled";
+}
+/** The public lane's one on/off decision, in the order its switches are
+ * owned: the global kill switch, then the per-Team off list, then this
+ * Computer's own switch. Either of the first two overrides this Computer's
+ * own "on". */
+export function decidePublicLane(input) {
+    if (!input.publicEgressEnabled)
+        return { kind: "denied", reason: "globally-disabled" };
+    if (input.teamDisabled)
+        return { kind: "denied", reason: "team-disabled" };
+    if (!input.computerInternetAccessEnabled)
+        return { kind: "denied", reason: "computer-disabled" };
+    return { kind: "allowed" };
+}
+export function recordComputerEgress(event) {
+    console.info(JSON.stringify(event));
+}
+/** The policy refusal every host returns; the reason stays in the log. */
+export function computerEgressDenied(input) {
+    recordComputerEgress({
+        event: "computer.egress",
+        ...input,
+        lane: "denied",
+        contentLength: null,
+    });
+    return new Response("Computer egress denied by policy", {
+        status: input.status,
+        headers: { "Content-Type": "text/plain; charset=utf-8" },
+    });
+}
+/** Smart-HTTP transport headers plus the guest's own credential. */
+const originGitRequestHeaders = [
+    ...anonymousRequestHeaders,
+    "authorization",
+    "content-encoding",
+];
+/**
+ * An admitted origin-git exchange as a fresh request to the host's own Git
+ * door. Only the guest's own credential (an owner key or workflow Git pass
+ * Shed sets as `http.<remote>.extraHeader`) travels; the gateway adds none.
+ */
+export function originGitRequest(request, url) {
+    const headers = new Headers();
+    for (const name of originGitRequestHeaders) {
+        const value = request.headers.get(name);
+        if (value !== null)
+            headers.set(name, value);
+    }
+    const init = {
+        method: request.method,
+        headers,
+        redirect: "manual",
+        signal: request.signal,
+    };
+    if (request.method !== "GET" && request.method !== "HEAD")
+        Object.assign(init, { body: request.body, duplex: "half" });
+    return new Request(url, init);
+}

package/dist/execution-result.d.ts

@@ -0,0 +1,3 @@
+import type { WorkspaceRuntimeExecHandle } from "@fungi.computer/cloudflare-computer";
+/** A host deadline cancels the owned execution, rather than merely abandoning its result. */
+export declare function computerExecutionResult(run: WorkspaceRuntimeExecHandle<"utf8">, signal?: AbortSignal): Promise<import("@fungi.computer/cloudflare-computer").WorkspaceRuntimeResult<"utf8">>;

package/dist/execution-result.js

@@ -0,0 +1,28 @@
+/** A host deadline cancels the owned execution, rather than merely abandoning its result. */
+export async function computerExecutionResult(run, signal) {
+    if (signal === undefined)
+        return await run.result();
+    let interrupt = () => undefined;
+    const interrupted = new Promise((resolve) => {
+        interrupt = () => {
+            resolve({ kind: "interrupted" });
+        };
+        signal.addEventListener("abort", interrupt, { once: true });
+        if (signal.aborted)
+            interrupt();
+    });
+    try {
+        const result = await Promise.race([
+            run.result().then((value) => ({ kind: "result", value })),
+            interrupted,
+        ]);
+        if (result.kind === "result")
+            return result.value;
+        await run.kill("SIGKILL");
+        signal.throwIfAborted();
+        throw new Error("Computer execution interrupted");
+    }
+    finally {
+        signal.removeEventListener("abort", interrupt);
+    }
+}

package/dist/files-patch.d.ts

@@ -0,0 +1,20 @@
+import type { Workspace } from "@fungi.computer/cloudflare-computer";
+/** Await Workspace synchronization even when the native engine reports a partial failure. */
+export declare function applyWorkspacePatch(workspace: Pick<Workspace, "runtime">, backend: string, input: {
+    patch: string;
+}): 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";
+    };
+}>;

package/dist/files-patch.js

@@ -0,0 +1,108 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { patchInputSchema, patchOutputSchema, maximumStreamBytes, } from "./operation-contract.js";
+/** The packaged, pinned Codex engine owns patch parsing and the Workspace jail. */
+const nativePatch = {
+    executable: "/opt/fungi/fungi-apply-patch",
+    cwd: "/workspace",
+    timeoutMs: 30_000,
+    mismatchExitCode: 23,
+};
+function bounded(value) {
+    const bytes = new TextEncoder().encode(value);
+    return bytes.length <= maximumStreamBytes
+        ? { value, truncated: false }
+        : {
+            value: new TextDecoder().decode(bytes.slice(0, maximumStreamBytes)),
+            truncated: true,
+        };
+}
+/** Await Workspace synchronization even when the native engine reports a partial failure. */
+export async function applyWorkspacePatch(workspace, backend, input) {
+    const env_1 = { stack: [], error: void 0, hasError: false };
+    try {
+        const { patch } = patchInputSchema.parse(input);
+        const run = __addDisposableResource(env_1, await workspace.runtime.exec(nativePatch.executable, {
+            backend,
+            cwd: nativePatch.cwd,
+            encoding: "utf8",
+            stdin: patch,
+            timeoutMs: nativePatch.timeoutMs,
+        }), false);
+        const result = await run.result();
+        const synchronizationFailure = result.sync.status === "pending" ? result.sync.error : null;
+        const stdout = bounded(result.stdout);
+        const stderr = bounded(synchronizationFailure !== null
+            ? `${result.stderr}\nPatch filesystem synchronization failed: ${synchronizationFailure}. Earlier patch writes may remain.`
+            : result.stderr);
+        const output = {
+            status: synchronizationFailure !== null ? "failed" : result.status,
+            exitCode: synchronizationFailure !== null && result.exitCode === 0
+                ? 1
+                : result.exitCode,
+            stdout: stdout.value,
+            stderr: stderr.value,
+            truncated: stdout.truncated || stderr.truncated,
+        };
+        return patchOutputSchema.parse(result.exitCode === nativePatch.mismatchExitCode
+            ? { ...output, error: { kind: "mismatch" } }
+            : output);
+    }
+    catch (e_1) {
+        env_1.error = e_1;
+        env_1.hasError = true;
+    }
+    finally {
+        __disposeResources(env_1);
+    }
+}

package/dist/files.d.ts

@@ -0,0 +1,75 @@
+import type { SQLiteWorkspaceProvider, WorkspaceClient } from "@fungi.computer/cloudflare-computer";
+/** Files need only the Workspace filesystem, local or leased through a stub. */
+export type WorkspaceFiles = Pick<WorkspaceClient, "fs">;
+import { type ComputerFileReplacement, type ComputerFileReplacementResult } from "./operation-contract.js";
+export type WorkspaceFilesOwner = Readonly<{
+    replaceFileIfUnchanged: (input: ComputerFileReplacement) => Promise<ComputerFileReplacementResult>;
+}>;
+export type Utf8Page = Readonly<{
+    content: string;
+    byteLength: number;
+}>;
+/** Decode a bounded byte page without consuming an incomplete final UTF-8 character. */
+export declare function decodeUtf8Page(bytes: Uint8Array, path: string, moreBytesRemain: boolean): Utf8Page;
+/** Read raw bounded bytes without Workspace.fs's BOM-stripping UTF-8 path. */
+export declare function readBoundedWorkspaceText(provider: SQLiteWorkspaceProvider, path: string, maximumBytes: number): string;
+/** Adapt native Workspace.fs at the one real file boundary. */
+export declare function createWorkspaceFilesPort(workspace: WorkspaceFiles, owner: WorkspaceFilesOwner): Readonly<{
+    read(input: {
+        path: string;
+        offset: number;
+        limit: number;
+    }): Promise<{
+        path: string;
+        content: string;
+        offset: number;
+        nextOffset: number | null;
+        truncated: boolean;
+    }>;
+    list(input: {
+        path: string;
+        limit: number;
+    }): Promise<{
+        path: string;
+        entries: {
+            path: string;
+            name: string;
+            type: "file" | "directory" | "symlink";
+            size: number;
+            modifiedAt: number;
+        }[];
+        truncated: boolean;
+    }>;
+    glob(input: {
+        path: string;
+        pattern: string;
+        limit: number;
+    }): Promise<{
+        path: string;
+        matches: string[];
+        truncated: boolean;
+    }>;
+    grep(input: {
+        path: string;
+        pattern: string;
+        regex: boolean;
+        ignoreCase: boolean;
+        limit: number;
+    }): Promise<{
+        path: string;
+        matches: {
+            path: string;
+            line: number;
+            text: string;
+        }[];
+        truncated: boolean;
+    }>;
+    replace(input: Readonly<{
+        path: string;
+        expectedContent: string;
+        content: string;
+    }>): Promise<{
+        path: string;
+        bytes: number;
+    }>;
+}>;