@intentius/chant-lexicon-fountain 0.33.0

package/src/spec/fetch.ts

@@ -0,0 +1,53 @@
+/**
+ * Fetch the fountain OpenAPI spec.
+ *
+ * Fountain serves its OpenAPI 3.1 spec from the running app at
+ * /api/openapi.json (generated from code via OpenApiSpex; public, no auth).
+ * This is an unversioned live endpoint: it always serves the spec of
+ * whatever is currently deployed, with no release tag to pin — fountain
+ * follows the rolling-spec model (like fly). A versioned spec artifact per
+ * release shipped upstream as a release asset (BinaryBourbon/fountain#140);
+ * when the hosted endpoint is reliably current this fetcher can prefer it.
+ *
+ * Fallback: a committed snapshot (fountain-openapi.snapshot.json) keeps
+ * generation hermetic when the live endpoint is unreachable — CI runs,
+ * offline dev, or the current state where the hosted instance predates the
+ * endpoint. The snapshot is refreshed alongside surface.snapshot.json when
+ * upstream moves (regenerate from a fountain checkout via
+ * `mix openapi.spec.json --spec FountainWeb.ApiSpec`).
+ */
+
+import { join, dirname } from "path";
+import { homedir } from "os";
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { fetchWithCache } from "@intentius/chant/codegen/fetch";
+
+const SCHEMA_URL = "https://founta.inevitable.fyi/api/openapi.json";
+
+const CACHE_FILE = join(homedir(), ".chant", "fountain-openapi.json");
+
+const SNAPSHOT_FILE = join(dirname(fileURLToPath(import.meta.url)), "fountain-openapi.snapshot.json");
+
+/**
+ * Fetch the fountain OpenAPI spec with caching, falling back to the
+ * committed snapshot when the live endpoint is unreachable. Returns a
+ * single-entry map — the whole spec is one document; the parser fans it
+ * out into per-kind results.
+ */
+export async function fetchSchemas(options?: { force?: boolean }): Promise<Map<string, Buffer>> {
+  let raw: Buffer;
+  try {
+    raw = await fetchWithCache({ url: SCHEMA_URL, cacheFile: CACHE_FILE }, options?.force);
+    // The live host currently 404s (deploy lag) — a non-spec body must not
+    // silently replace the snapshot.
+    JSON.parse(raw.toString("utf-8"));
+  } catch (err) {
+    console.error(
+      `[fountain] live spec fetch failed (${err instanceof Error ? err.message.split("\n")[0] : err}) — ` +
+        `using committed snapshot`,
+    );
+    raw = readFileSync(SNAPSHOT_FILE);
+  }
+  return new Map([["fountain-openapi.json", raw]]);
+}

package/src/spec/fountain-openapi.snapshot.json

