@eir-labs/coltrane 0.9.4 → 0.11.0

package/dist/src/venue_realize.js

@@ -35,6 +35,43 @@ const refuse = (code, detail) => ({
     tornDown: () => true,
     teardown: () => { },
 });
+/**
+ * The env keys a seat may carry from the ambient environment — the minimum a process needs to
+ * EXECUTE: PATH so the OS can locate its binary, HOME so the binary can resolve its own config. An
+ * explicit ALLOWLIST, not a deny-list: a key absent from this list never reaches the seat, so a
+ * credential added to the container later is excluded by default rather than by anyone remembering
+ * to strip it. This is the deny-by-default posture held unconditionally — it does not depend on the
+ * completeness of any strip-list (`withoutBoxCredentials`'s `BOX_CREDENTIAL_ENV` is a floor for the
+ * paths that never reach here, not the control).
+ *
+ * Why it is not `[]`: the seat env was `{}` (deny EVERYTHING), which is airtight but unspawnable —
+ * a `claude -p` child with no PATH cannot find its binary and dies with `spawn claude ENOENT`
+ * (measured, gig 87cffa2c), so no venue-confined seat ever ran. `['PATH','HOME']` is the
+ * minimum-viable widening: enough to start, no credential material.
+ *
+ * Why USER is admitted: on a macOS host with no `~/.claude/.credentials.json`, Claude auth is
+ * keychain-backed (a `Claude Code-credentials` keychain entry), and the keychain lookup needs USER
+ * to resolve the account. Measured: `claude -p` under {PATH,HOME} exits 1 with 'Not logged in ·
+ * Please run /login'; under {PATH,HOME,USER} it exits 0 and reaches the MCP server (gig 4506b567).
+ * On a Linux drain, credentials are file-based under HOME, so PATH+HOME already suffices and this
+ * key is inert. USER is a USERNAME, not a credential — admitting it carries no secret material, so
+ * the deny-by-default posture is unweakened; the allowlist grows by exactly one non-secret key.
+ */
+export const SEAT_ENV_ALLOWLIST = ["PATH", "HOME", "USER"];
+/**
+ * Build a seat's env as the allowlisted subset of the ambient environment. Only keys in
+ * `SEAT_ENV_ALLOWLIST` that are present with a defined value are carried; every other key — every
+ * credential, every undeclared ambient var — is omitted. Never inherits `ambientEnv` wholesale.
+ */
+function seatEnv(ambientEnv) {
+    const out = {};
+    for (const key of SEAT_ENV_ALLOWLIST) {
+        const value = ambientEnv[key];
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
 /**
  * Realize a Venue contract into an enforced, observable performance space.
  *
@@ -86,9 +123,12 @@ export function realize(venue, opts) {
         if (grants.length > 0 && effective_tools.length === 0) {
             return refuse("ceiling-empty", `agent "${seat.agent.slug}" grants [${grants.join(", ")}] but none lie within venue "${venue.slug}" equipment — the room narrows it to nothing`);
         }
-        // env is a default-deny map: nothing from the ambient environment leaks into a seat. No test
-        // pins seat.env values; the strictest posture is the safe one until a spec names otherwise.
-        seats.push({ agent_slug: seat.agent.slug, effective_tools, env: {} });
+        // env is the ALLOWLISTED subset of the ambient environment (SEAT_ENV_ALLOWLIST): the minimum a
+        // process needs to EXECUTE, and nothing else. `env: {}` was the stricter posture but it is
+        // UNSPAWNABLE — a child with no PATH dies with `spawn claude ENOENT` (measured, gig 87cffa2c),
+        // so no venue-confined seat ever started. Every credential and undeclared ambient var stays out
+        // by default; this widening only admits PATH/HOME.
+        seats.push({ agent_slug: seat.agent.slug, effective_tools, env: seatEnv(opts.ambientEnv) });
     }
     // The room is sound. Build the observable realization with per-call isolation and idempotent
     // teardown. `torn` is closed over this call alone, so tearing one gig's room down cannot touch

package/dist/src/venue_realize.js.map

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

package/dist/src/venue_realizer.d.ts

@@ -0,0 +1,224 @@
+import { DEVICE_CLASSES } from "./genome_schema.js";
+import { prepareWorkspace } from "./workspace.js";
+/** The workspace preparer the room populates its tree through. It IS the drain's `prepareWorkspace`
+ *  (src/workspace.ts) — one mechanism, not two — and defaults to exactly that. Injectable ONLY so a
+ *  law can observe the routing without a live git endpoint, the same seam shape `run` already uses for
+ *  docker; the default is the real shared function, so production population and drain population are
+ *  the identical clone path. */
+export type WorkspacePreparer = typeof prepareWorkspace;
+export { DEVICE_CLASSES };
+/** Credentials reach the room ONLY through here: bound at realization time from `credential_names`,
+ *  a subset of the venue's `credential_surface`. Injected the way the engine already injects one. */
+export type CredentialResolver = (names: readonly string[]) => Promise<Record<string, string>>;
+/** How the containerized realizer reaches `docker`. Real by default; see dockerComposeRealizer. */
+export type ComposeRunner = (args: readonly string[], timeoutMs: number) => void;
+/** The properties a realizer may CLAIM — and may only claim if it can actually keep them. */
+export type VenueGuarantee = "withholds_capabilities" | "isolated_filesystem" | "network_policy_doors" | "reproducible_tool_surface" | "per_chair_isolation";
+/** One thing a realizer created, LABELLED with both the gig it belongs to and the instance that made
+ *  it — an unlabelled artifact is indistinguishable from something a human made on purpose, so
+ *  nothing may safely collect it. */
+export interface RealizedArtifact {
+    kind: string;
+    id: string;
+    labels: {
+        gig_id: string;
+        instance: string;
+    };
+}
+/** A ceiling on what survives outside the per-gig lifecycle. The point is that a bound EXISTS. */
+export interface RetentionPolicy {
+    max_cached_build_artifacts: number;
+    max_unreferenced_environments: number;
+    cadence: string;
+}
+/** WHERE a room is stood up. Absent endpoint = the worker's own machine. The device map lives here,
+ *  not in the contract: which nodes `serial` means, and which group owns them, are the machine's
+ *  facts rather than the room's. */
+export interface RealizationHost {
+    endpoint?: string;
+    architecture: string;
+    devices: Readonly<Record<string, {
+        nodes: readonly string[];
+        group: string;
+    }>>;
+    /** Per gig, against a live lease — never held at boot. See src/workspace.ts:60-89. */
+    credential?: (args: {
+        gigId: string;
+    }) => Promise<string>;
+}
+export interface RealizationHandle {
+    state: string;
+    mcpServerConfigs: Readonly<Record<string, unknown>>;
+    configPath: string;
+    artifacts: readonly RealizedArtifact[];
+    teardown(): Promise<void> | void;
+    tornDown(): boolean;
+    /** Present ONLY when the room is SEAT-BEARING — its venue selects a `floor` image (Dockerfile.floor)
+     *  that carries the toolchain and the agent binary, the deliberate opposite of the production-only
+     *  room image. It names the room's own container and the per-realization workspace, so the invoker
+     *  can run the chair as `docker exec -i -w <workspace> <container> claude …` INSIDE the room. Absent
+     *  on the production room image and on the local-process realizer: the seat runs on the host. */
+    seat?: {
+        container: string;
+        workspace: string;
+    } | undefined;
+}
+export interface RealizeOpts {
+    gigId: string;
+    engineServers?: Readonly<Record<string, unknown>>;
+    probe?: (s: {
+        slug: string;
+    }) => Promise<string[]>;
+    host?: RealizationHost;
+    chairs?: number;
+    /** WHERE the room's tree comes from — the repository named by the RUN, supplied by the realization
+     *  caller, NEVER a venue field and NEVER read from the host's cwd. A venue is one AT-REST room that
+     *  serves many repositories, so the repository is a per-RUN fact, threaded in here from
+     *  `RunDeps.repoUrl` (an explicit dispatch field, or the claim's governed `repo_url`). Present → the
+     *  room's workspace is populated (through `prepareWorkspace`) with a clone of this repository, so a
+     *  seat inside the room has a tree to edit. Absent → the workspace stays the empty room, and no git
+     *  credential is minted. Inferring an ambient source is the exact failure this explicit field
+     *  forecloses. */
+    repoUrl?: string;
+    /** The per-gig git-credential plumbing `prepareWorkspace` requires, supplied by the realization
+     *  caller alongside `repoUrl` — never derived from ambient process state. The minted token only ever
+     *  rides `cloneInto`'s GIT_CONFIG_* env, never a host file, so token-never-on-disk is preserved. */
+    drainKey?: string;
+    instance?: string;
+    gitCredentialsEndpoint?: string;
+}
+/** The seam. The engine ships the interface, the state machine, the probe and the drift guard; a
+ *  deployment supplies the implementations it has. Two implementations or it is not a seam. */
+export interface VenueRealizer {
+    readonly substrate: string;
+    readonly guarantees: readonly VenueGuarantee[];
+    available(): boolean;
+    readonly retention: RetentionPolicy;
+    realize(venue: unknown, credentialResolver: CredentialResolver, opts: RealizeOpts): Promise<RealizationHandle>;
+    sweep(opts: {
+        liveGigs: readonly string[];
+    }): Promise<readonly RealizedArtifact[]>;
+}
+/** A substrate no available realizer provides is a REFUSAL, never a downgrade — the whole reason
+ *  this gap is written down. Names what was required and what this host can actually provide. */
+export declare class VenueSubstrateUnavailable extends Error {
+    readonly required: string;
+    readonly available: readonly string[];
+    constructor(required: string, available: readonly string[]);
+}
+/** A HOST cannot host this venue: a device class it does not provide, an architecture it is not.
+ *  Distinct from a substrate refusal — the fix is a different machine, not a different runtime. */
+export declare class VenueHostUnsuitable extends Error {
+    constructor(message: string);
+}
+/** A realization would exceed the venue's declared concurrency ceiling. */
+export declare class VenueConcurrencyRefused extends Error {
+    constructor(message: string);
+}
+/** Input would render a setting the contract may not ask for. Carries `forbidden` so the refusal
+ *  names the value, and `field` so it names where it arrived — "invalid venue" sends the author back
+ *  to read the whole contract. */
+export declare class VenueRenderRefusal extends Error {
+    readonly forbidden: string;
+    readonly field: string | undefined;
+    constructor(args: {
+        forbidden: string;
+        field?: string;
+        message?: string;
+    });
+}
+/** Gap 2's bidirectional probe, direction one: a tool the CONTRACT grants that the server does not
+ *  actually advertise. "Granted but unprovided" caught at realization instead of at first use. Carries
+ *  the bare tool and the server so the refusal names both — the remediation is to add the tool to the
+ *  server or drop the grant, which is a different fix from a server that is too wide. */
+export declare class VenueRealizationError extends Error {
+    readonly state: string;
+    readonly missingGrant: string;
+    readonly serverSlug: string;
+    constructor(args: {
+        state: string;
+        missingGrant: string;
+        serverSlug: string;
+        message?: string;
+    });
+}
+/** Gap 2's bidirectional probe, direction two: the server advertises MORE than the contract declared.
+ *  A ceiling the thing beneath it can quietly exceed is not a ceiling — the exact intersection R10
+ *  enforces at compose time. NON-OVERLAPPING fields with `VenueRealizationError` on purpose: the two
+ *  mismatches demand different remediation, and one merged error would make the direction ambiguous. */
+export declare class VenueContractViolation extends Error {
+    readonly state: string;
+    readonly extraTool: string;
+    readonly serverSlug: string;
+    constructor(args: {
+        state: string;
+        extraTool: string;
+        serverSlug: string;
+        message?: string;
+    });
+}
+/** The CLOSED allowlist of contract fields the renderer may substitute. Exact, not a floor: a field
+ *  not on this list contributes nothing to the render whatever it is called, and widening the list
+ *  is a line someone changes on purpose. */
+export declare const COMPOSE_SUBSTITUTABLE_FIELDS: readonly ["credential_names", "doors", "installs", "mcp_servers", "slug"];
+/** The identity of the environment built from a venue — a function of the parsed contract's content,
+ *  so the same contract is the same environment and a changed one is a different environment. */
+export declare function environmentIdentity(venue: unknown): string;
+/** The identity of the shared floor a venue composes over. Two venues declaring the same floor
+ *  resolve to the SAME floor identity — the precondition for sharing at all. */
+export declare function floorIdentity(venue: unknown): string;
+/** Renders the runtime configuration from a PARSED venue. Never from raw input: re-parsing through
+ *  `VenueSchema` (which is `.strict()`) is the enforcement point, so an unparsed object carrying an
+ *  extra key is refused at the door rather than trusted to have been parsed by every future caller. */
+export declare function renderComposeConfig(venue: unknown, opts: {
+    gigId: string;
+    realizationDir: string;
+    host?: RealizationHost;
+}): Record<string, unknown>;
+/** Picks the realizer a venue requires from those a deployment supplies. A required substrate no
+ *  AVAILABLE realizer provides is a `VenueSubstrateUnavailable`, never a downgrade. A venue naming no
+ *  substrate is realizable by whatever the deployment supplies — deny-by-default is on capability,
+ *  not on portability. */
+export declare function selectRealizer(venue: unknown, realizers: readonly VenueRealizer[]): VenueRealizer;
+/** THE ONE OWNER OF THE COMPOSE PROJECT NAME — and therefore of the room's container name.
+ *
+ *  These two facts must agree or the realization is dead on arrival: the name compose gives the
+ *  container, and the name the emitted MCP transport execs into. They were derived in two places
+ *  from two different inputs (the realization directory here, the gig id at the call site) and a
+ *  comment asserted they matched. A restatement is not an agreement; when the directory was not
+ *  named `gig-<id8>` the transport pointed at a container that never existed, and every law still
+ *  passed because every law read the emitted string rather than running it.
+ *
+ *  So there is one derivation and both callers go through it. `-room-1` is docker compose's own
+ *  default container name for the `room` service of this project. */
+export declare function composeProjectName(realizationDir: string): string;
+export declare function roomContainerName(realizationDir: string): string;
+/** The container docker compose names for a declared SERVER service — same `{project}-{service}-1`
+ *  default as the room, with the server's slug as the service. The credential-delivery step copies
+ *  each server's own classes into this container, mirroring where the prior compose file-secret was
+ *  mounted, so a server that reads /run/secrets/<class> is unchanged by the delivery move. */
+export declare function serverContainerName(realizationDir: string, slug: string): string;
+/** The Gap 2 entry: builds the spawn's MCP environment STRICTLY from the venue contract, verifies it
+ *  in both directions before anything is committed, and writes the per-gig config the spawn is pointed
+ *  at. The map is the venue's declared servers plus the engine entries and NOTHING the venue did not
+ *  declare — the ambient `.mcp.json` `readMcpServerConfigs` builds at bootstrap is never read here,
+ *  neither to add a server nor to override one, because a drain's cwd is an untrusted clone and a clone
+ *  that can declare MCP servers for the seat reading it is command execution under the seat. The
+ *  realized map is precisely what a tool grant is failed closed against, so preflight and spawn read
+ *  one stable object rather than two copies that agree today. */
+export declare function realizeVenue(venue: unknown, credentialResolver: CredentialResolver, opts: RealizeOpts): Promise<RealizationHandle>;
+/** The baseline. Runs seats as subprocesses of a host that holds the git binary, the remote and the
+ *  network — so it CANNOT withhold capabilities and CANNOT enforce `doors` at a network boundary,
+ *  and it claims neither. src/workspace.ts:44-56 is already candid that process-level protection is
+ *  not a security control and must not be described as one, so claiming those guarantees would be a
+ *  false contract a caller would rely on. Must work on a host with no container runtime and no
+ *  daemon installed. */
+export declare function localProcessRealizer(): VenueRealizer;
+/** The containerized realizer. Names a real boundary and may claim the guarantees it provides. MUST
+ *  NOT throw on construction — the out-of-scope laws call `.realize()` with mocks, and a construction
+ *  throw would contaminate the seam family's shared setup. Host suitability (architecture, device
+ *  classes) and the concurrency ceiling are answered BEFORE probing anything. */
+export declare function dockerComposeRealizer(opts?: {
+    run?: ComposeRunner;
+    prepareWorkspace?: WorkspacePreparer;
+}): VenueRealizer;