@usine/cloudflare 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,96 @@
-# Temporary Holding Version
+# @usine/cloudflare
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Cloudflare Worker that runs each usine Attempt in its own sandbox, for `cloudflare` Workers in `usine.yaml` ([#551](https://github.com/basaltbytes/usine/issues/551)). You deploy it to your Cloudflare account; usine's executor calls it over HTTPS with a Cloudflare Access service token.
+
+Each sandbox is a Durable Object that owns one container, started from an image in the Worker's configuration with the [Durable Object Container API](https://developers.cloudflare.com/containers/api/durable-object-container/) and the [Sandbox SDK 1.0](https://developers.cloudflare.com/sandbox/). The container has no internet access. Its requests for GitHub, the LLM providers, and the allowlisted hosts go to outbound handlers in the Worker, which hold the Attempt's credentials, so the container never receives them:
+
+| Host in the sandbox | Handler | Upstream |
+| --- | --- | --- |
+| `github.com`, `api.github.com` over HTTPS | Adds the Attempt's installation token | GitHub |
+| `anthropic.usine.internal` over HTTP | Replaces the placeholder key with the Anthropic API key | `https://api.anthropic.com` |
+| `openai.usine.internal` over HTTP | Replaces the placeholder key with the OpenAI API key | `https://api.openai.com` |
+| Each host in `ALLOWED_HOSTS` over HTTPS | Forwards the request unchanged | The host |
+
+While a sandbox has no installation token or no key for a provider, such as a sandbox that the executor keeps after its Attempt, the handler for that host refuses every request with status 403. `ALLOWED_HOSTS` can't name a GitHub or provider host.
+
+A provider handler adds the key only to the requests that Claude Code and Codex send: Anthropic's `POST /v1/messages`, `POST /v1/messages/count_tokens`, and `GET /v1/models`, and OpenAI's `POST /v1/responses`, `POST /v1/responses/compact`, and `GET /v1/models`. These are the paths that the Gateway's `llm.<domain>` serves ([ADR 0027](../../docs/adr/0027-gateway-credential-proxy.md)), each with the method that the harnesses use. The handler refuses every other method and path, such as the files or organization administration APIs, with status 404, before it adds the key.
+
+HTTPS interception needs the container to trust Cloudflare's container certificate authority. The executor sets `GIT_SSL_CAINFO`, `CURL_CA_BUNDLE`, `SSL_CERT_FILE`, and `NODE_EXTRA_CA_CERTS` to it for every command, as Cloudflare's coding-agent runner does. Claude Code and Codex use plain HTTP to their handlers, with a placeholder key.
+
+## Entry points
+
+| Import | Contents |
+| --- | --- |
+| `@usine/cloudflare` | `SandboxApi`, the JSON API contract for `HttpApiClient.make` in the executor, with its records and errors, `sandboxName`, the Access header names, and the exec and attach stream paths. |
+| `@usine/cloudflare/stream` | The messages of the exec and attach WebSocket streams. |
+| `@usine/cloudflare/harness` | The environment that points git, gh, Claude Code, and Codex at the outbound handlers, and the sandbox paths. |
+| `src/worker.ts` | The Worker that `wrangler.jsonc` deploys: `AttemptSandbox`, `SandboxRegistry`, and the outbound handlers. It runs only on Cloudflare. |
+
+## The sandbox API
+
+Every request needs the `CF-Access-Client-Id` and `CF-Access-Client-Secret` headers of the service token that the Worker is configured with. The Worker refuses any other request with status 401.
+
+| Route | Purpose |
+| --- | --- |
+| `GET /v1/health` | The protocol version and the image names. |
+| `GET /v1/sandboxes?owner=<instance>.<worker>` | The sandboxes of one usine instance's Worker, each with whether its container runs. |
+| `PUT /v1/sandboxes/<name>` | Creates the sandbox of an Attempt, or returns it if it already runs that Attempt. |
+| `GET /v1/sandboxes/<name>` | One sandbox. |
+| `PUT /v1/sandboxes/<name>/credentials` | Replaces the handlers' credentials, such as a renewed installation token, or revokes them with none. |
+| `POST /v1/sandboxes/<name>/hold` | Keeps the container running past its lease until the sandbox is destroyed. |
+| `POST /v1/sandboxes/<name>/stop` | Stops every command that still runs in the sandbox, and every process that a command left running. |
+| `DELETE /v1/sandboxes/<name>` | Destroys the container and forgets the sandbox. |
+| `GET /v1/sandboxes/<name>/processes/<process>` | A command's state and output size, from its process files. |
+| `GET /v1/sandboxes/<name>/exec` (WebSocket) | Runs one command with `sh -c`, with its stdin, stdout, stderr, and exit code on the stream. |
+| `GET /v1/sandboxes/<name>/processes/<process>/attach?stdout=<n>&stderr=<n>` (WebSocket) | Resumes a command's output after the given byte offsets, then sends its exit code. |
+
+Each command runs as the `usine` user in `/home/usine`, with `HOME` set, since the platform passes a command only the image's `PATH`. It runs in its own session, with its process ID, output, and exit code in files under `/home/usine/.usine/processes/<process>`. If the stream that started a command closes, the command's stdin closes, and its output keeps going to the files, so a later request can attach or read its state. The Worker closes the stream without an exit code when it can't read the command's output or exit code from the container, so the client attaches from the bytes it received.
+
+A command, and every process that it starts, gets `USINE_PROCESS`, the command's process directory, in its environment. A stop sends TERM to every process in each command's session, and in the session of each process with `USINE_PROCESS`, so it includes what a command left running after it exited. Five seconds later, it sends KILL to the processes that still run. It fails if a process still runs five seconds after that, so usine doesn't salvage or reattach a checkout that a process can still change. A process that leaves its command's session and also drops `USINE_PROCESS` from its environment isn't stopped.
+
+Each set of credentials carries `issuedAt`, the time usine issued it. A sandbox applies one create or credential change at a time, and refuses credentials issued before the ones it holds with status 409 and `StaleCredentials`. A renewal that's still on its way when usine revokes the credentials therefore can't restore them.
+
+A keepalive alarm keeps the container running for two hours after the last create, credential renewal, or command, then lets the platform stop it after ten minutes of inactivity. A held sandbox keeps running until it's destroyed: usine holds the sandbox of a checkout that it keeps, such as one with unpushed work. A stopped container loses its disk.
+
+When Cloudflare restarts a host or replaces an instance, it sends the container SIGTERM and stops it up to 15 minutes later. The image's init (`image/init.sh`) writes the time to `/home/usine/.usine/draining` and keeps the container running, and each sandbox summary reports `draining` while the file exists. The executor then drains the Attempt: it salvages the checkout and destroys the sandbox before the container stops.
+
+## Deploy
+
+You need a Cloudflare account with Workers Paid, which Containers require, and [Wrangler](https://developers.cloudflare.com/workers/wrangler/) logged in to it. The image is linux/amd64; Wrangler builds it with your local Docker.
+
+1. In a usine checkout, build the Worker:
+
+   ```sh
+   pnpm install
+   pnpm --filter @usine/cloudflare... build
+   cd packages/cloudflare
+   ```
+
+2. In `wrangler.jsonc`, set `name` to your Worker's name, and set `ALLOWED_HOSTS` to the package registries your repositories install from.
+
+3. Create a Cloudflare Access service token in Zero Trust under **Access** > **Service credentials** > **Service Tokens**, and store its client ID and client secret on the Worker:
+
+   ```sh
+   npx wrangler secret put ACCESS_CLIENT_ID
+   npx wrangler secret put ACCESS_CLIENT_SECRET
+   ```
+
+   To also check the token at Cloudflare's edge, add an Access application for the Worker's hostname with a Service Auth policy that allows that token.
+
+4. Deploy the Worker and its image:
+
+   ```sh
+   npx wrangler deploy
+   ```
+
+   The containers use the `durable_object` scheduling policy, which Wrangler can't undo for the application.
+
+5. Add the Worker to `usine.yaml`, and set the token and the provider keys in the orchestrator's environment. See [Run attempts on Cloudflare](https://docs.usine.dev/guides/cloudflare-sandboxes/).
+
+## EU placement
+
+The Sandbox SDK 1.0 needs the `durable_object` scheduling policy, which rejects placement constraints, including `jurisdiction: "eu"`. Containers can't be kept in the EU until Cloudflare adds placement to that policy.
+
+## Develop
+
+`pnpm test` runs unit tests in Node: the routes and streams against fake ports, and the process file scripts with the local `sh`. The Durable Object's container calls need Cloudflare's container runtime, so no test runs the Worker itself.

package/dist/access.d.ts

@@ -0,0 +1,12 @@
+import { Effect, Redacted } from "effect";
+/** The Cloudflare Access service token that the Worker accepts. */
+export interface AccessToken {
+    readonly clientId: Redacted.Redacted<string>;
+    readonly clientSecret: Redacted.Redacted<string>;
+}
+/**
+ * Returns whether `headers` carry `token` in the Access service token headers. A request
+ * without either header is refused.
+ */
+export declare const accessGranted: (headers: Headers, token: AccessToken) => Effect.Effect<boolean, never, never>;
+//# sourceMappingURL=access.d.ts.map

package/dist/access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAG1C,mEAAmE;AACnE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC7C,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;CAClD;AAiBD;;;GAGG;AACH,eAAO,MAAM,aAAa,gFAiBxB,CAAC"}

package/dist/access.js

@@ -0,0 +1,32 @@
+import { Effect, Redacted } from "effect";
+import { ACCESS_CLIENT_ID_HEADER, ACCESS_CLIENT_SECRET_HEADER } from "./api/api.js";
+const encoder = new TextEncoder();
+const digest = (value) => Effect.promise(() => crypto.subtle.digest("SHA-256", encoder.encode(value))).pipe(Effect.map((bytes) => new Uint8Array(bytes)));
+/** Returns whether two digests are equal, in constant time. */
+const sameDigest = (left, right) => {
+    let difference = left.length ^ right.length;
+    for (let index = 0; index < Math.min(left.length, right.length); index++)
+        difference |= (left[index] ?? 0) ^ (right[index] ?? 0);
+    return difference === 0;
+};
+/**
+ * Returns whether `headers` carry `token` in the Access service token headers. A request
+ * without either header is refused.
+ */
+export const accessGranted = Effect.fn("SandboxWorker.accessGranted")(function* (headers, token) {
+    const clientId = headers.get(ACCESS_CLIENT_ID_HEADER);
+    const clientSecret = headers.get(ACCESS_CLIENT_SECRET_HEADER);
+    if (clientId === null || clientSecret === null)
+        return false;
+    const [presentedId, presentedSecret, expectedId, expectedSecret] = yield* Effect.all([
+        digest(clientId),
+        digest(clientSecret),
+        digest(Redacted.value(token.clientId)),
+        digest(Redacted.value(token.clientSecret)),
+    ]);
+    // Both comparisons run, so the response time doesn't tell which header was wrong.
+    const idMatches = sameDigest(presentedId, expectedId);
+    const secretMatches = sameDigest(presentedSecret, expectedSecret);
+    return idMatches && secretMatches;
+});
+//# sourceMappingURL=access.js.map

package/dist/access.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.js","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAC1C,OAAO,EAAE,uBAAuB,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAQpF,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;AAElC,MAAM,MAAM,GAAG,CAAC,KAAa,EAAE,EAAE,CAC/B,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAC/E,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,CAC7C,CAAC;AAEJ,+DAA+D;AAC/D,MAAM,UAAU,GAAG,CAAC,IAAgB,EAAE,KAAiB,EAAW,EAAE;IAClE,IAAI,UAAU,GAAG,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC5C,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE;QACtE,UAAU,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IACzD,OAAO,UAAU,KAAK,CAAC,CAAC;AAC1B,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC,EAAE,CAAC,6BAA6B,CAAC,CAAC,QAAQ,CAAC,EAC7E,OAAgB,EAChB,KAAkB;IAElB,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;IACtD,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;IAC9D,IAAI,QAAQ,KAAK,IAAI,IAAI,YAAY,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC7D,MAAM,CAAC,WAAW,EAAE,eAAe,EAAE,UAAU,EAAE,cAAc,CAAC,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;QACnF,MAAM,CAAC,QAAQ,CAAC;QAChB,MAAM,CAAC,YAAY,CAAC;QACpB,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACtC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;KAC3C,CAAC,CAAC;IACH,kFAAkF;IAClF,MAAM,SAAS,GAAG,UAAU,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;IACtD,MAAM,aAAa,GAAG,UAAU,CAAC,eAAe,EAAE,cAAc,CAAC,CAAC;IAClE,OAAO,SAAS,IAAI,aAAa,CAAC;AACpC,CAAC,CAAC,CAAC"}

package/dist/api/api.d.ts

@@ -0,0 +1,215 @@
+import { AttemptId } from "@usine/core/attempt";
+import { type WorkerName } from "@usine/core/worker";
+import { Schema } from "effect";
+import { HttpApi, HttpApiEndpoint, HttpApiGroup } from "effect/http-api";
+import { SandboxName, SandboxOwner } from "./names.ts";
+export { ACCESS_CLIENT_ID_HEADER, ACCESS_CLIENT_SECRET_HEADER, attachPath, execPath, ProcessId, SandboxName, SandboxOwner, } from "./names.ts";
+/** The version of the sandbox API and the exec stream, reported by `/v1/health`. */
+export declare const SANDBOX_PROTOCOL = 1;
+/**
+ * Returns the owner of the sandboxes that `instance` runs for `worker`. Throws if `instance` isn't
+ * in kebab case.
+ */
+export declare const sandboxOwner: (instance: string, worker: WorkerName) => SandboxOwner;
+/** Returns the name of the sandbox that runs `attempt` for `owner`. */
+export declare const sandboxName: (owner: SandboxOwner, attempt: AttemptId) => SandboxName;
+declare const ApiKeyCredential_base: Schema.Class<ApiKeyCredential, Schema.TaggedStruct<"ApiKey", {
+    readonly key: Schema.Redacted<Schema.NonEmptyString>;
+}>, {}>;
+/** An API key that the provider's outbound handler sends in place of the sandbox's placeholder. */
+export declare class ApiKeyCredential extends ApiKeyCredential_base {
+}
+/**
+ * How a provider's outbound handler authenticates the sandbox's requests. Only API keys exist;
+ * a brokered login (#549) would be another member.
+ */
+export declare const ProviderCredential: Schema.Union<readonly [typeof ApiKeyCredential]>;
+export type ProviderCredential = typeof ProviderCredential.Type;
+declare const ProviderGrant_base: Schema.Class<ProviderGrant, Schema.Struct<{
+    readonly provider: Schema.Literals<readonly ["anthropic", "openai"]>;
+    readonly credential: Schema.Union<readonly [typeof ApiKeyCredential]>;
+}>, {}>;
+export declare class ProviderGrant extends ProviderGrant_base {
+}
+declare const SandboxCredentials_base: Schema.Class<SandboxCredentials, Schema.Struct<{
+    /**
+     * When usine issued these credentials, later than any credentials it issued before. The sandbox
+     * refuses credentials issued before the ones it holds, so a delayed request can't restore
+     * credentials that a later request replaced or revoked.
+     */
+    readonly issuedAt: Schema.DateTimeUtc;
+    /** The Attempt's installation token, added to requests for `github.com` and `api.github.com`. */
+    readonly github: Schema.OptionFromOptionalKey<Schema.Redacted<Schema.NonEmptyString>>;
+    readonly providers: Schema.$Array<typeof ProviderGrant>;
+}>, {}>;
+/**
+ * The secrets that a sandbox's outbound handlers hold. The container never receives them. A host
+ * without a credential is refused, so replacing the credentials with none revokes them.
+ */
+export declare class SandboxCredentials extends SandboxCredentials_base {
+}
+declare const CreateSandbox_base: Schema.Class<CreateSandbox, Schema.Struct<{
+    readonly owner: Schema.brand<Schema.String, "SandboxOwner">;
+    readonly attempt: Schema.brand<Schema.NonEmptyString, "AttemptId">;
+    readonly image: Schema.brand<Schema.String, "CloudflareImageName">;
+    readonly instanceType: Schema.Literals<readonly ["lite", "basic", "standard-1", "standard-2", "standard-3", "standard-4"]>;
+    readonly credentials: typeof SandboxCredentials;
+}>, {}>;
+/** A request to create the sandbox for one Attempt, or to return it if it already runs that Attempt. */
+export declare class CreateSandbox extends CreateSandbox_base {
+}
+declare const SandboxSummary_base: Schema.Class<SandboxSummary, Schema.Struct<{
+    readonly name: Schema.brand<Schema.String, "SandboxName">;
+    readonly owner: Schema.brand<Schema.String, "SandboxOwner">;
+    readonly attempt: Schema.brand<Schema.NonEmptyString, "AttemptId">;
+    readonly image: Schema.brand<Schema.String, "CloudflareImageName">;
+    readonly instanceType: Schema.Literals<readonly ["lite", "basic", "standard-1", "standard-2", "standard-3", "standard-4"]>;
+    readonly createdAt: Schema.DateTimeUtc;
+    /** Whether the container runs. A container that stopped lost its disk. */
+    readonly running: Schema.Boolean;
+    /**
+     * Whether usine holds the sandbox: the keepalive alarm keeps its container running past the
+     * lease, until usine reconciles or destroys it, because it keeps a checkout.
+     */
+    readonly held: Schema.Boolean;
+    /**
+     * Whether the platform sent the container SIGTERM. It stops the container within 15 minutes, and
+     * a container that starts again has an empty disk.
+     */
+    readonly draining: Schema.Boolean;
+}>, {}>;
+export declare class SandboxSummary extends SandboxSummary_base {
+}
+declare const SandboxList_base: Schema.Class<SandboxList, Schema.Struct<{
+    readonly sandboxes: Schema.$Array<typeof SandboxSummary>;
+}>, {}>;
+export declare class SandboxList extends SandboxList_base {
+}
+declare const HealthReport_base: Schema.Class<HealthReport, Schema.Struct<{
+    readonly protocol: Schema.Literal<1>;
+    /** The names in the Worker's `containers[].images`. */
+    readonly images: Schema.$Array<Schema.brand<Schema.String, "CloudflareImageName">>;
+}>, {}>;
+export declare class HealthReport extends HealthReport_base {
+}
+declare const Stopped_base: Schema.Class<Stopped, Schema.Struct<{
+    readonly stopped: Schema.Int;
+}>, {}>;
+/** The response to a stop: the number of commands that were still running. */
+export declare class Stopped extends Stopped_base {
+}
+declare const Destroyed_base: Schema.Class<Destroyed, Schema.Struct<{
+    readonly destroyed: Schema.Boolean;
+}>, {}>;
+/** The response to a destroy. `destroyed` is whether the sandbox existed. */
+export declare class Destroyed extends Destroyed_base {
+}
+declare const ProcessRunning_base: Schema.Class<ProcessRunning, Schema.TaggedStruct<"Running", {}>, {}>;
+export declare class ProcessRunning extends ProcessRunning_base {
+}
+declare const ProcessExited_base: Schema.Class<ProcessExited, Schema.TaggedStruct<"Exited", {
+    readonly exitCode: Schema.Int;
+}>, {}>;
+export declare class ProcessExited extends ProcessExited_base {
+}
+export declare const ProcessState: Schema.Union<readonly [typeof ProcessRunning, typeof ProcessExited]>;
+export type ProcessState = typeof ProcessState.Type;
+declare const ProcessStatus_base: Schema.Class<ProcessStatus, Schema.Struct<{
+    readonly process: Schema.brand<Schema.String, "ProcessId">;
+    /** The command's process ID in the container. */
+    readonly pid: Schema.Int;
+    readonly state: Schema.Union<readonly [typeof ProcessRunning, typeof ProcessExited]>;
+    readonly stdoutBytes: Schema.Int;
+    readonly stderrBytes: Schema.Int;
+}>, {}>;
+/** A command's state and output size, read from its process files. */
+export declare class ProcessStatus extends ProcessStatus_base {
+}
+declare const SandboxNotFound_base: Schema.Class<SandboxNotFound, Schema.TaggedStruct<"SandboxNotFound", {
+    readonly name: Schema.brand<Schema.String, "SandboxName">;
+}>, import("effect/Cause").YieldableError>;
+export declare class SandboxNotFound extends SandboxNotFound_base {
+}
+declare const SandboxConflict_base: Schema.Class<SandboxConflict, Schema.TaggedStruct<"SandboxConflict", {
+    readonly name: Schema.brand<Schema.String, "SandboxName">;
+    readonly owner: Schema.brand<Schema.String, "SandboxOwner">;
+    readonly attempt: Schema.brand<Schema.NonEmptyString, "AttemptId">;
+}>, import("effect/Cause").YieldableError>;
+/** The sandbox exists for another owner or Attempt. */
+export declare class SandboxConflict extends SandboxConflict_base {
+}
+declare const StaleCredentials_base: Schema.Class<StaleCredentials, Schema.TaggedStruct<"StaleCredentials", {
+    readonly name: Schema.brand<Schema.String, "SandboxName">;
+    readonly issuedAt: Schema.DateTimeUtc;
+    readonly current: Schema.DateTimeUtc;
+}>, import("effect/Cause").YieldableError>;
+/** The sandbox holds credentials issued at `current`, after the request's, which it refused. */
+export declare class StaleCredentials extends StaleCredentials_base {
+}
+declare const ImageNotFound_base: Schema.Class<ImageNotFound, Schema.TaggedStruct<"ImageNotFound", {
+    readonly image: Schema.brand<Schema.String, "CloudflareImageName">;
+    readonly images: Schema.$Array<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/** The Worker's `containers[].images` has no image with this name. */
+export declare class ImageNotFound extends ImageNotFound_base {
+}
+declare const ProcessNotFound_base: Schema.Class<ProcessNotFound, Schema.TaggedStruct<"ProcessNotFound", {
+    readonly name: Schema.brand<Schema.String, "SandboxName">;
+    readonly process: Schema.brand<Schema.String, "ProcessId">;
+}>, import("effect/Cause").YieldableError>;
+export declare class ProcessNotFound extends ProcessNotFound_base {
+}
+declare const ContainerUnavailable_base: Schema.Class<ContainerUnavailable, Schema.TaggedStruct<"ContainerUnavailable", {
+    readonly name: Schema.brand<Schema.String, "SandboxName">;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The container didn't start, stopped, or failed a command. `message` comes from the runtime. */
+export declare class ContainerUnavailable extends ContainerUnavailable_base {
+}
+/** `GET /v1/health`, served by any sandbox Durable Object. */
+export declare const healthGroup: HttpApiGroup.HttpApiGroup<"health", HttpApiEndpoint.HttpApiEndpoint<"health", "GET", "/v1/health", never, never, never, never, Schema.toCodecJson<typeof HealthReport>, never, never, never>, false>;
+/** `GET /v1/sandboxes`, served by the registry Durable Object. */
+export declare const registryGroup: HttpApiGroup.HttpApiGroup<"registry", HttpApiEndpoint.HttpApiEndpoint<"list", "GET", "/v1/sandboxes", never, Schema.toCodecStringTree<Schema.Struct<{
+    owner: Schema.brand<Schema.String, "SandboxOwner">;
+}>>, never, never, Schema.toCodecJson<typeof SandboxList>, never, never, never>, false>;
+/** The routes of one sandbox, served by its Durable Object. */
+export declare const sandboxGroup: HttpApiGroup.HttpApiGroup<"sandbox", HttpApiEndpoint.HttpApiEndpoint<"create", "PUT", "/v1/sandboxes/:name", Schema.toCodecStringTree<Schema.Struct<{
+    name: Schema.brand<Schema.String, "SandboxName">;
+}>>, never, Schema.toCodecJson<typeof CreateSandbox>, never, Schema.toCodecJson<typeof SandboxSummary>, Schema.toCodecJson<typeof SandboxConflict | typeof StaleCredentials | typeof ImageNotFound | typeof ContainerUnavailable>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"credentials", "PUT", "/v1/sandboxes/:name/credentials", Schema.toCodecStringTree<Schema.Struct<{
+    name: Schema.brand<Schema.String, "SandboxName">;
+}>>, never, Schema.toCodecJson<typeof SandboxCredentials>, never, Schema.toCodecJson<typeof SandboxSummary>, Schema.toCodecJson<typeof SandboxNotFound | typeof StaleCredentials | typeof ContainerUnavailable>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"destroy", "DELETE", "/v1/sandboxes/:name", Schema.toCodecStringTree<Schema.Struct<{
+    name: Schema.brand<Schema.String, "SandboxName">;
+}>>, never, never, never, Schema.toCodecJson<typeof Destroyed>, Schema.toCodecJson<typeof ContainerUnavailable>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"get", "GET", "/v1/sandboxes/:name", Schema.toCodecStringTree<Schema.Struct<{
+    name: Schema.brand<Schema.String, "SandboxName">;
+}>>, never, never, never, Schema.toCodecJson<typeof SandboxSummary>, Schema.toCodecJson<typeof SandboxNotFound>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"hold", "POST", "/v1/sandboxes/:name/hold", Schema.toCodecStringTree<Schema.Struct<{
+    name: Schema.brand<Schema.String, "SandboxName">;
+}>>, never, never, never, Schema.toCodecJson<typeof SandboxSummary>, Schema.toCodecJson<typeof SandboxNotFound | typeof ContainerUnavailable>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"process", "GET", "/v1/sandboxes/:name/processes/:process", Schema.toCodecStringTree<Schema.Struct<{
+    name: Schema.brand<Schema.String, "SandboxName">;
+    process: Schema.brand<Schema.String, "ProcessId">;
+}>>, never, never, never, Schema.toCodecJson<typeof ProcessStatus>, Schema.toCodecJson<typeof SandboxNotFound | typeof ProcessNotFound | typeof ContainerUnavailable>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"stop", "POST", "/v1/sandboxes/:name/stop", Schema.toCodecStringTree<Schema.Struct<{
+    name: Schema.brand<Schema.String, "SandboxName">;
+}>>, never, never, never, Schema.toCodecJson<typeof Stopped>, Schema.toCodecJson<typeof SandboxNotFound | typeof ContainerUnavailable>, never, never>, false>;
+/**
+ * The JSON API of the Worker that usine ships (`@usine/cloudflare/worker`). Every request carries
+ * the Access service token headers. Commands run through the exec stream at `execPath`, not
+ * through this API.
+ */
+export declare const SandboxApi: HttpApi.HttpApi<"SandboxApi", HttpApiGroup.HttpApiGroup<"health", HttpApiEndpoint.HttpApiEndpoint<"health", "GET", "/v1/health", never, never, never, never, Schema.toCodecJson<typeof HealthReport>, never, never, never>, false> | HttpApiGroup.HttpApiGroup<"registry", HttpApiEndpoint.HttpApiEndpoint<"list", "GET", "/v1/sandboxes", never, Schema.toCodecStringTree<Schema.Struct<{
+    owner: Schema.brand<Schema.String, "SandboxOwner">;
+}>>, never, never, Schema.toCodecJson<typeof SandboxList>, never, never, never>, false> | HttpApiGroup.HttpApiGroup<"sandbox", HttpApiEndpoint.HttpApiEndpoint<"create", "PUT", "/v1/sandboxes/:name", Schema.toCodecStringTree<Schema.Struct<{
+    name: Schema.brand<Schema.String, "SandboxName">;
+}>>, never, Schema.toCodecJson<typeof CreateSandbox>, never, Schema.toCodecJson<typeof SandboxSummary>, Schema.toCodecJson<typeof SandboxConflict | typeof StaleCredentials | typeof ImageNotFound | typeof ContainerUnavailable>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"credentials", "PUT", "/v1/sandboxes/:name/credentials", Schema.toCodecStringTree<Schema.Struct<{
+    name: Schema.brand<Schema.String, "SandboxName">;
+}>>, never, Schema.toCodecJson<typeof SandboxCredentials>, never, Schema.toCodecJson<typeof SandboxSummary>, Schema.toCodecJson<typeof SandboxNotFound | typeof StaleCredentials | typeof ContainerUnavailable>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"destroy", "DELETE", "/v1/sandboxes/:name", Schema.toCodecStringTree<Schema.Struct<{
+    name: Schema.brand<Schema.String, "SandboxName">;
+}>>, never, never, never, Schema.toCodecJson<typeof Destroyed>, Schema.toCodecJson<typeof ContainerUnavailable>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"get", "GET", "/v1/sandboxes/:name", Schema.toCodecStringTree<Schema.Struct<{
+    name: Schema.brand<Schema.String, "SandboxName">;
+}>>, never, never, never, Schema.toCodecJson<typeof SandboxSummary>, Schema.toCodecJson<typeof SandboxNotFound>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"hold", "POST", "/v1/sandboxes/:name/hold", Schema.toCodecStringTree<Schema.Struct<{
+    name: Schema.brand<Schema.String, "SandboxName">;
+}>>, never, never, never, Schema.toCodecJson<typeof SandboxSummary>, Schema.toCodecJson<typeof SandboxNotFound | typeof ContainerUnavailable>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"process", "GET", "/v1/sandboxes/:name/processes/:process", Schema.toCodecStringTree<Schema.Struct<{
+    name: Schema.brand<Schema.String, "SandboxName">;
+    process: Schema.brand<Schema.String, "ProcessId">;
+}>>, never, never, never, Schema.toCodecJson<typeof ProcessStatus>, Schema.toCodecJson<typeof SandboxNotFound | typeof ProcessNotFound | typeof ContainerUnavailable>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"stop", "POST", "/v1/sandboxes/:name/stop", Schema.toCodecStringTree<Schema.Struct<{
+    name: Schema.brand<Schema.String, "SandboxName">;
+}>>, never, never, never, Schema.toCodecJson<typeof Stopped>, Schema.toCodecJson<typeof SandboxNotFound | typeof ContainerUnavailable>, never, never>, false>>;
+//# sourceMappingURL=api.d.ts.map

package/dist/api/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/api/api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEhD,OAAO,EAIL,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACzE,OAAO,EAAa,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAElE,OAAO,EACL,uBAAuB,EACvB,2BAA2B,EAC3B,UAAU,EACV,QAAQ,EACR,SAAS,EACT,WAAW,EACX,YAAY,GACb,MAAM,YAAY,CAAC;AAEpB,oFAAoF;AACpF,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC;;;GAGG;AACH,eAAO,MAAM,YAAY,aAAc,MAAM,UAAU,UAAU,KAAG,YACxB,CAAC;AAE7C,uEAAuE;AACvE,eAAO,MAAM,WAAW,UAAW,YAAY,WAAW,SAAS,KAAG,WAChB,CAAC;;;;AAEvD,mGAAmG;AACnG,qBAAa,gBAAiB,SAAQ,qBAEpC;CAAG;AAEL;;;GAGG;AACH,eAAO,MAAM,kBAAkB,kDAAmC,CAAC;AACnE,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC,IAAI,CAAC;;;;;AAEhE,qBAAa,aAAc,SAAQ,kBAGjC;CAAG;;IAcH;;;;OAIG;;IAEH,iGAAiG;;;;AAbnG;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,uBAYtC;CAAG;;;;;;;;AAEL,wGAAwG;AACxG,qBAAa,aAAc,SAAQ,kBAMjC;CAAG;;;;;;;;IAWH,0EAA0E;;IAE1E;;;OAGG;;IAEH;;;OAGG;;;AAnBL,qBAAa,cAAe,SAAQ,mBAqBlC;CAAG;;;;AAEL,qBAAa,WAAY,SAAQ,gBAE/B;CAAG;;;IAIH,uDAAuD;;;AAFzD,qBAAa,YAAa,SAAQ,iBAIhC;CAAG;;;;AAEL,8EAA8E;AAC9E,qBAAa,OAAQ,SAAQ,YAE3B;CAAG;;;;AAEL,6EAA6E;AAC7E,qBAAa,SAAU,SAAQ,cAE7B;CAAG;;AAEL,qBAAa,cAAe,SAAQ,mBAAmD;CAAG;;;;AAE1F,qBAAa,aAAc,SAAQ,kBAEjC;CAAG;AAEL,eAAO,MAAM,YAAY,sEAAgD,CAAC;AAC1E,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAC;;;IAKlD,iDAAiD;;;;;;AAHnD,sEAAsE;AACtE,qBAAa,aAAc,SAAQ,kBAOjC;CAAG;;;;AAEL,qBAAa,eAAgB,SAAQ,oBAIpC;CAAG;;;;;;AAEJ,uDAAuD;AACvD,qBAAa,eAAgB,SAAQ,oBAIpC;CAAG;;;;;;AAEJ,gGAAgG;AAChG,qBAAa,gBAAiB,SAAQ,qBAIrC;CAAG;;;;;AAEJ,sEAAsE;AACtE,qBAAa,aAAc,SAAQ,kBAIlC;CAAG;;;;;AAEJ,qBAAa,eAAgB,SAAQ,oBAIpC;CAAG;;;;;AAEJ,kGAAkG;AAClG,qBAAa,oBAAqB,SAAQ,yBAIzC;CAAG;AAIJ,8DAA8D;AAC9D,eAAO,MAAM,WAAW,sMAEvB,CAAC;AAEF,kEAAkE;AAClE,eAAO,MAAM,aAAa;;uFAKzB,CAAC;AAEF,+DAA+D;AAC/D,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;6JAwC8C,CAAC;AAExE;;;;GAIG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;8JAA2E,CAAC"}

package/dist/api/api.js

@@ -0,0 +1,180 @@
+import { AttemptId } from "@usine/core/attempt";
+import { safeSegment } from "@usine/core/repository";
+import { CloudflareImageName, CloudflareInstanceType, CloudflareLlmProvider, } from "@usine/core/worker";
+import { Schema } from "effect";
+import { HttpApi, HttpApiEndpoint, HttpApiGroup } from "effect/http-api";
+import { ProcessId, SandboxName, SandboxOwner } from "./names.js";
+export { ACCESS_CLIENT_ID_HEADER, ACCESS_CLIENT_SECRET_HEADER, attachPath, execPath, ProcessId, SandboxName, SandboxOwner, } from "./names.js";
+/** The version of the sandbox API and the exec stream, reported by `/v1/health`. */
+export const SANDBOX_PROTOCOL = 1;
+/**
+ * Returns the owner of the sandboxes that `instance` runs for `worker`. Throws if `instance` isn't
+ * in kebab case.
+ */
+export const sandboxOwner = (instance, worker) => SandboxOwner.make(`${instance}.${worker}`);
+/** Returns the name of the sandbox that runs `attempt` for `owner`. */
+export const sandboxName = (owner, attempt) => SandboxName.make(`${owner}.${safeSegment(attempt)}`);
+/** An API key that the provider's outbound handler sends in place of the sandbox's placeholder. */
+export class ApiKeyCredential extends Schema.TaggedClass()("ApiKey", {
+    key: Schema.Redacted(Schema.NonEmptyString),
+}) {
+}
+/**
+ * How a provider's outbound handler authenticates the sandbox's requests. Only API keys exist;
+ * a brokered login (#549) would be another member.
+ */
+export const ProviderCredential = Schema.Union([ApiKeyCredential]);
+export class ProviderGrant extends Schema.Class("@usine/cloudflare/ProviderGrant")({
+    provider: CloudflareLlmProvider,
+    credential: ProviderCredential,
+}) {
+}
+const uniqueProviders = Schema.makeFilter((grants) => new Set(grants.map(({ provider }) => provider)).size === grants.length, { message: "Expected each provider once" });
+/**
+ * The secrets that a sandbox's outbound handlers hold. The container never receives them. A host
+ * without a credential is refused, so replacing the credentials with none revokes them.
+ */
+export class SandboxCredentials extends Schema.Class("@usine/cloudflare/SandboxCredentials")({
+    /**
+     * When usine issued these credentials, later than any credentials it issued before. The sandbox
+     * refuses credentials issued before the ones it holds, so a delayed request can't restore
+     * credentials that a later request replaced or revoked.
+     */
+    issuedAt: Schema.DateTimeUtc,
+    /** The Attempt's installation token, added to requests for `github.com` and `api.github.com`. */
+    github: Schema.OptionFromOptionalKey(Schema.Redacted(Schema.NonEmptyString)),
+    providers: Schema.Array(ProviderGrant).check(uniqueProviders),
+}) {
+}
+/** A request to create the sandbox for one Attempt, or to return it if it already runs that Attempt. */
+export class CreateSandbox extends Schema.Class("@usine/cloudflare/CreateSandbox")({
+    owner: SandboxOwner,
+    attempt: AttemptId,
+    image: CloudflareImageName,
+    instanceType: CloudflareInstanceType,
+    credentials: SandboxCredentials,
+}) {
+}
+export class SandboxSummary extends Schema.Class("@usine/cloudflare/SandboxSummary")({
+    name: SandboxName,
+    owner: SandboxOwner,
+    attempt: AttemptId,
+    image: CloudflareImageName,
+    instanceType: CloudflareInstanceType,
+    createdAt: Schema.DateTimeUtc,
+    /** Whether the container runs. A container that stopped lost its disk. */
+    running: Schema.Boolean,
+    /**
+     * Whether usine holds the sandbox: the keepalive alarm keeps its container running past the
+     * lease, until usine reconciles or destroys it, because it keeps a checkout.
+     */
+    held: Schema.Boolean,
+    /**
+     * Whether the platform sent the container SIGTERM. It stops the container within 15 minutes, and
+     * a container that starts again has an empty disk.
+     */
+    draining: Schema.Boolean,
+}) {
+}
+export class SandboxList extends Schema.Class("@usine/cloudflare/SandboxList")({
+    sandboxes: Schema.Array(SandboxSummary),
+}) {
+}
+export class HealthReport extends Schema.Class("@usine/cloudflare/HealthReport")({
+    protocol: Schema.Literal(SANDBOX_PROTOCOL),
+    /** The names in the Worker's `containers[].images`. */
+    images: Schema.Array(CloudflareImageName),
+}) {
+}
+/** The response to a stop: the number of commands that were still running. */
+export class Stopped extends Schema.Class("@usine/cloudflare/Stopped")({
+    stopped: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+}) {
+}
+/** The response to a destroy. `destroyed` is whether the sandbox existed. */
+export class Destroyed extends Schema.Class("@usine/cloudflare/Destroyed")({
+    destroyed: Schema.Boolean,
+}) {
+}
+export class ProcessRunning extends Schema.TaggedClass()("Running", {}) {
+}
+export class ProcessExited extends Schema.TaggedClass()("Exited", {
+    exitCode: Schema.Int,
+}) {
+}
+export const ProcessState = Schema.Union([ProcessRunning, ProcessExited]);
+/** A command's state and output size, read from its process files. */
+export class ProcessStatus extends Schema.Class("@usine/cloudflare/ProcessStatus")({
+    process: ProcessId,
+    /** The command's process ID in the container. */
+    pid: Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)),
+    state: ProcessState,
+    stdoutBytes: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+    stderrBytes: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+}) {
+}
+export class SandboxNotFound extends Schema.TaggedError()("SandboxNotFound", { name: SandboxName }, { httpApiStatus: 404 }) {
+}
+/** The sandbox exists for another owner or Attempt. */
+export class SandboxConflict extends Schema.TaggedError()("SandboxConflict", { name: SandboxName, owner: SandboxOwner, attempt: AttemptId }, { httpApiStatus: 409 }) {
+}
+/** The sandbox holds credentials issued at `current`, after the request's, which it refused. */
+export class StaleCredentials extends Schema.TaggedError()("StaleCredentials", { name: SandboxName, issuedAt: Schema.DateTimeUtc, current: Schema.DateTimeUtc }, { httpApiStatus: 409 }) {
+}
+/** The Worker's `containers[].images` has no image with this name. */
+export class ImageNotFound extends Schema.TaggedError()("ImageNotFound", { image: CloudflareImageName, images: Schema.Array(Schema.String) }, { httpApiStatus: 422 }) {
+}
+export class ProcessNotFound extends Schema.TaggedError()("ProcessNotFound", { name: SandboxName, process: ProcessId }, { httpApiStatus: 404 }) {
+}
+/** The container didn't start, stopped, or failed a command. `message` comes from the runtime. */
+export class ContainerUnavailable extends Schema.TaggedError()("ContainerUnavailable", { name: SandboxName, message: Schema.String }, { httpApiStatus: 503 }) {
+}
+const sandbox = { name: SandboxName };
+/** `GET /v1/health`, served by any sandbox Durable Object. */
+export const healthGroup = HttpApiGroup.make("health").add(HttpApiEndpoint.get("health", "/v1/health", { success: HealthReport }));
+/** `GET /v1/sandboxes`, served by the registry Durable Object. */
+export const registryGroup = HttpApiGroup.make("registry").add(HttpApiEndpoint.get("list", "/v1/sandboxes", {
+    query: { owner: SandboxOwner },
+    success: SandboxList,
+}));
+/** The routes of one sandbox, served by its Durable Object. */
+export const sandboxGroup = HttpApiGroup.make("sandbox")
+    .add(HttpApiEndpoint.put("create", "/v1/sandboxes/:name", {
+    params: sandbox,
+    payload: CreateSandbox,
+    success: SandboxSummary,
+    error: [SandboxConflict, StaleCredentials, ImageNotFound, ContainerUnavailable],
+}), HttpApiEndpoint.get("get", "/v1/sandboxes/:name", {
+    params: sandbox,
+    success: SandboxSummary,
+    error: SandboxNotFound,
+}), HttpApiEndpoint.put("credentials", "/v1/sandboxes/:name/credentials", {
+    params: sandbox,
+    payload: SandboxCredentials,
+    success: SandboxSummary,
+    error: [SandboxNotFound, StaleCredentials, ContainerUnavailable],
+}), HttpApiEndpoint.post("hold", "/v1/sandboxes/:name/hold", {
+    params: sandbox,
+    success: SandboxSummary,
+    error: [SandboxNotFound, ContainerUnavailable],
+}), HttpApiEndpoint.post("stop", "/v1/sandboxes/:name/stop", {
+    params: sandbox,
+    success: Stopped,
+    error: [SandboxNotFound, ContainerUnavailable],
+}), HttpApiEndpoint.delete("destroy", "/v1/sandboxes/:name", {
+    params: sandbox,
+    success: Destroyed,
+    error: ContainerUnavailable,
+}), HttpApiEndpoint.get("process", "/v1/sandboxes/:name/processes/:process", {
+    params: { ...sandbox, process: ProcessId },
+    success: ProcessStatus,
+    error: [SandboxNotFound, ProcessNotFound, ContainerUnavailable],
+}))
+    .annotate(HttpApi.PayloadParseOptions, { onExcessProperty: "error" });
+/**
+ * The JSON API of the Worker that usine ships (`@usine/cloudflare/worker`). Every request carries
+ * the Access service token headers. Commands run through the exec stream at `execPath`, not
+ * through this API.
+ */
+export const SandboxApi = HttpApi.make("SandboxApi").add(healthGroup, registryGroup, sandboxGroup);
+//# sourceMappingURL=api.js.map

package/dist/api/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/api/api.ts"],"names":[],"mappings":"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"}

package/dist/api/harness.d.ts

@@ -0,0 +1,49 @@
+import type { CloudflareLlmProvider } from "@usine/core/worker";
+/** The home directory of the image's `usine` user, where every command starts. */
+export declare const SANDBOX_HOME = "/home/usine";
+/** The directory with each command's process files, one directory per process ID. */
+export declare const PROCESSES_DIRECTORY = "/home/usine/.usine/processes";
+/**
+ * The file that the image's init writes when the platform sends the container SIGTERM, before
+ * it stops the container within 15 minutes (`image/init.sh`).
+ */
+export declare const DRAIN_MARKER = "/home/usine/.usine/draining";
+/**
+ * The certificate authority that signs the certificates of the hosts the Worker intercepts over
+ * HTTPS. The container runtime mounts it.
+ */
+export declare const CONTAINER_CA = "/etc/cloudflare/certs/cloudflare-containers-ca.crt";
+/**
+ * The host that each provider's outbound handler serves over plain HTTP inside the sandbox, and
+ * the upstream it forwards to over HTTPS.
+ */
+export declare const PROVIDER_HOSTS: {
+    readonly anthropic: {
+        readonly sandbox: "anthropic.usine.internal";
+        readonly upstream: "api.anthropic.com";
+    };
+    readonly openai: {
+        readonly sandbox: "openai.usine.internal";
+        readonly upstream: "api.openai.com";
+    };
+};
+/** The GitHub hosts whose requests the GitHub outbound handler authenticates. */
+export declare const GITHUB_HOSTS: readonly ["github.com", "api.github.com"];
+export type GitHubHost = (typeof GITHUB_HOSTS)[number];
+/**
+ * The value the sandbox sends where a tool expects a credential. The outbound handlers replace
+ * it, so it's not a secret.
+ */
+export declare const PLACEHOLDER_CREDENTIAL = "usine-placeholder";
+/**
+ * Returns the environment that points the harnesses, git, and gh at the outbound handlers, for
+ * a sandbox whose handlers hold keys for `providers`. It contains no secret.
+ *
+ * - git and gh use HTTPS to GitHub, and trust the container's certificate authority, as
+ *   Cloudflare's coding-agent runner sets it up. gh sends the placeholder as its token.
+ * - Claude Code calls the Anthropic handler over plain HTTP with the placeholder as its key.
+ * - Codex reads the placeholder from `OPENAI_API_KEY`; the image's Codex configuration points
+ *   its `usine` model provider at the OpenAI handler.
+ */
+export declare const harnessEnvironment: (providers: ReadonlyArray<CloudflareLlmProvider>) => Record<string, string>;
+//# sourceMappingURL=harness.d.ts.map

package/dist/api/harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.d.ts","sourceRoot":"","sources":["../../src/api/harness.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAEhE,kFAAkF;AAClF,eAAO,MAAM,YAAY,gBAAgB,CAAC;AAE1C,qFAAqF;AACrF,eAAO,MAAM,mBAAmB,iCAAqC,CAAC;AAEtE;;;GAGG;AACH,eAAO,MAAM,YAAY,gCAAoC,CAAC;AAE9D;;;GAGG;AACH,eAAO,MAAM,YAAY,uDAAuD,CAAC;AAEjF;;;GAGG;AACH,eAAO,MAAM,cAAc;;iBACZ,OAAO,EAAE,0BAA0B;iBAAE,QAAQ,EAAE,mBAAmB;;;iBACrE,OAAO,EAAE,uBAAuB;iBAAE,QAAQ,EAAE,gBAAgB;;CAIvE,CAAC;AAEF,iFAAiF;AACjF,eAAO,MAAM,YAAY,YAAI,YAAY,EAAE,gBAAgB,CAAU,CAAC;AACtE,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD;;;GAGG;AACH,eAAO,MAAM,sBAAsB,sBAAsB,CAAC;AAY1D;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,cAClB,aAAa,CAAC,qBAAqB,CAAC,KAC9C,MAAM,CAAC,MAAM,EAAE,MAAM,CAWrB,CAAC"}