@@ -0,0 +1 @@
+{"components":{"responses":{},"schemas":{"SecretListResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Secret"},"type":"array","x-struct":null,"x-validate":null}},"required":["data"],"title":"SecretListResponse","type":"object","x-struct":"Elixir.FountainWeb.Schemas.SecretListResponse","x-validate":null},"ConversationCreateRequest":{"properties":{"agent_id":{"format":"uuid","type":"string","x-struct":null,"x-validate":null},"images":{"description":"Optional images to attach to the initial prompt.","items":{"$ref":"#/components/schemas/ImageInput"},"nullable":true,"type":"array","x-struct":null,"x-validate":null},"prompt":{"description":"Optional first turn prompt.","type":"string","x-struct":null,"x-validate":null},"sprite_name":{"description":"Override the auto-generated sprite name.","type":"string","x-struct":null,"x-validate":null},"vault_id":{"description":"Optional vault whose secrets override the environment's baseline at sprite spawn. Must satisfy the agent's allowed_vault_ids when that allowlist is set.","format":"uuid","nullable":true,"type":"string","x-struct":null,"x-validate":null}},"required":["agent_id"],"title":"ConversationCreateRequest","type":"object","x-struct":"Elixir.FountainWeb.Schemas.ConversationCreateRequest","x-validate":null},"Secret":{"description":"A named secret. Values are write-only — the API never returns them.","properties":{"environment_id":{"format":"uuid","type":"string","x-struct":null,"x-validate":null},"id":{"format":"uuid","type":"string","x-struct":null,"x-validate":null},"inserted_at":{"format":"date-time","type":"string","x-struct":null,"x-validate":null},"key":{"type":"string","x-struct":null,"x-validate":null},"updated_at":{"format":"date-time","type":"string","x-struct":null,"x-validate":null}},"required":["id","key","environment_id"],"title":"Secret","type":"object","x-struct":"Elixir.FountainWeb.Schemas.Secret","x-validate":null},"VaultUpdate":{"properties":{"description":{"type":"string","x-struct":null,"x-validate":null},"metadata":{"additionalProperties":true,"type":"object","x-struct":null,"x-validate":null},"name":{"maxLength":200,"minLength":1,"type":"string","x-struct":null,"x-validate":null}},"title":"VaultUpdate","type":"object","x-struct":"Elixir.FountainWeb.Schemas.VaultUpdate","x-validate":null},"ImageInput":{"description":"A base64-encoded image to attach to a prompt.","properties":{"data":{"description":"Base64-encoded image bytes.","type":"string","x-struct":null,"x-validate":null},"media_type":{"description":"MIME type of the image.","enum":["image/png","image/jpeg","image/gif","image/webp"],"type":"string","x-struct":null,"x-validate":null}},"required":["data","media_type"],"title":"ImageInput","type":"object","x-struct":"Elixir.FountainWeb.Schemas.ImageInput","x-validate":null},"Repository":{"properties":{"mount_path":{"pattern":"^/","type":"string","x-struct":null,"x-validate":null},"url":{"format":"uri","pattern":"^https://","type":"string","x-struct":null,"x-validate":null}},"required":["url","mount_path"],"title":"Repository","type":"object","x-struct":"Elixir.FountainWeb.Schemas.Repository","x-validate":null},"EnvironmentUpdate":{"properties":{"env_vars":{"additionalProperties":{"type":"string","x-struct":null,"x-validate":null},"type":"object","x-struct":null,"x-validate":null},"metadata":{"additionalProperties":true,"type":"object","x-struct":null,"x-validate":null},"name":{"maxLength":200,"minLength":1,"type":"string","x-struct":null,"x-validate":null},"networking_config":{"additionalProperties":true,"description":"Refines networking_type: limited. allowed_hosts is the only key honored today; unknown keys are ignored. Under limited, egress is restricted to the allowlisted domains. With no allowed_hosts (or an empty list), the sandbox denies all egress by default — this is a deny-all, not an allow-all.","properties":{"allowed_hosts":{"description":"Domains the sandbox may reach when networking_type is limited.","items":{"type":"string","x-struct":null,"x-validate":null},"type":"array","x-struct":null,"x-validate":null}},"type":"object","x-struct":null,"x-validate":null},"networking_type":{"enum":["unrestricted","limited"],"type":"string","x-struct":null,"x-validate":null},"packages":{"additionalProperties":true,"type":"object","x-struct":null,"x-validate":null},"repositories":{"items":{"$ref":"#/components/schemas/Repository"},"type":"array","x-struct":null,"x-validate":null},"setup_script":{"type":"string","x-struct":null,"x-validate":null}},"title":"EnvironmentUpdate","type":"object","x-struct":"Elixir.FountainWeb.Schemas.EnvironmentUpdate","x-validate":null},"VaultSecret":{"description":"A named secret in a vault. Values are write-only — the API never returns them.","properties":{"id":{"format":"uuid","type":"string","x-struct":null,"x-validate":null},"inserted_at":{"format":"date-time","type":"string","x-struct":null,"x-validate":null},"key":{"type":"string","x-struct":null,"x-validate":null},"updated_at":{"format":"date-time","type":"string","x-struct":null,"x-validate":null},"vault_id":{"format":"uuid","type":"string","x-struct":null,"x-validate":null}},"required":["id","key","vault_id"],"title":"VaultSecret","type":"object","x-struct":"Elixir.FountainWeb.Schemas.VaultSecret","x-validate":null},"TurnListResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Turn"},"type":"array","x-struct":null,"x-validate":null}},"required":["data"],"title":"TurnListResponse","type":"object","x-struct":"Elixir.FountainWeb.Schemas.TurnListResponse","x-validate":null},"Sandbox":{"description":"One sprite lifespan owned by a conversation.","properties":{"id":{"format":"uuid","type":"string","x-struct":null,"x-validate":null},"sprite_name":{"type":"string","x-struct":null,"x-validate":null},"status":{"enum":["pending","starting","ready","terminated","failed"],"type":"string","x-struct":null,"x-validate":null}},"required":["id","sprite_name","status"],"title":"Sandbox","type":"object","x-struct":"Elixir.FountainWeb.Schemas.Sandbox","x-validate":null},"Error":{"properties":{"error":{"type":"string","x-struct":null,"x-validate":null}},"required":["error"],"title":"Error","type":"object","x-struct":"Elixir.FountainWeb.Schemas.Error","x-validate":null},"VaultSecretResponse":{"properties":{"data":{"$ref":"#/components/schemas/VaultSecret"}},"required":["data"],"title":"VaultSecretResponse","type":"object","x-struct":"Elixir.FountainWeb.Schemas.VaultSecretResponse","x-validate":null},"EnvironmentResponse":{"properties":{"data":{"$ref":"#/components/schemas/Environment"}},"required":["data"],"title":"EnvironmentResponse","type":"object","x-struct":"Elixir.FountainWeb.Schemas.EnvironmentResponse","x-validate":null},"ChangesetError":{"description":"Validation errors keyed by field, with each value an array of messages.","properties":{"errors":{"additionalProperties":{"items":{"type":"string","x-struct":null,"x-validate":null},"type":"array","x-struct":null,"x-validate":null},"type":"object","x-struct":null,"x-validate":null}},"required":["errors"],"title":"ChangesetError","type":"object","x-struct":"Elixir.FountainWeb.Schemas.ChangesetError","x-validate":null},"Agent":{"description":"An AI agent definition: runtime, model, skills, MCP, env.","properties":{"allowed_vault_ids":{"description":"Vaults a conversation may attach to this agent. null (default) allows any vault the tenant owns; an empty list forbids attaching any vault; a non-empty list is an allowlist. Vault values override the agent's environment on key collision, so this scopes who can override reviewed config.","items":{"format":"uuid","type":"string","x-struct":null,"x-validate":null},"nullable":true,"type":"array","x-struct":null,"x-validate":null},"description":{"type":"string","x-struct":null,"x-validate":null},"environment_id":{"format":"uuid","nullable":true,"type":"string","x-struct":null,"x-validate":null},"id":{"format":"uuid","type":"string","x-struct":null,"x-validate":null},"inserted_at":{"format":"date-time","type":"string","x-struct":null,"x-validate":null},"mcp_servers":{"additionalProperties":true,"type":"object","x-struct":null,"x-validate":null},"metadata":{"additionalProperties":true,"type":"object","x-struct":null,"x-validate":null},"model":{"description":"Canonical provider/model_id (e.g. anthropic/claude-sonnet-4-6).","pattern":"^[a-z0-9_-]+/[a-z0-9._-]+$","type":"string","x-struct":null,"x-validate":null},"name":{"type":"string","x-struct":null,"x-validate":null},"runtime":{"enum":["claude","codex","gemini","opencode"],"type":"string","x-struct":null,"x-validate":null},"skills":{"description":"Each entry is either inline (`{name, content}` — full SKILL.md text written to the sprite) or github (`{source, ref?, name?}` — installed on the sprite via the skills.sh CLI, optionally pinned to a tag/branch/sha via `ref`). Exactly one of `content` or `source` must be set on each entry.","items":{"properties":{"content":{"description":"Full SKILL.md body for inline entries.","type":"string","x-struct":null,"x-validate":null},"name":{"description":"Skill name (required for inline entries).","type":"string","x-struct":null,"x-validate":null},"ref":{"description":"Optional tag, branch, or sha pinning a github-sourced skill (installed as `owner/repo@ref`). Without it the default branch is fetched at spawn time.","pattern":"^[A-Za-z0-9._/-]+$","type":"string","x-struct":null,"x-validate":null},"source":{"description":"GitHub `owner/repo` for skills.sh-sourced entries.","pattern":"^[A-Za-z0-9._/-]+$","type":"string","x-struct":null,"x-validate":null}},"type":"object","x-struct":null,"x-validate":null},"type":"array","x-struct":null,"x-validate":null},"system":{"description":"System prompt.","type":"string","x-struct":null,"x-validate":null},"updated_at":{"format":"date-time","type":"string","x-struct":null,"x-validate":null}},"required":["id","name","model","runtime"],"title":"Agent","type":"object","x-struct":"Elixir.FountainWeb.Schemas.Agent","x-validate":null},"Conversation":{"description":"One chat with one agent inside one sandbox.","properties":{"agent_id":{"format":"uuid","nullable":true,"type":"string","x-struct":null,"x-validate":null},"id":{"format":"uuid","type":"string","x-struct":null,"x-validate":null},"inserted_at":{"format":"date-time","type":"string","x-struct":null,"x-validate":null},"runtime":{"enum":["claude","codex","gemini","opencode"],"type":"string","x-struct":null,"x-validate":null},"runtime_session_id":{"nullable":true,"type":"string","x-struct":null,"x-validate":null},"sandbox":{"nullable":true,"oneOf":[{"$ref":"#/components/schemas/Sandbox"}],"x-struct":null,"x-validate":null},"sandbox_id":{"format":"uuid","nullable":true,"type":"string","x-struct":null,"x-validate":null},"status":{"enum":["pending","running","idle","completed","failed","terminated"],"type":"string","x-struct":null,"x-validate":null},"updated_at":{"format":"date-time","type":"string","x-struct":null,"x-validate":null},"vault_id":{"format":"uuid","nullable":true,"type":"string","x-struct":null,"x-validate":null}},"required":["id","runtime","status"],"title":"Conversation","type":"object","x-struct":"Elixir.FountainWeb.Schemas.Conversation","x-validate":null},"EnvironmentListResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Environment"},"type":"array","x-struct":null,"x-validate":null}},"required":["data"],"title":"EnvironmentListResponse","type":"object","x-struct":"Elixir.FountainWeb.Schemas.EnvironmentListResponse","x-validate":null},"VaultSecretRequest":{"properties":{"key":{"type":"string","x-struct":null,"x-validate":null},"value":{"description":"Secret value (write-only).","type":"string","x-struct":null,"x-validate":null}},"required":["key","value"],"title":"VaultSecretRequest","type":"object","x-struct":"Elixir.FountainWeb.Schemas.VaultSecretRequest","x-validate":null},"PromptRequest":{"properties":{"images":{"description":"Optional images to attach to this prompt.","items":{"$ref":"#/components/schemas/ImageInput"},"nullable":true,"type":"array","x-struct":null,"x-validate":null},"prompt":{"type":"string","x-struct":null,"x-validate":null}},"required":["prompt"],"title":"PromptRequest","type":"object","x-struct":"Elixir.FountainWeb.Schemas.PromptRequest","x-validate":null},"Turn":{"description":"One prompt → exit_code cycle within a conversation.","properties":{"ended_at":{"format":"date-time","nullable":true,"type":"string","x-struct":null,"x-validate":null},"exit_code":{"nullable":true,"type":"integer","x-struct":null,"x-validate":null},"id":{"format":"uuid","type":"string","x-struct":null,"x-validate":null},"image_count":{"description":"Number of images attached to this turn.","type":"integer","x-struct":null,"x-validate":null},"inserted_at":{"format":"date-time","type":"string","x-struct":null,"x-validate":null},"prompt":{"type":"string","x-struct":null,"x-validate":null},"started_at":{"format":"date-time","nullable":true,"type":"string","x-struct":null,"x-validate":null},"status":{"enum":["pending","running","completed","failed","interrupted"],"type":"string","x-struct":null,"x-validate":null},"turn_number":{"type":"integer","x-struct":null,"x-validate":null}},"required":["id","turn_number","prompt","status"],"title":"Turn","type":"object","x-struct":"Elixir.FountainWeb.Schemas.Turn","x-validate":null},"VaultSecretListResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/VaultSecret"},"type":"array","x-struct":null,"x-validate":null}},"required":["data"],"title":"VaultSecretListResponse","type":"object","x-struct":"Elixir.FountainWeb.Schemas.VaultSecretListResponse","x-validate":null},"HealthResponse":{"properties":{"status":{"example":"ok","type":"string","x-struct":null,"x-validate":null}},"required":["status"],"title":"HealthResponse","type":"object","x-struct":"Elixir.FountainWeb.Schemas.HealthResponse","x-validate":null},"VaultResponse":{"properties":{"data":{"$ref":"#/components/schemas/Vault"}},"required":["data"],"title":"VaultResponse","type":"object","x-struct":"Elixir.FountainWeb.Schemas.VaultResponse","x-validate":null},"PromptResponse":{"properties":{"status":{"example":"queued","type":"string","x-struct":null,"x-validate":null}},"required":["status"],"title":"PromptResponse","type":"object","x-struct":"Elixir.FountainWeb.Schemas.PromptResponse","x-validate":null},"AgentListResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Agent"},"type":"array","x-struct":null,"x-validate":null}},"required":["data"],"title":"AgentListResponse","type":"object","x-struct":"Elixir.FountainWeb.Schemas.AgentListResponse","x-validate":null},"AgentUpdate":{"properties":{"allowed_vault_ids":{"description":"Vaults a conversation may attach to this agent. null (default) allows any vault the tenant owns; an empty list forbids attaching any vault; a non-empty list is an allowlist.","items":{"format":"uuid","type":"string","x-struct":null,"x-validate":null},"nullable":true,"type":"array","x-struct":null,"x-validate":null},"description":{"type":"string","x-struct":null,"x-validate":null},"environment_id":{"format":"uuid","nullable":true,"type":"string","x-struct":null,"x-validate":null},"mcp_servers":{"additionalProperties":true,"type":"object","x-struct":null,"x-validate":null},"metadata":{"additionalProperties":true,"type":"object","x-struct":null,"x-validate":null},"model":{"pattern":"^[a-z0-9_-]+/[a-z0-9._-]+$","type":"string","x-struct":null,"x-validate":null},"name":{"maxLength":200,"minLength":1,"type":"string","x-struct":null,"x-validate":null},"runtime":{"enum":["claude","codex","gemini","opencode"],"type":"string","x-struct":null,"x-validate":null},"skills":{"description":"Each entry is either inline (`{name, content}` — full SKILL.md text written to the sprite) or github (`{source, ref?, name?}` — installed on the sprite via the skills.sh CLI, optionally pinned to a tag/branch/sha via `ref`). Exactly one of `content` or `source` must be set on each entry.","items":{"properties":{"content":{"description":"Full SKILL.md body for inline entries.","type":"string","x-struct":null,"x-validate":null},"name":{"description":"Skill name (required for inline entries).","type":"string","x-struct":null,"x-validate":null},"ref":{"description":"Optional tag, branch, or sha pinning a github-sourced skill (installed as `owner/repo@ref`). Without it the default branch is fetched at spawn time.","pattern":"^[A-Za-z0-9._/-]+$","type":"string","x-struct":null,"x-validate":null},"source":{"description":"GitHub `owner/repo` for skills.sh-sourced entries.","pattern":"^[A-Za-z0-9._/-]+$","type":"string","x-struct":null,"x-validate":null}},"type":"object","x-struct":null,"x-validate":null},"type":"array","x-struct":null,"x-validate":null},"system":{"type":"string","x-struct":null,"x-validate":null}},"title":"AgentUpdate","type":"object","x-struct":"Elixir.FountainWeb.Schemas.AgentUpdate","x-validate":null},"ConversationListResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Conversation"},"type":"array","x-struct":null,"x-validate":null}},"required":["data"],"title":"ConversationListResponse","type":"object","x-struct":"Elixir.FountainWeb.Schemas.ConversationListResponse","x-validate":null},"VaultRequest":{"properties":{"description":{"type":"string","x-struct":null,"x-validate":null},"metadata":{"additionalProperties":true,"type":"object","x-struct":null,"x-validate":null},"name":{"maxLength":200,"minLength":1,"type":"string","x-struct":null,"x-validate":null}},"required":["name"],"title":"VaultRequest","type":"object","x-struct":"Elixir.FountainWeb.Schemas.VaultRequest","x-validate":null},"ConversationResponse":{"properties":{"data":{"$ref":"#/components/schemas/Conversation"}},"required":["data"],"title":"ConversationResponse","type":"object","x-struct":"Elixir.FountainWeb.Schemas.ConversationResponse","x-validate":null},"Vault":{"description":"A free-floating bag of env-var overrides selected at conversation creation. Vault values override an environment's baseline secrets when the same key is set on both.","properties":{"description":{"type":"string","x-struct":null,"x-validate":null},"id":{"format":"uuid","type":"string","x-struct":null,"x-validate":null},"inserted_at":{"format":"date-time","type":"string","x-struct":null,"x-validate":null},"metadata":{"additionalProperties":true,"type":"object","x-struct":null,"x-validate":null},"name":{"type":"string","x-struct":null,"x-validate":null},"updated_at":{"format":"date-time","type":"string","x-struct":null,"x-validate":null}},"required":["id","name"],"title":"Vault","type":"object","x-struct":"Elixir.FountainWeb.Schemas.Vault","x-validate":null},"SecretResponse":{"properties":{"data":{"$ref":"#/components/schemas/Secret"}},"required":["data"],"title":"SecretResponse","type":"object","x-struct":"Elixir.FountainWeb.Schemas.SecretResponse","x-validate":null},"SecretRequest":{"properties":{"key":{"type":"string","x-struct":null,"x-validate":null},"value":{"description":"Secret value (write-only).","type":"string","x-struct":null,"x-validate":null}},"required":["key","value"],"title":"SecretRequest","type":"object","x-struct":"Elixir.FountainWeb.Schemas.SecretRequest","x-validate":null},"AgentRequest":{"properties":{"allowed_vault_ids":{"description":"Vaults a conversation may attach to this agent. null (default) allows any vault the tenant owns; an empty list forbids attaching any vault; a non-empty list is an allowlist.","items":{"format":"uuid","type":"string","x-struct":null,"x-validate":null},"nullable":true,"type":"array","x-struct":null,"x-validate":null},"description":{"type":"string","x-struct":null,"x-validate":null},"environment_id":{"format":"uuid","nullable":true,"type":"string","x-struct":null,"x-validate":null},"mcp_servers":{"additionalProperties":true,"type":"object","x-struct":null,"x-validate":null},"metadata":{"additionalProperties":true,"type":"object","x-struct":null,"x-validate":null},"model":{"pattern":"^[a-z0-9_-]+/[a-z0-9._-]+$","type":"string","x-struct":null,"x-validate":null},"name":{"maxLength":200,"minLength":1,"type":"string","x-struct":null,"x-validate":null},"runtime":{"enum":["claude","codex","gemini","opencode"],"type":"string","x-struct":null,"x-validate":null},"skills":{"description":"Each entry is either inline (`{name, content}` — full SKILL.md text written to the sprite) or github (`{source, ref?, name?}` — installed on the sprite via the skills.sh CLI, optionally pinned to a tag/branch/sha via `ref`). Exactly one of `content` or `source` must be set on each entry.","items":{"properties":{"content":{"description":"Full SKILL.md body for inline entries.","type":"string","x-struct":null,"x-validate":null},"name":{"description":"Skill name (required for inline entries).","type":"string","x-struct":null,"x-validate":null},"ref":{"description":"Optional tag, branch, or sha pinning a github-sourced skill (installed as `owner/repo@ref`). Without it the default branch is fetched at spawn time.","pattern":"^[A-Za-z0-9._/-]+$","type":"string","x-struct":null,"x-validate":null},"source":{"description":"GitHub `owner/repo` for skills.sh-sourced entries.","pattern":"^[A-Za-z0-9._/-]+$","type":"string","x-struct":null,"x-validate":null}},"type":"object","x-struct":null,"x-validate":null},"type":"array","x-struct":null,"x-validate":null},"system":{"type":"string","x-struct":null,"x-validate":null}},"required":["name","model","runtime"],"title":"AgentRequest","type":"object","x-struct":"Elixir.FountainWeb.Schemas.AgentRequest","x-validate":null},"EnvironmentRequest":{"properties":{"env_vars":{"additionalProperties":{"type":"string","x-struct":null,"x-validate":null},"type":"object","x-struct":null,"x-validate":null},"metadata":{"additionalProperties":true,"type":"object","x-struct":null,"x-validate":null},"name":{"maxLength":200,"minLength":1,"type":"string","x-struct":null,"x-validate":null},"networking_config":{"additionalProperties":true,"description":"Refines networking_type: limited. allowed_hosts is the only key honored today; unknown keys are ignored. Under limited, egress is restricted to the allowlisted domains. With no allowed_hosts (or an empty list), the sandbox denies all egress by default — this is a deny-all, not an allow-all.","properties":{"allowed_hosts":{"description":"Domains the sandbox may reach when networking_type is limited.","items":{"type":"string","x-struct":null,"x-validate":null},"type":"array","x-struct":null,"x-validate":null}},"type":"object","x-struct":null,"x-validate":null},"networking_type":{"enum":["unrestricted","limited"],"type":"string","x-struct":null,"x-validate":null},"packages":{"additionalProperties":true,"type":"object","x-struct":null,"x-validate":null},"repositories":{"items":{"$ref":"#/components/schemas/Repository"},"type":"array","x-struct":null,"x-validate":null},"setup_script":{"type":"string","x-struct":null,"x-validate":null}},"required":["name"],"title":"EnvironmentRequest","type":"object","x-struct":"Elixir.FountainWeb.Schemas.EnvironmentRequest","x-validate":null},"Environment":{"description":"A reusable sandbox environment: packages, env vars, repos, networking.","properties":{"env_vars":{"additionalProperties":{"type":"string","x-struct":null,"x-validate":null},"type":"object","x-struct":null,"x-validate":null},"id":{"format":"uuid","type":"string","x-struct":null,"x-validate":null},"inserted_at":{"format":"date-time","type":"string","x-struct":null,"x-validate":null},"metadata":{"additionalProperties":true,"type":"object","x-struct":null,"x-validate":null},"name":{"type":"string","x-struct":null,"x-validate":null},"networking_config":{"additionalProperties":true,"description":"Refines networking_type: limited. allowed_hosts is the only key honored today; unknown keys are ignored. Under limited, egress is restricted to the allowlisted domains. With no allowed_hosts (or an empty list), the sandbox denies all egress by default — this is a deny-all, not an allow-all.","properties":{"allowed_hosts":{"description":"Domains the sandbox may reach when networking_type is limited.","items":{"type":"string","x-struct":null,"x-validate":null},"type":"array","x-struct":null,"x-validate":null}},"type":"object","x-struct":null,"x-validate":null},"networking_type":{"enum":["unrestricted","limited"],"type":"string","x-struct":null,"x-validate":null},"packages":{"additionalProperties":true,"type":"object","x-struct":null,"x-validate":null},"repositories":{"items":{"$ref":"#/components/schemas/Repository"},"type":"array","x-struct":null,"x-validate":null},"setup_script":{"type":"string","x-struct":null,"x-validate":null},"updated_at":{"format":"date-time","type":"string","x-struct":null,"x-validate":null}},"required":["id","name"],"title":"Environment","type":"object","x-struct":"Elixir.FountainWeb.Schemas.Environment","x-validate":null},"VaultListResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Vault"},"type":"array","x-struct":null,"x-validate":null}},"required":["data"],"title":"VaultListResponse","type":"object","x-struct":"Elixir.FountainWeb.Schemas.VaultListResponse","x-validate":null},"AgentResponse":{"properties":{"data":{"$ref":"#/components/schemas/Agent"}},"required":["data"],"title":"AgentResponse","type":"object","x-struct":"Elixir.FountainWeb.Schemas.AgentResponse","x-validate":null}},"securitySchemes":{"bearer":{"description":"ADMIN_TOKEN configured at boot.","scheme":"bearer","type":"http"}}},"info":{"description":"HTTP API for Agent on Demand. The same surface backs the LiveView UI\nand the `aod` CLI; if it's not here, it doesn't exist yet.\n\nAll `/api/*` endpoints require a bearer token (`ADMIN_TOKEN`).\n","title":"Agent on Demand","version":"0.1.0"},"openapi":"3.0.0","paths":{"/api/agents":{"get":{"callbacks":{},"operationId":"FountainWeb.AgentController.index","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentListResponse"}}},"description":"Agents"}},"summary":"List agents","tags":["Agents"]},"post":{"callbacks":{},"operationId":"FountainWeb.AgentController.create","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRequest"}}},"description":"Agent attributes","required":false},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}},"description":"Agent"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangesetError"}}},"description":"Validation error"}},"summary":"Create an agent","tags":["Agents"]}},"/api/agents/{id}":{"delete":{"callbacks":{},"operationId":"FountainWeb.AgentController.delete","parameters":[{"description":"","in":"path","name":"id","required":true,"schema":{"type":"string","x-struct":null,"x-validate":null}}],"responses":{"204":{"description":"Deleted"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not found"}},"summary":"Delete an agent","tags":["Agents"]},"get":{"callbacks":{},"operationId":"FountainWeb.AgentController.show","parameters":[{"description":"","in":"path","name":"id","required":true,"schema":{"type":"string","x-struct":null,"x-validate":null}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}},"description":"Agent"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not found"}},"summary":"Get an agent","tags":["Agents"]},"patch":{"callbacks":{},"description":"Every field is optional; the server merges into the existing record.","operationId":"FountainWeb.AgentController.update (2)","parameters":[{"description":"","in":"path","name":"id","required":true,"schema":{"type":"string","x-struct":null,"x-validate":null}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentUpdate"}}},"description":"Partial agent attributes","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}},"description":"Agent"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangesetError"}}},"description":"Validation error"}},"summary":"Update an agent (partial)","tags":["Agents"]},"put":{"callbacks":{},"description":"Every field is optional; the server merges into the existing record.","operationId":"FountainWeb.AgentController.update","parameters":[{"description":"","in":"path","name":"id","required":true,"schema":{"type":"string","x-struct":null,"x-validate":null}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentUpdate"}}},"description":"Partial agent attributes","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}},"description":"Agent"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangesetError"}}},"description":"Validation error"}},"summary":"Update an agent (partial)","tags":["Agents"]}},"/api/conversations":{"get":{"callbacks":{},"operationId":"FountainWeb.ConversationController.index","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationListResponse"}}},"description":"Conversations"}},"summary":"List conversations","tags":["Conversations"]},"post":{"callbacks":{},"description":"Creates a sandbox + conversation pair, starts the runtime in a fresh sprite, and (if `prompt` is supplied) sends it as turn 1. Pass `X-Fountain-Parent-Conversation-Id` header to record which conversation spawned this one. Legacy `X-AoD-Parent-Conversation-Id` is still accepted for sprites provisioned before the rename.","operationId":"FountainWeb.ConversationController.create","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationCreateRequest"}}},"description":"Conversation attrs","required":false},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationResponse"}}},"description":"Conversation"},"402":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string","x-struct":null,"x-validate":null},"upgrade_url":{"type":"string","x-struct":null,"x-validate":null}},"type":"object","x-struct":null,"x-validate":null}}},"description":"Subscription required"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Agent not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangesetError"}}},"description":"Validation error"}},"summary":"Start a conversation","tags":["Conversations"]}},"/api/conversations/{conversation_id}/interrupt":{"post":{"callbacks":{},"operationId":"FountainWeb.ConversationController.interrupt","parameters":[{"description":"","in":"path","name":"conversation_id","required":true,"schema":{"type":"string","x-struct":null,"x-validate":null}}],"responses":{"204":{"description":"Interrupted"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No turn running"}},"summary":"Interrupt the running turn","tags":["Conversations"]}},"/api/conversations/{conversation_id}/prompts":{"post":{"callbacks":{},"description":"Queues a new turn. If the ConversationServer has been GC'd (e.g. across a BEAM restart) a fresh sprite is provisioned and the runtime resumes via its session id.","operationId":"FountainWeb.ConversationController.prompt","parameters":[{"description":"","in":"path","name":"conversation_id","required":true,"schema":{"type":"string","x-struct":null,"x-validate":null}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptRequest"}}},"description":"Prompt","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptResponse"}}},"description":"Queued"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Busy"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not found"}},"summary":"Send another prompt","tags":["Conversations"]}},"/api/conversations/{conversation_id}/stream":{"get":{"callbacks":{},"description":"Server-Sent Events stream of the conversation's log events. The `Last-Event-ID` request header resumes from a known event id; missed events are replayed before the live tail begins. Keep-alive heartbeats every 15s as `: heartbeat` comments.","operationId":"FountainWeb.ConversationController.stream","parameters":[{"description":"","in":"path","name":"conversation_id","required":true,"schema":{"type":"string","x-struct":null,"x-validate":null}},{"description":"Resume after this event id (integer as string). Missing or unparseable values are treated as 0.","in":"header","name":"Last-Event-ID","required":false,"schema":{"type":"string","x-struct":null,"x-validate":null}}],"responses":{"200":{"content":{"text/event-stream":{"schema":{"type":"string","x-struct":null,"x-validate":null}}},"description":"SSE stream"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not found"}},"summary":"Stream log events (SSE)","tags":["Conversations"]}},"/api/conversations/{conversation_id}/terminate":{"post":{"callbacks":{},"description":"Tears down the sprite and marks the conversation `terminated`. Idempotent for already-dead conversations.","operationId":"FountainWeb.ConversationController.terminate","parameters":[{"description":"","in":"path","name":"conversation_id","required":true,"schema":{"type":"string","x-struct":null,"x-validate":null}}],"responses":{"204":{"description":"Terminated"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not found"}},"summary":"Terminate a conversation","tags":["Conversations"]}},"/api/conversations/{conversation_id}/turns":{"get":{"callbacks":{},"operationId":"FountainWeb.ConversationController.turns","parameters":[{"description":"","in":"path","name":"conversation_id","required":true,"schema":{"type":"string","x-struct":null,"x-validate":null}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TurnListResponse"}}},"description":"Turns"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not found"}},"summary":"List turns in a conversation","tags":["Conversations"]}},"/api/conversations/{id}":{"delete":{"callbacks":{},"description":"Tears down the sprite if alive, then deletes the conversation row (cascades to turns and log events).","operationId":"FountainWeb.ConversationController.delete","parameters":[{"description":"","in":"path","name":"id","required":true,"schema":{"type":"string","x-struct":null,"x-validate":null}}],"responses":{"204":{"description":"Deleted"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not found"}},"summary":"Delete a conversation","tags":["Conversations"]},"get":{"callbacks":{},"operationId":"FountainWeb.ConversationController.show","parameters":[{"description":"","in":"path","name":"id","required":true,"schema":{"type":"string","x-struct":null,"x-validate":null}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationResponse"}}},"description":"Conversation"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not found"}},"summary":"Get a conversation","tags":["Conversations"]}},"/api/environments":{"get":{"callbacks":{},"operationId":"FountainWeb.EnvironmentController.index","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentListResponse"}}},"description":"Environments"}},"summary":"List environments","tags":["Environments"]},"post":{"callbacks":{},"operationId":"FountainWeb.EnvironmentController.create","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentRequest"}}},"description":"Environment attributes","required":false},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentResponse"}}},"description":"Environment"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangesetError"}}},"description":"Validation error"}},"summary":"Create an environment","tags":["Environments"]}},"/api/environments/{environment_id}/secrets":{"get":{"callbacks":{},"operationId":"FountainWeb.SecretController.index","parameters":[{"description":"","in":"path","name":"environment_id","required":true,"schema":{"type":"string","x-struct":null,"x-validate":null}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecretListResponse"}}},"description":"Secrets"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not found"}},"summary":"List secrets in an environment","tags":["Secrets"]},"post":{"callbacks":{},"description":"Sets the value for `key`. If the key exists, the value is overwritten. Values are write-only — subsequent reads never return them.","operationId":"FountainWeb.SecretController.create","parameters":[{"description":"","in":"path","name":"environment_id","required":true,"schema":{"type":"string","x-struct":null,"x-validate":null}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecretRequest"}}},"description":"Secret","required":false},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecretResponse"}}},"description":"Secret"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangesetError"}}},"description":"Validation error"}},"summary":"Upsert a secret","tags":["Secrets"]}},"/api/environments/{environment_id}/secrets/{id}":{"delete":{"callbacks":{},"operationId":"FountainWeb.SecretController.delete","parameters":[{"description":"","in":"path","name":"environment_id","required":true,"schema":{"type":"string","x-struct":null,"x-validate":null}},{"description":"Secret key.","in":"path","name":"id","required":true,"schema":{"type":"string","x-struct":null,"x-validate":null}}],"responses":{"204":{"description":"Deleted"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not found"}},"summary":"Delete a secret by key","tags":["Secrets"]}},"/api/environments/{id}":{"delete":{"callbacks":{},"operationId":"FountainWeb.EnvironmentController.delete","parameters":[{"description":"","in":"path","name":"id","required":true,"schema":{"type":"string","x-struct":null,"x-validate":null}}],"responses":{"204":{"description":"Deleted"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not found"}},"summary":"Delete an environment","tags":["Environments"]},"get":{"callbacks":{},"operationId":"FountainWeb.EnvironmentController.show","parameters":[{"description":"","in":"path","name":"id","required":true,"schema":{"type":"string","x-struct":null,"x-validate":null}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentResponse"}}},"description":"Environment"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not found"}},"summary":"Get an environment","tags":["Environments"]},"patch":{"callbacks":{},"description":"Every field is optional; the server merges into the existing record.","operationId":"FountainWeb.EnvironmentController.update (2)","parameters":[{"description":"","in":"path","name":"id","required":true,"schema":{"type":"string","x-struct":null,"x-validate":null}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentUpdate"}}},"description":"Partial environment attributes","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentResponse"}}},"description":"Environment"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangesetError"}}},"description":"Validation error"}},"summary":"Update an environment (partial)","tags":["Environments"]},"put":{"callbacks":{},"description":"Every field is optional; the server merges into the existing record.","operationId":"FountainWeb.EnvironmentController.update","parameters":[{"description":"","in":"path","name":"id","required":true,"schema":{"type":"string","x-struct":null,"x-validate":null}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentUpdate"}}},"description":"Partial environment attributes","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentResponse"}}},"description":"Environment"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangesetError"}}},"description":"Validation error"}},"summary":"Update an environment (partial)","tags":["Environments"]}},"/api/vaults":{"get":{"callbacks":{},"operationId":"FountainWeb.VaultController.index","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VaultListResponse"}}},"description":"Vaults"}},"summary":"List vaults","tags":["Vaults"]},"post":{"callbacks":{},"operationId":"FountainWeb.VaultController.create","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VaultRequest"}}},"description":"Vault attributes","required":false},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VaultResponse"}}},"description":"Vault"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangesetError"}}},"description":"Validation error"}},"summary":"Create a vault","tags":["Vaults"]}},"/api/vaults/{id}":{"delete":{"callbacks":{},"operationId":"FountainWeb.VaultController.delete","parameters":[{"description":"","in":"path","name":"id","required":true,"schema":{"type":"string","x-struct":null,"x-validate":null}}],"responses":{"204":{"description":"Deleted"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not found"}},"summary":"Delete a vault","tags":["Vaults"]},"get":{"callbacks":{},"operationId":"FountainWeb.VaultController.show","parameters":[{"description":"","in":"path","name":"id","required":true,"schema":{"type":"string","x-struct":null,"x-validate":null}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VaultResponse"}}},"description":"Vault"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not found"}},"summary":"Get a vault","tags":["Vaults"]},"patch":{"callbacks":{},"description":"Every field is optional; the server merges into the existing record.","operationId":"FountainWeb.VaultController.update (2)","parameters":[{"description":"","in":"path","name":"id","required":true,"schema":{"type":"string","x-struct":null,"x-validate":null}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VaultUpdate"}}},"description":"Partial vault attributes","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VaultResponse"}}},"description":"Vault"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangesetError"}}},"description":"Validation error"}},"summary":"Update a vault (partial)","tags":["Vaults"]},"put":{"callbacks":{},"description":"Every field is optional; the server merges into the existing record.","operationId":"FountainWeb.VaultController.update","parameters":[{"description":"","in":"path","name":"id","required":true,"schema":{"type":"string","x-struct":null,"x-validate":null}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VaultUpdate"}}},"description":"Partial vault attributes","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VaultResponse"}}},"description":"Vault"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangesetError"}}},"description":"Validation error"}},"summary":"Update a vault (partial)","tags":["Vaults"]}},"/api/vaults/{vault_id}/secrets":{"get":{"callbacks":{},"operationId":"FountainWeb.VaultSecretController.index","parameters":[{"description":"","in":"path","name":"vault_id","required":true,"schema":{"type":"string","x-struct":null,"x-validate":null}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VaultSecretListResponse"}}},"description":"Vault Secrets"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not found"}},"summary":"List secrets in a vault","tags":["Vault Secrets"]},"post":{"callbacks":{},"description":"Sets the value for `key`. If the key exists, the value is overwritten. Values are write-only — subsequent reads never return them.","operationId":"FountainWeb.VaultSecretController.create","parameters":[{"description":"","in":"path","name":"vault_id","required":true,"schema":{"type":"string","x-struct":null,"x-validate":null}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VaultSecretRequest"}}},"description":"Vault Secret","required":false},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VaultSecretResponse"}}},"description":"Vault Secret"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangesetError"}}},"description":"Validation error"}},"summary":"Upsert a vault secret","tags":["Vault Secrets"]}},"/api/vaults/{vault_id}/secrets/{id}":{"delete":{"callbacks":{},"operationId":"FountainWeb.VaultSecretController.delete","parameters":[{"description":"","in":"path","name":"vault_id","required":true,"schema":{"type":"string","x-struct":null,"x-validate":null}},{"description":"Secret key.","in":"path","name":"id","required":true,"schema":{"type":"string","x-struct":null,"x-validate":null}}],"responses":{"204":{"description":"Deleted"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not found"}},"summary":"Delete a vault secret by key","tags":["Vault Secrets"]}},"/health":{"get":{"callbacks":{},"description":"Public, unauthenticated. Returns `{\"status\": \"ok\"}` if the app is up.","operationId":"FountainWeb.HealthController.show","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}},"description":"Health response"}},"security":[],"summary":"Liveness probe","tags":["Health"]}}},"security":[{"bearer":[]}],"servers":[{"url":"http://localhost:4000","variables":{}}],"tags":[]}

package/src/spec/parse.ts

@@ -0,0 +1,309 @@
+/**
+ * Fountain OpenAPI parser.
+ *
+ * Fountain's spec (OpenApiSpex, served at /api/openapi.json) is
+ * request/response DTOs, so we generate a curated set of resources — the
+ * three kinds `fountain apply` reconciles: Environment, Vault, Agent.
+ * Each pairs a request schema (writable authoring surface) with a response
+ * schema (read-only attributes). Object schemas reachable from the request
+ * schemas (e.g. Repository) are emitted as standalone property-type classes.
+ *
+ * Conversations are deliberately not a resource: they are runs with a
+ * status lifecycle, modeled as ops, not declarables.
+ */
+
+import {
+  extractConstraints as coreExtractConstraints,
+  primaryType,
+  isEnumDefinition,
+  type JsonSchemaProperty,
+  type PropertyConstraints,
+} from "@intentius/chant/codegen/json-schema";
+
+// ── Types ──────────────────────────────────────────────────────────
+
+export type { PropertyConstraints };
+
+export interface ParsedProperty {
+  name: string;
+  tsType: string;
+  required: boolean;
+  description?: string;
+  constraints: PropertyConstraints;
+}
+
+export interface ParsedResource {
+  typeName: string;
+  description?: string;
+  properties: ParsedProperty[];
+  attributes: Array<{ name: string; tsType: string }>;
+}
+
+export interface FountainParseResult {
+  resource: ParsedResource;
+  /** Always empty — fountain emits property types as standalone results. */
+  propertyTypes: Array<{ name: string; defType: string }>;
+  /** Always empty — enums are inlined as string-literal unions. */
+  enums: Array<{ name: string; values: string[] }>;
+  /** Whether this entity is a property type (nested config shape). */
+  isProperty?: boolean;
+}
+
+// ── OpenAPI types ──────────────────────────────────────────────────
+
+interface OpenAPISchema extends JsonSchemaProperty {
+  allOf?: OpenAPISchema[];
+  additionalProperties?: boolean | OpenAPISchema;
+  items?: OpenAPISchema;
+  properties?: Record<string, OpenAPISchema>;
+  nullable?: boolean;
+}
+
+interface OpenAPISpec {
+  components?: { schemas?: Record<string, OpenAPISchema> };
+}
+
+// ── Curated manifest ───────────────────────────────────────────────
+
+/** The single service segment for all fountain type names (apiVersion fountain.dev/v1). */
+const SERVICE = "V1";
+
+interface ResourceSpec {
+  typeName: string;
+  request: string;
+  response: string;
+}
+
+const RESOURCES: ResourceSpec[] = [
+  { typeName: `Fountain::${SERVICE}::Environment`, request: "EnvironmentRequest", response: "Environment" },
+  { typeName: `Fountain::${SERVICE}::Vault`, request: "VaultRequest", response: "Vault" },
+  { typeName: `Fountain::${SERVICE}::Agent`, request: "AgentRequest", response: "Agent" },
+];
+
+const REF_PREFIX = "#/components/schemas/";
+
+// ── Parser ─────────────────────────────────────────────────────────
+
+/**
+ * Parse the fountain OpenAPI spec into the curated resources and the
+ * property types reachable from their request schemas.
+ */
+export function parseFountainOpenAPI(data: string | Buffer): FountainParseResult[] {
+  const spec: OpenAPISpec = JSON.parse(typeof data === "string" ? data : data.toString("utf-8"));
+  const schemas = spec.components?.schemas ?? {};
+
+  const emitted = collectPropertyTypes(schemas);
+  const resolve = (prop: OpenAPISchema | undefined): string => resolveType(prop, schemas, emitted);
+
+  const results: FountainParseResult[] = [];
+
+  for (const rspec of RESOURCES) {
+    const req = schemas[rspec.request];
+    const res = schemas[rspec.response];
+    const reqProps = req?.properties ?? {};
+    const requiredSet = new Set(req?.required ?? []);
+
+    const properties: ParsedProperty[] = [];
+    for (const [name, prop] of Object.entries(reqProps)) {
+      properties.push({
+        name,
+        tsType: resolve(prop),
+        required: requiredSet.has(name),
+        description: prop.description,
+        constraints: coreExtractConstraints(prop as JsonSchemaProperty),
+      });
+    }
+
+    // Attributes = response props not present in the request schema.
+    const attributes: Array<{ name: string; tsType: string }> = [];
+    for (const [name, prop] of Object.entries(res?.properties ?? {})) {
+      if (name in reqProps) continue;
+      attributes.push({ name, tsType: resolve(prop) });
+    }
+
+    results.push({
+      resource: {
+        typeName: rspec.typeName,
+        description: res?.description ?? req?.description,
+        properties,
+        attributes,
+      },
+      propertyTypes: [],
+      enums: [],
+    });
+  }
+
+  for (const schemaName of emitted) {
+    const def = schemas[schemaName];
+    const requiredSet = new Set(def.required ?? []);
+    const properties: ParsedProperty[] = [];
+    for (const [name, prop] of Object.entries(def.properties ?? {})) {
+      properties.push({
+        name,
+        tsType: resolve(prop),
+        required: requiredSet.has(name),
+        description: prop.description,
+        constraints: coreExtractConstraints(prop as JsonSchemaProperty),
+      });
+    }
+    results.push({
+      resource: {
+        typeName: `Fountain::${SERVICE}::${schemaToClassName(schemaName)}`,
+        description: def.description,
+        properties,
+        attributes: [],
+      },
+      propertyTypes: [],
+      enums: [],
+      isProperty: true,
+    });
+  }
+
+  return results;
+}
+
+/**
+ * Walk the request schemas and collect the set of object schemas reachable
+ * through their properties (following $ref, allOf, arrays, and maps).
+ */
+function collectPropertyTypes(schemas: Record<string, OpenAPISchema>): string[] {
+  const emitted = new Set<string>();
+  const queue: string[] = [];
+
+  const seedFrom = (node: unknown) => {
+    for (const ref of collectRefs(node)) {
+      const target = schemas[ref];
+      if (!target) continue;
+      if (isObjectSchema(target) && !emitted.has(ref)) {
+        emitted.add(ref);
+        queue.push(ref);
+      }
+    }
+  };
+
+  for (const spec of RESOURCES) {
+    seedFrom(schemas[spec.request]?.properties);
+  }
+  while (queue.length > 0) {
+    const name = queue.shift()!;
+    seedFrom(schemas[name]?.properties);
+  }
+
+  return [...emitted];
+}
+
+/** Collect every `#/components/schemas/X` ref name nested anywhere in a node. */
+function collectRefs(node: unknown, acc: Set<string> = new Set()): Set<string> {
+  if (!node || typeof node !== "object") return acc;
+  if (Array.isArray(node)) {
+    for (const item of node) collectRefs(item, acc);
+    return acc;
+  }
+  const obj = node as Record<string, unknown>;
+  const ref = obj.$ref;
+  if (typeof ref === "string" && ref.startsWith(REF_PREFIX)) acc.add(ref.slice(REF_PREFIX.length));
+  for (const [key, value] of Object.entries(obj)) {
+    if (key === "$ref") continue;
+    collectRefs(value, acc);
+  }
+  return acc;
+}
+
+/** An object schema with properties (not a pure enum). */
+function isObjectSchema(def: OpenAPISchema): boolean {
+  return !!def.properties && Object.keys(def.properties).length > 0 && !isEnumDefinition(def);
+}
+
+// ── Type resolution ────────────────────────────────────────────────
+
+function resolveType(
+  prop: OpenAPISchema | undefined,
+  schemas: Record<string, OpenAPISchema>,
+  emitted: string[],
+): string {
+  if (!prop) return "any";
+
+  if (prop.$ref) return resolveRefType(prop.$ref, schemas, emitted);
+
+  if (prop.allOf && prop.allOf.length > 0) {
+    const withRef = prop.allOf.find((s) => s.$ref);
+    if (withRef?.$ref) return resolveRefType(withRef.$ref, schemas, emitted);
+  }
+
+  if (prop.enum && prop.enum.length > 0) {
+    return [...prop.enum].sort().map((v) => JSON.stringify(v)).join(" | ");
+  }
+
+  const pt = primaryType(prop.type);
+  switch (pt) {
+    case "string":
+      return "string";
+    case "integer":
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "array": {
+      if (prop.items) {
+        const itemType = resolveType(prop.items, schemas, emitted);
+        return itemType.includes(" | ") ? `(${itemType})[]` : `${itemType}[]`;
+      }
+      return "any[]";
+    }
+    case "object":
+      if (prop.additionalProperties && typeof prop.additionalProperties === "object") {
+        return `Record<string, ${resolveType(prop.additionalProperties, schemas, emitted)}>`;
+      }
+      return "Record<string, any>";
+    default:
+      return "any";
+  }
+}
+
+/** Resolve a `#/components/schemas/X` ref to a TypeScript type. */
+function resolveRefType(ref: string, schemas: Record<string, OpenAPISchema>, emitted: string[]): string {
+  if (!ref.startsWith(REF_PREFIX)) return "any";
+  const name = ref.slice(REF_PREFIX.length);
+  const def = schemas[name];
+  if (!def) return "any";
+
+  if (emitted.includes(name)) return schemaToClassName(name);
+
+  if (isEnumDefinition(def)) {
+    return [...(def.enum ?? [])].sort().map((v) => JSON.stringify(v)).join(" | ");
+  }
+
+  if (def.properties) return "Record<string, any>";
+
+  const pt = primaryType(def.type);
+  switch (pt) {
+    case "string":
+      return "string";
+    case "integer":
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    default:
+      return "any";
+  }
+}
+
+// ── Naming helpers ─────────────────────────────────────────────────
+
+/** Convert a schema name into a PascalCase class-name segment. */
+export function schemaToClassName(schemaName: string): string {
+  return schemaName.charAt(0).toUpperCase() + schemaName.slice(1);
+}
+
+/** Extract short name: "Fountain::V1::Agent" → "Agent". */
+export function fountainShortName(typeName: string): string {
+  const parts = typeName.split("::");
+  return parts[parts.length - 1];
+}
+
+/** Extract service name: "Fountain::V1::Agent" → "V1". */
+export function fountainServiceName(typeName: string): string {
+  const parts = typeName.split("::");
+  return parts.length >= 2 ? parts[1] : SERVICE;
+}

package/src/validate-cli.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env tsx
+import { validate } from "./validate";
+import { printValidationResult } from "@intentius/chant/codegen/validate";
+
+// `validate` takes an optional { basePath }; defaults to the lexicon root.
+// printValidationResult throws on failure — the catch turns that into a
+// nonzero exit so `npm run validate` (and prepack) actually gate on it.
+try {
+  printValidationResult(await validate());
+} catch (err) {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+}

package/src/validate.ts

@@ -0,0 +1,34 @@
+/**
+ * Validate generated lexicon-fountain artifacts.
+ *
+ * Thin wrapper around the core validation framework
+ * with fountain-specific configuration.
+ */
+
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { validateLexiconArtifacts, type ValidateResult } from "@intentius/chant/codegen/validate";
+
+export type { ValidateCheck, ValidateResult } from "@intentius/chant/codegen/validate";
+
+/**
+ * The curated surface, as named in spec/parse.ts. A regeneration that
+ * loses one — an upstream rename, a spec fetch that returned a partial
+ * document — must fail validation rather than ship a lexicon missing a
+ * kind. Repository is included: it is the one property type reachable
+ * from the request schemas, and its absence means ref-following broke.
+ */
+const REQUIRED_NAMES: string[] = ["Environment", "Vault", "Agent", "Repository"];
+
+/**
+ * Validate the generated lexicon-fountain artifacts.
+ */
+export async function validate(opts?: { basePath?: string }): Promise<ValidateResult> {
+  const basePath = opts?.basePath ?? dirname(dirname(fileURLToPath(import.meta.url)));
+
+  return validateLexiconArtifacts({
+    lexiconJsonFilename: "lexicon-fountain.json",
+    requiredNames: REQUIRED_NAMES,
+    basePath,
+  });
+}