@intentius/chant-lexicon-fountain 0.89.0 → 0.91.0

package/src/composites/box.ts

@@ -0,0 +1,255 @@
+/**
+ * Box — a persistent machine that serves an app repo and its tools (#2705).
+ *
+ * A box is an `Environment` whose `setup_script` provisions the machine (for
+ * an arugula studio box, the studio's `box/provision-template.sh`), an
+ * `Agent` on a persistent sandbox provisioned from it, and optionally a
+ * `Vault` for the secrets every box of this kind shares. `repo` is optional:
+ * when given, the Environment's `repositories` clones it in before setup
+ * runs; when omitted (#2759 — a blank-slate app, such as the one hud's
+ * `init` makes, has no git remote yet), the Environment holds no
+ * `repositories` at all and `setup_script` still runs, against whatever
+ * working tree is already on the sandbox (a self-hosted `runner`'s own).
+ *
+ * ```ts
+ * export const { environment, agent, vault } = Box({
+ *   name: "studio-box",
+ *   repo: { url: "https://github.com/arugula-salad/studio", ref: "main" },
+ *   setupScript: readFileSync("box/provision-template.sh", "utf8"),
+ *   permissionPolicy: { default: "auto_allow" },
+ *   allowedHosts: ["registry.npmjs.org", "github.com"],
+ *   vault: { secrets: [{ key: "STUDIO_SECRET", value: "${STUDIO_SECRET}" }] },
+ * });
+ * ```
+ *
+ * Beside `Steward`: a steward is an environment's one writer, an `acp` agent
+ * whose every turn is a chant command line, bound to a teammate with a
+ * standing thread and schedules. A box is where people and their agents work
+ * on an app: a conversational runtime (`claude` by default), the app repo
+ * cloned in (when there is one), the provisioning script run as setup, and
+ * one served port. It declares no teammate and no schedule, and nothing here
+ * starts a conversation. Starting and reaping a box stays a runtime act, as
+ * it is in hud's box runtime.
+ *
+ * The defaults are the closed ones, as `ConciergeStack`'s are, and loosening
+ * one is a visible parameter: networking is `limited` with an empty allowlist
+ * until `allowedHosts` names hosts or `unrestrictedNetworking: true` opens it
+ * (which FTN011 then warns about); `allowed_vault_ids` holds the box's own
+ * vault, or nothing, until `allowedVaults` widens it; `sandbox_provider` is
+ * unset (the instance default) until `sandboxProvider` names one of the
+ * pinned spec's `sprites`, `e2b`, `daytona` or `runner`. `permission_policy`
+ * has no default at all, because fountain's unset policy is `auto_allow` and
+ * that should be a choice someone wrote down.
+ *
+ * ## Credentials
+ *
+ * A box holds no credential (#2726). What it reaches outside itself
+ * (inference, Fountain's own API) goes through a broker, such as a studio's
+ * lobby, that holds the key and enforces a scope. Those capabilities are
+ * declared in the workspace declaration's `box` block on the member that
+ * holds this composite, not here: `chant workspace check` and the read
+ * contract read the declaration without running this code. Here, a vault
+ * secret's value and an `envVars` value are references (`${VAR}`, `op://`,
+ * `bws://`, `infisical://`) that resolve at apply, never a literal, and never
+ * `process.env.X`, which writes the secret into the built manifest. `chant
+ * workspace check` fails a box member whose files hold one
+ * (`box-credential-declared`).
+ *
+ * ## The port
+ *
+ * fountain's `Environment` and `Agent` have no field for a served port (the
+ * pinned spec, v0.21.0). The port is recorded in the metadata of both, under
+ * `box-port`, and returned as `port`, so whatever builds the box's URL reads
+ * it from the declaration or from fountain's own record without a guess.
+ *
+ * ## Allowed vaults in the read contract
+ *
+ * `sandbox_provider` is a plain `Agent` field, so `chant workspace graph
+ * --json` (and `chant graph`) already carry it on the agent's node like any
+ * other declared attribute. `allowed_vault_ids` is not as plain to read:
+ * fountain's own convention (and this composite's, per `allowedVaults`
+ * above) is that an *unset* list means "any vault the tenant owns", so a
+ * graph reader can't tell "no vaults declared" from "any vault" just by the
+ * key's absence. #2759 — a runtime that creates a vault per box (hud's box
+ * runtime) needs to check that the declaration permits it — so the resolved
+ * list, or the literal string `"any"`, is also recorded in the agent's
+ * metadata under `box-allowed-vault-ids` (`BOX_ALLOWED_VAULTS_METADATA_KEY`).
+ * It is read-only bookkeeping, alongside `box-port`: the manifest's real
+ * `allowed_vault_ids` field is what fountain applies.
+ */
+
+import { Agent, Environment, Vault } from "../generated/index";
+
+/** The metadata key a box's served port is recorded under, on its Environment and Agent. */
+export const BOX_PORT_METADATA_KEY = "box-port";
+
+/** The metadata key a box agent's resolved allowed vaults (or `"any"`) are recorded under, for the read contract. */
+export const BOX_ALLOWED_VAULTS_METADATA_KEY = "box-allowed-vault-ids";
+
+/** `Agent.sandbox_provider`'s values at the pinned spec. */
+export const BOX_SANDBOX_PROVIDERS = ["sprites", "e2b", "daytona", "runner"] as const;
+
+/** A sandbox backend, per the pinned spec's `sandbox_provider` enum. */
+export type BoxSandboxProvider = (typeof BOX_SANDBOX_PROVIDERS)[number];
+
+/** The port a box serves when none is given: the door's. */
+export const BOX_DEFAULT_PORT = 8080;
+
+/** Where the app repo is cloned when no `mountPath` is given. */
+export const BOX_DEFAULT_MOUNT_PATH = "/workspace/app";
+
+/** A permission verdict, or a number of seconds under the `ask_timeout` key. */
+export type BoxPermissionPolicy = Record<string, "ask" | "auto_allow" | "auto_deny" | number>;
+
+/** The app repo the box serves. Shape of fountain's `Repository`. */
+export interface BoxRepositoryOpts {
+  /** https clone url. */
+  url: string;
+  /** Absolute path the repo is cloned to. Default `/workspace/app`. */
+  mountPath?: string;
+  /** Branch or tag. The default branch when omitted. */
+  ref?: string;
+  /** Name of the secret holding a clone token. Required for a private repo. */
+  secretKey?: string;
+}
+
+/** The secrets every box of this kind shares, held in a Vault of the box's own. */
+export interface BoxVaultOpts {
+  /** Vault name. Default `<name>-secrets`. */
+  name?: string;
+  description?: string;
+  /** Written at apply. A reference such as `${VAR}` or `op://...` that resolves at apply, never a literal (FTN001, and `box-credential-declared` in `chant workspace check`). */
+  secrets?: { key: string; value: string }[];
+}
+
+export interface BoxOpts {
+  /** The Agent's name. The Environment is `<name>-env`. */
+  name: string;
+  /** The app repo the box serves, cloned into the sandbox before setup runs. Omit for a blank-slate app with no repo yet: the Environment declares no `repositories`, and `setupScript` runs against whatever working tree the sandbox already has. */
+  repo?: BoxRepositoryOpts;
+  /** The provisioning script's text, run as the Environment's `setup_script`. */
+  setupScript: string;
+  /** Setup exec timeout, 1 to 900 seconds (FTN024). fountain's default is 120. */
+  setupTimeoutSeconds?: number;
+  /** Agent runtime. Default `claude`. */
+  runtime?: "claude" | "codex" | "gemini" | "opencode";
+  /** Canonical provider/model_id. Omitted, fountain's default for the runtime. */
+  model?: string;
+  /** Sandbox backend override. Omitted, the instance default (`SANDBOX_PROVIDER`). A plain `Agent.sandbox_provider` field, so it is already visible on the graph node without extra bookkeeping (unlike `allowedVaults`; see "Allowed vaults in the read contract" above). */
+  sandboxProvider?: BoxSandboxProvider;
+  /** Per-tool permission policy. Required: fountain's unset policy is `auto_allow`. */
+  permissionPolicy: BoxPermissionPolicy;
+  /** Environment packages, passed through. */
+  packages?: Record<string, unknown>;
+  /** Environment variables, passed through. Not for secrets: use `vault`. */
+  envVars?: Record<string, string>;
+  /** Egress allowlist under `limited` networking. Default [], deny-all. */
+  allowedHosts?: string[];
+  /** Open the sandbox's network. FTN011 warns on it. Refused with `allowedHosts`. */
+  unrestrictedNetworking?: boolean;
+  /** Declare a Vault for the box's shared secrets. */
+  vault?: BoxVaultOpts;
+  /**
+   * Vaults a conversation may attach. Default: the box's own vault, or none.
+   * `"any"` leaves the list unset, which fountain reads as any vault the
+   * tenant owns: what a runtime that makes a vault per box (hud's) needs.
+   */
+  allowedVaults?: "any" | Array<InstanceType<typeof Vault> | string>;
+  /** The port the box serves. Default 8080, the door's. Recorded as `box-port` metadata. */
+  port?: number;
+  system?: string;
+  skills?: Array<Record<string, unknown>>;
+  mcpServers?: Record<string, unknown>;
+  /** Extra metadata, merged over the ownership marker on every resource the box declares. */
+  metadata?: Record<string, unknown>;
+}
+
+export interface BoxResources {
+  environment: InstanceType<typeof Environment>;
+  agent: InstanceType<typeof Agent>;
+  vault?: InstanceType<typeof Vault>;
+  /** The served port, as recorded under `box-port`. */
+  port: number;
+}
+
+export function Box(opts: BoxOpts): BoxResources {
+  const port = opts.port ?? BOX_DEFAULT_PORT;
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`Box "${opts.name}": port ${port} is not a TCP port (1 to 65535)`);
+  }
+  if (opts.unrestrictedNetworking && opts.allowedHosts !== undefined) {
+    throw new Error(
+      `Box "${opts.name}": allowedHosts and unrestrictedNetworking together — ` +
+        `an allowlist means nothing on an open network. Pass one.`,
+    );
+  }
+  if (!opts.setupScript.trim()) {
+    throw new Error(`Box "${opts.name}": setupScript is empty — a box is provisioned by its setup script`);
+  }
+
+  const owned = { "managed-by": "chant", ...(opts.metadata ?? {}) };
+  const metadata = { ...owned, [BOX_PORT_METADATA_KEY]: port };
+
+  const repository = opts.repo
+    ? {
+        url: opts.repo.url,
+        mount_path: opts.repo.mountPath ?? BOX_DEFAULT_MOUNT_PATH,
+        ...(opts.repo.ref !== undefined ? { ref: opts.repo.ref } : {}),
+        ...(opts.repo.secretKey !== undefined ? { secret_key: opts.repo.secretKey } : {}),
+      }
+    : undefined;
+
+  const environment = new Environment({
+    name: `${opts.name}-env`,
+    ...(repository ? { repositories: [repository] } : {}),
+    setup_script: opts.setupScript,
+    ...(opts.setupTimeoutSeconds !== undefined ? { setup_timeout_seconds: opts.setupTimeoutSeconds } : {}),
+    ...(opts.packages ? { packages: opts.packages } : {}),
+    ...(opts.envVars ? { env_vars: opts.envVars } : {}),
+    ...(opts.unrestrictedNetworking
+      ? { networking_type: "unrestricted" as const }
+      : { networking_type: "limited" as const, networking_config: { allowed_hosts: opts.allowedHosts ?? [] } }),
+    metadata,
+  });
+
+  const vault = opts.vault
+    ? new Vault({
+        name: opts.vault.name ?? `${opts.name}-secrets`,
+        ...(opts.vault.description !== undefined ? { description: opts.vault.description } : {}),
+        ...(opts.vault.secrets ? { secrets: opts.vault.secrets } : {}),
+        metadata: owned,
+      })
+    : undefined;
+
+  // A Vault declaration rather than its `.id`, as in Steward: the manifest's
+  // reference form is the resource's name (FTN021), and an AttrRef would
+  // serialize to the chant export name instead.
+  const allowedVaults =
+    opts.allowedVaults === "any" ? undefined : (opts.allowedVaults ?? (vault ? [vault] : []));
+
+  // The resolved allowed-vaults value, for the read contract (see "Allowed
+  // vaults in the read contract" above) — "any" when the list is left unset,
+  // otherwise each entry's own declared name.
+  const allowedVaultsForReadContract: "any" | string[] =
+    opts.allowedVaults === "any"
+      ? "any"
+      : allowedVaults!.map((v) => (typeof v === "string" ? v : (v as unknown as { props: { name: string } }).props.name));
+  const agentMetadata = { ...metadata, [BOX_ALLOWED_VAULTS_METADATA_KEY]: allowedVaultsForReadContract };
+
+  const agent = new Agent({
+    name: opts.name,
+    runtime: opts.runtime ?? "claude",
+    ...(opts.model !== undefined ? { model: opts.model } : {}),
+    sandbox_mode: "persistent",
+    ...(opts.sandboxProvider !== undefined ? { sandbox_provider: opts.sandboxProvider } : {}),
+    environment,
+    permission_policy: opts.permissionPolicy,
+    ...(allowedVaults !== undefined ? { allowed_vault_ids: allowedVaults } : {}),
+    ...(opts.skills ? { skills: opts.skills } : {}),
+    ...(opts.mcpServers ? { mcp_servers: opts.mcpServers } : {}),
+    ...(opts.system !== undefined ? { system: opts.system } : {}),
+    metadata: agentMetadata,
+  });
+
+  return { environment, agent, ...(vault ? { vault } : {}), port };
+}

package/src/composites/composites.test.ts

@@ -1,9 +1,13 @@
 import { beforeEach, describe, expect, it } from "vitest";
-import { WatchOp, type OpConfig } from "@intentius/chant/op";
+import { WatchOp, isStewardDeclaration, stewardFormFor, type OpConfig } from "@intentius/chant/op";
 import { ConciergeStack } from "./concierge-stack";
 import { Steward, stewardForOp, __resetStewardsForTests } from "./steward";
+import { Box, BOX_ALLOWED_VAULTS_METADATA_KEY, BOX_PORT_METADATA_KEY } from "./box";
+import { postSynthChecks } from "../lint/post-synth/index";
+import spec from "../spec/fountain-openapi.snapshot.json";
 import { Environment, Vault } from "../generated/index";
 import { fountainSerializer } from "../serializer";
+import { buildGraphIr, resolveAttrRefs } from "@intentius/chant";
 import type { Declarable } from "@intentius/chant";
 import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
 import { runtimeModelValidCheck } from "../lint/post-synth/ftn016-runtime-model-valid";
@@ -234,3 +238,298 @@ describe("Steward", () => {
     expect(yaml).toMatch(/allowed_vault_ids:\n\s+- prod-creds/);
   });
 });
+
+// ── Steward: the declaration core reads, and its form (#2731) ─────────────
+
+describe("Steward declaration and form", () => {
+  beforeEach(() => {
+    __resetStewardsForTests();
+  });
+
+  const toolchain = () => new Environment({ name: "toolchain" });
+
+  it("returns the declaration core reads: name, every op, and fountain as the default form", () => {
+    const { declaration } = Steward({
+      name: "box-steward",
+      environment: toolchain(),
+      ops: [op("box-converge", { cron: "* * * * *" }), op("box-release")],
+    });
+    expect(isStewardDeclaration(declaration)).toBe(true);
+    expect(declaration.name).toBe("box-steward");
+    expect(declaration.ops.map((o) => o.name)).toEqual(["box-converge", "box-release"]);
+    expect(declaration.form).toEqual({ default: "fountain", environments: {} });
+    expect(stewardFormFor(declaration, "prod")).toBe("fountain");
+  });
+
+  it("names the environments where the same steward runs locally", () => {
+    const { declaration, schedules } = Steward({
+      name: "box-steward",
+      environment: toolchain(),
+      ops: [op("box-converge", { cron: "* * * * *" })],
+      form: { default: "fountain", environments: { minimal: "local", spritzer: "local" } },
+    });
+    expect(stewardFormFor(declaration, "fountain-k3d")).toBe("fountain");
+    expect(stewardFormFor(declaration, "minimal")).toBe("local");
+    expect(stewardFormFor(declaration, "spritzer")).toBe("local");
+    // The Fountain resources are declared whatever the form: which environment
+    // they run in is the deploy's business, not the declaration's.
+    expect(schedules).toHaveLength(1);
+  });
+
+  it("refuses a form that is local everywhere, which needs none of the Fountain resources", () => {
+    expect(() =>
+      Steward({ name: "box-steward", environment: toolchain(), ops: [], form: "local" }),
+    ).toThrow(/local" in every environment/);
+  });
+
+  it("refuses an op listed twice, which would run twice per fire", () => {
+    const converge = op("box-converge", { cron: "* * * * *" });
+    expect(() =>
+      Steward({ name: "box-steward", environment: toolchain(), ops: [converge, converge] }),
+    ).toThrow(/listed twice/);
+  });
+
+  it("records the brokered capabilities, and refuses them beside a vault (#2726)", () => {
+    const { declaration } = Steward({ name: "box-steward", environment: toolchain(), ops: [], capabilities: ["fountain"] });
+    expect(declaration.capabilities).toEqual(["fountain"]);
+    expect(declaration.vault).toBeNull();
+    __resetStewardsForTests();
+    expect(
+      Steward({ name: "prod-steward", environment: toolchain(), vault: new Vault({ name: "prod-creds" }), ops: [] }).declaration.vault,
+    ).toBe("prod-creds");
+    __resetStewardsForTests();
+    expect(() =>
+      Steward({ name: "x", environment: toolchain(), vault: new Vault({ name: "v" }), ops: [], capabilities: ["fountain"] }),
+    ).toThrow(/holds no credential/);
+  });
+
+  it("refuses an unknown form", () => {
+    expect(() =>
+      Steward({ name: "box-steward", environment: toolchain(), ops: [], form: "cloud" as never }),
+    ).toThrow(/"local" or "fountain"/);
+  });
+});
+
+// ── Box ───────────────────────────────────────────────────────────────────
+
+describe("Box", () => {
+  const base = {
+    name: "studio-box",
+    repo: { url: "https://github.com/arugula-salad/studio" },
+    setupScript: "#!/bin/bash\nexec ~/box/provision-template.sh\n",
+    permissionPolicy: { default: "auto_allow" as const },
+  };
+
+  it("declares a closed Environment and a persistent claude Agent, with the port in metadata", () => {
+    const { environment, agent, vault, port } = Box(base);
+
+    const env = props(environment);
+    expect(env.name).toBe("studio-box-env");
+    expect(env.repositories).toEqual([{ url: "https://github.com/arugula-salad/studio", mount_path: "/workspace/app" }]);
+    expect(env.setup_script).toBe(base.setupScript);
+    expect(env.networking_type).toBe("limited");
+    expect(env.networking_config).toEqual({ allowed_hosts: [] });
+    expect(env.metadata).toEqual({ "managed-by": "chant", [BOX_PORT_METADATA_KEY]: 8080 });
+
+    const a = props(agent);
+    expect(a.name).toBe("studio-box");
+    expect(a.runtime).toBe("claude");
+    expect(a.model).toBeUndefined();
+    expect(a.sandbox_mode).toBe("persistent");
+    expect(a.environment).toBe(environment);
+    expect(a.permission_policy).toEqual({ default: "auto_allow" });
+    expect(a.allowed_vault_ids).toEqual([]);
+    expect(a.sandbox_provider).toBeUndefined();
+    expect(a.metadata).toEqual({
+      "managed-by": "chant",
+      "box-port": 8080,
+      [BOX_ALLOWED_VAULTS_METADATA_KEY]: [],
+    });
+
+    expect(vault).toBeUndefined();
+    expect(port).toBe(8080);
+  });
+
+  it("declares the shared vault and scopes the agent to it, named in the read contract", () => {
+    const { agent, vault } = Box({
+      ...base,
+      vault: { secrets: [{ key: "STUDIO_SECRET", value: "${STUDIO_SECRET}" }] },
+    });
+    expect(props(vault).name).toBe("studio-box-secrets");
+    expect(props(vault).secrets).toEqual([{ key: "STUDIO_SECRET", value: "${STUDIO_SECRET}" }]);
+    expect(props(vault).metadata).toEqual({ "managed-by": "chant" });
+    expect(props(agent).allowed_vault_ids).toEqual([vault]);
+    expect((props(agent).metadata as Record<string, unknown>)[BOX_ALLOWED_VAULTS_METADATA_KEY]).toEqual([
+      "studio-box-secrets",
+    ]);
+  });
+
+  it("resolves an explicit allowedVaults list to names in the read contract", () => {
+    const { agent } = Box({ ...base, allowedVaults: ["other-secrets", "studio-box-secrets"] });
+    expect(props(agent).allowed_vault_ids).toEqual(["other-secrets", "studio-box-secrets"]);
+    expect((props(agent).metadata as Record<string, unknown>)[BOX_ALLOWED_VAULTS_METADATA_KEY]).toEqual([
+      "other-secrets",
+      "studio-box-secrets",
+    ]);
+  });
+
+  it("loosening is a visible parameter", () => {
+    const open = Box({
+      ...base,
+      runtime: "codex",
+      model: "openai/gpt-5",
+      port: 3000,
+      unrestrictedNetworking: true,
+      allowedVaults: "any",
+      sandboxProvider: "e2b",
+      repo: { url: "https://github.com/o/app", mountPath: "/srv/app", ref: "v1", secretKey: "GH_TOKEN" },
+      envVars: { NODE_ENV: "production" },
+      packages: { apt: ["podman"] },
+      setupTimeoutSeconds: 900,
+      metadata: { team: "studio" },
+    });
+    const env = props(open.environment);
+    expect(env.networking_type).toBe("unrestricted");
+    expect(env.networking_config).toBeUndefined();
+    expect(env.repositories).toEqual([{ url: "https://github.com/o/app", mount_path: "/srv/app", ref: "v1", secret_key: "GH_TOKEN" }]);
+    expect(env.env_vars).toEqual({ NODE_ENV: "production" });
+    expect(env.packages).toEqual({ apt: ["podman"] });
+    expect(env.setup_timeout_seconds).toBe(900);
+    expect(env.metadata).toEqual({ "managed-by": "chant", team: "studio", "box-port": 3000 });
+    const a = props(open.agent);
+    expect(a.runtime).toBe("codex");
+    expect(a.model).toBe("openai/gpt-5");
+    expect(a.sandbox_provider).toBe("e2b");
+    // "any" leaves the manifest's own list unset: fountain reads that as any
+    // vault the tenant owns. The read contract still names it explicitly.
+    expect("allowed_vault_ids" in a).toBe(false);
+    expect((a.metadata as Record<string, unknown>)[BOX_ALLOWED_VAULTS_METADATA_KEY]).toBe("any");
+    expect(open.port).toBe(3000);
+
+    const listed = Box({ ...base, allowedHosts: ["registry.npmjs.org"] });
+    expect(props(listed.environment).networking_config).toEqual({ allowed_hosts: ["registry.npmjs.org"] });
+  });
+
+  it("builds with no repo — no clone, the Environment declares no repositories", () => {
+    const { environment, agent, port } = Box({
+      name: "blank-slate",
+      setupScript: "#!/bin/bash\nnpm install\n",
+      permissionPolicy: { default: "auto_allow" as const },
+      sandboxProvider: "runner",
+    });
+    const env = props(environment);
+    expect("repositories" in env).toBe(false);
+    expect(env.setup_script).toBe("#!/bin/bash\nnpm install\n");
+    const a = props(agent);
+    expect(a.sandbox_provider).toBe("runner");
+    expect(port).toBe(8080);
+  });
+
+  it("refuses what it cannot mean", () => {
+    expect(() => Box({ ...base, port: 0 })).toThrow(/not a TCP port/);
+    expect(() => Box({ ...base, port: 8080.5 })).toThrow(/not a TCP port/);
+    expect(() => Box({ ...base, unrestrictedNetworking: true, allowedHosts: ["github.com"] })).toThrow(
+      /allowedHosts and unrestrictedNetworking/,
+    );
+    expect(() => Box({ ...base, setupScript: "  " })).toThrow(/setupScript is empty/);
+  });
+
+  it("serializes to a manifest whose specs the pinned API accepts, clean under every post-synth check", () => {
+    const { environment, agent, vault } = Box({
+      ...base,
+      allowedHosts: ["registry.npmjs.org", "github.com"],
+      vault: { secrets: [{ key: "STUDIO_SECRET", value: "${STUDIO_SECRET}" }] },
+    });
+    const entities = new Map<string, Declarable>([
+      ["boxAgent", agent as unknown as Declarable],
+      ["boxVault", vault as unknown as Declarable],
+      ["boxEnv", environment as unknown as Declarable],
+    ]);
+
+    const yaml = fountainSerializer.serialize(entities) as string;
+    expect([...yaml.matchAll(/^kind: (\w+)$/gm)].map((m) => m[1])).toEqual(["Environment", "Vault", "Agent"]);
+    expect(yaml).toContain("environment: studio-box-env");
+    expect(yaml).toMatch(/allowed_vault_ids:\n\s+- studio-box-secrets/);
+    expect(yaml).toContain("box-port: 8080");
+
+    // Every spec key is a field of the pinned create request, or one of the
+    // two manifest-level forms fountainApply and `fountain apply -f` resolve:
+    // a name reference to the agent's environment, and inline secrets.
+    const schemas = (spec as unknown as { components: { schemas: Record<string, { properties: Record<string, unknown> }> } })
+      .components.schemas;
+    const manifestOnly = new Set(["environment", "secrets"]);
+    for (const [kind, entity] of [
+      ["EnvironmentRequest", environment],
+      ["VaultRequest", vault],
+      ["AgentRequest", agent],
+    ] as const) {
+      const fields = Object.keys(schemas[kind].properties);
+      for (const key of Object.keys(props(entity))) {
+        if (key === "name" || manifestOnly.has(key)) continue;
+        expect(fields, `${kind} has no field ${key}`).toContain(key);
+      }
+    }
+
+    const ctx = { outputs: new Map(), entities, buildResult: { warnings: [], errors: [] } } as unknown as PostSynthContext;
+    const diagnostics = postSynthChecks.flatMap((c) => c.check(ctx));
+    expect(diagnostics).toEqual([]);
+  });
+
+  it("a no-repo, sandboxProvider: runner box builds a manifest whose every field exists in the pinned spec, clean under every post-synth check", () => {
+    const { environment, agent } = Box({
+      name: "blank-slate",
+      setupScript: "#!/bin/bash\nnpm install\n",
+      permissionPolicy: { default: "auto_allow" as const },
+      sandboxProvider: "runner",
+    });
+    const entities = new Map<string, Declarable>([
+      ["boxAgent", agent as unknown as Declarable],
+      ["boxEnv", environment as unknown as Declarable],
+    ]);
+
+    const yaml = fountainSerializer.serialize(entities) as string;
+    expect([...yaml.matchAll(/^kind: (\w+)$/gm)].map((m) => m[1])).toEqual(["Environment", "Agent"]);
+    expect(yaml).not.toContain("repositories:");
+    expect(yaml).toContain("sandbox_provider: runner");
+
+    const schemas = (spec as unknown as { components: { schemas: Record<string, { properties: Record<string, unknown> }> } })
+      .components.schemas;
+    const manifestOnly = new Set(["environment", "secrets"]);
+    for (const [kind, entity] of [
+      ["EnvironmentRequest", environment],
+      ["AgentRequest", agent],
+    ] as const) {
+      const fields = Object.keys(schemas[kind].properties);
+      for (const key of Object.keys(props(entity))) {
+        if (key === "name" || manifestOnly.has(key)) continue;
+        expect(fields, `${kind} has no field ${key}`).toContain(key);
+      }
+    }
+
+    const ctx = { outputs: new Map(), entities, buildResult: { warnings: [], errors: [] } } as unknown as PostSynthContext;
+    const diagnostics = postSynthChecks.flatMap((c) => c.check(ctx));
+    expect(diagnostics).toEqual([]);
+  });
+
+  it("shows the agent's sandbox provider and allowed vaults on the graph node (#2759)", () => {
+    const { agent, environment } = Box({
+      ...base,
+      sandboxProvider: "runner",
+      allowedVaults: "any",
+    });
+    const entities = new Map<string, Declarable>([
+      ["boxAgent", agent as unknown as Declarable],
+      ["boxEnv", environment as unknown as Declarable],
+    ]);
+    resolveAttrRefs(entities);
+
+    const ir = buildGraphIr(entities);
+    const agentNode = ir.nodes.find((n) => n.id === "boxAgent")!;
+    expect(agentNode.attrs.sandbox_provider).toBe("runner");
+    // "any" leaves the manifest's allowed_vault_ids unset, so it's the
+    // metadata marker a graph reader checks, not an absent key it has to
+    // interpret.
+    expect(agentNode.attrs.allowed_vault_ids).toBeUndefined();
+    expect((agentNode.attrs.metadata as Record<string, unknown>)[BOX_ALLOWED_VAULTS_METADATA_KEY]).toBe("any");
+  });
+});