@intentius/chant-lexicon-fountain 0.33.0

package/src/lsp/hover.ts

@@ -0,0 +1,70 @@
+import { createRequire } from "module";
+import type { HoverContext, HoverInfo } from "@intentius/chant/lsp/types";
+import { LexiconIndex, lexiconHover, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
+const require = createRequire(import.meta.url);
+
+let cachedIndex: LexiconIndex | null = null;
+
+function getIndex(): LexiconIndex {
+  if (cachedIndex) return cachedIndex;
+  const data = require("../generated/lexicon-fountain.json") as Record<string, LexiconEntry>;
+  cachedIndex = new LexiconIndex(data);
+  return cachedIndex;
+}
+
+/**
+ * Per-kind notes. The security-relevant semantics (deny-all networking,
+ * vault precedence, conversation-scoped vault attachment) are the ones an
+ * author gets wrong from the property names alone, so hover carries them
+ * rather than leaving them to the skills.
+ */
+const KIND_NOTES: Record<string, string> = {
+  Environment:
+    "Sandbox baseline — packages, repositories, env_vars, secrets, networking.\n\n" +
+    "`networking_type: limited` restricts egress to `networking_config.allowed_hosts`; " +
+    "an empty list denies all egress. `unrestricted` is open — FTN010/FTN011 flag both silence and openness.",
+  Vault:
+    "Env-var overrides attached at conversation create. Vault values win on key " +
+    "collision with the environment, silently — FTN014 surfaces the shadowing in review.",
+  Agent:
+    "A runnable agent config bound to one Environment. `allowed_vault_ids`: " +
+    "`null` allows any tenant vault, `[]` forbids all, a list is an allowlist — " +
+    "set `[]` when the reviewed environment must not be overridable at spawn.",
+};
+
+/** Enum-valued props are worth spelling out inline — they are the typo surface. */
+function enumLines(entry: LexiconEntry): string[] {
+  const constraints = entry.propertyConstraints as
+    | Record<string, { enum?: unknown[] }>
+    | undefined;
+  if (!constraints) return [];
+
+  const lines: string[] = [];
+  for (const [prop, c] of Object.entries(constraints)) {
+    if (!Array.isArray(c?.enum) || c.enum.length === 0) continue;
+    lines.push(`- \`${prop}\`: ${c.enum.map((v) => `\`${String(v)}\``).join(" | ")}`);
+  }
+  return lines;
+}
+
+function fountainHover(className: string, entry: LexiconEntry): HoverInfo | undefined {
+  const lines: string[] = [`**${className}**`, "", `Fountain type: \`${entry.resourceType}\``];
+
+  if (entry.kind === "property") {
+    lines.push("", "*Property type — a nested shape, not a standalone declarable.*");
+    return { contents: lines.join("\n") };
+  }
+
+  const note = KIND_NOTES[className];
+  if (note) lines.push("", note);
+
+  const enums = enumLines(entry);
+  if (enums.length > 0) lines.push("", "Enumerated properties:", ...enums);
+
+  return { contents: lines.join("\n") };
+}
+
+/** Provide LSP hover information for fountain resources. */
+export function hover(ctx: HoverContext): HoverInfo | undefined {
+  return lexiconHover(ctx, getIndex(), fountainHover);
+}

package/src/op/activities/fountain-apply.test.ts

@@ -0,0 +1,208 @@
+import { describe, expect, it } from "vitest";
+import {
+  fountainApply,
+  splitSecrets,
+  isChantOwned,
+  resolveEndpoint,
+  parsePlan,
+  type FountainHttp,
+  type FountainPlan,
+} from "./fountain-apply";
+import { fountainRun } from "./fountain-run";
+
+interface Call {
+  method: string;
+  path: string;
+  body?: unknown;
+}
+
+/** Scripted fake http: records calls, answers from a route table. */
+function fakeHttp(routes: Record<string, { status: number; json?: unknown }>): {
+  http: FountainHttp;
+  calls: Call[];
+} {
+  const calls: Call[] = [];
+  const http: FountainHttp = async (method, path, body) => {
+    calls.push({ method, path, body });
+    const key = `${method} ${path}`;
+    const hit = routes[key];
+    if (!hit) throw new Error(`unrouted: ${key}`);
+    return { status: hit.status, json: hit.json ?? null };
+  };
+  return { http, calls };
+}
+
+const EMPTY_LISTS = {
+  "GET /api/environments": { status: 200, json: { data: [] } },
+  "GET /api/vaults": { status: 200, json: { data: [] } },
+  "GET /api/agents": { status: 200, json: { data: [] } },
+};
+
+describe("pure helpers", () => {
+  it("resolveEndpoint precedence: arg > env > default", () => {
+    expect(resolveEndpoint({ endpoint: "http://x/" }, {})).toBe("http://x");
+    expect(resolveEndpoint({}, { FOUNTAIN_ENDPOINT: "http://env" })).toBe("http://env");
+    expect(resolveEndpoint({}, {})).toBe("https://founta.inevitable.fyi");
+  });
+
+  it("splitSecrets extracts valid entries and leaves the body clean", () => {
+    const { body, secrets } = splitSecrets({
+      name: "e",
+      secrets: [{ key: "K", value: "v" }, { bogus: true }],
+    });
+    expect(body).toEqual({ name: "e" });
+    expect(secrets).toEqual([{ key: "K", value: "v" }]);
+  });
+
+  it("isChantOwned keys on the metadata marker", () => {
+    expect(isChantOwned({ metadata: { "managed-by": "chant" } })).toBe(true);
+    expect(isChantOwned({ metadata: { "managed-by": "human" } })).toBe(false);
+    expect(isChantOwned({})).toBe(false);
+  });
+});
+
+describe("fountainApply", () => {
+  it("creates in Environment -> Vault -> Agent order and resolves the environment ref", async () => {
+    const plan: FountainPlan = {
+      researcher: {
+        kind: "Agent",
+        spec: { name: "researcher", model: "a/m", runtime: "claude", environment: "conciergeEnv" },
+      },
+      conciergeEnv: { kind: "Environment", spec: { name: "concierge-env", networking_type: "limited" } },
+    };
+
+    const { http, calls } = fakeHttp({
+      ...EMPTY_LISTS,
+      "POST /api/environments": { status: 201, json: { data: { id: "env-1" } } },
+      "POST /api/agents": { status: 201, json: { data: { id: "agent-1" } } },
+    });
+
+    const summary = await fountainApply({ planContent: JSON.stringify(plan) }, http);
+
+    const mutations = calls.filter((c) => c.method === "POST");
+    expect(mutations.map((c) => c.path)).toEqual(["/api/environments", "/api/agents"]);
+    const agentBody = mutations[1].body as Record<string, unknown>;
+    expect(agentBody.environment_id).toBe("env-1");
+    expect(agentBody.environment).toBeUndefined();
+    expect(summary.created).toEqual(["Environment/concierge-env", "Agent/researcher"]);
+  });
+
+  it("updates by name when the resource already exists", async () => {
+    const plan: FountainPlan = {
+      v: { kind: "Vault", spec: { name: "staging-creds", description: "d" } },
+    };
+    const { http, calls } = fakeHttp({
+      ...EMPTY_LISTS,
+      "GET /api/vaults": { status: 200, json: { data: [{ id: "v-9", name: "staging-creds" }] } },
+      "PUT /api/vaults/v-9": { status: 200, json: { data: { id: "v-9" } } },
+    });
+
+    const summary = await fountainApply({ planContent: JSON.stringify(plan) }, http);
+    expect(summary.updated).toEqual(["Vault/staging-creds"]);
+    expect(calls.some((c) => c.method === "PUT" && c.path === "/api/vaults/v-9")).toBe(true);
+  });
+
+  it("upserts secrets through the sub-resource", async () => {
+    const plan: FountainPlan = {
+      e: {
+        kind: "Environment",
+        spec: { name: "e", secrets: [{ key: "OPENAI_API_KEY", value: "${FROM_PROVIDER}" }] },
+      },
+    };
+    const { http, calls } = fakeHttp({
+      ...EMPTY_LISTS,
+      "POST /api/environments": { status: 201, json: { data: { id: "env-1" } } },
+      "POST /api/environments/env-1/secrets": { status: 201 },
+    });
+
+    const summary = await fountainApply({ planContent: JSON.stringify(plan) }, http);
+    expect(summary.secretsUpserted).toBe(1);
+    const create = calls.find((c) => c.method === "POST" && c.path === "/api/environments")!;
+    expect((create.body as Record<string, unknown>).secrets).toBeUndefined();
+  });
+
+  it("prunes only chant-owned resources, in reverse kind order", async () => {
+    const plan: FountainPlan = {};
+    const { http, calls } = fakeHttp({
+      "GET /api/environments": {
+        status: 200,
+        json: { data: [{ id: "e-1", name: "owned-env", metadata: { "managed-by": "chant" } }] },
+      },
+      "GET /api/vaults": { status: 200, json: { data: [] } },
+      "GET /api/agents": {
+        status: 200,
+        json: {
+          data: [
+            { id: "a-1", name: "owned-agent", metadata: { "managed-by": "chant" } },
+            { id: "a-2", name: "human-agent", metadata: {} },
+          ],
+        },
+      },
+      "DELETE /api/agents/a-1": { status: 204 },
+      "DELETE /api/environments/e-1": { status: 204 },
+    });
+
+    const summary = await fountainApply({ planContent: "{}", prune: true }, http);
+    const deletes = calls.filter((c) => c.method === "DELETE").map((c) => c.path);
+    expect(deletes).toEqual(["/api/agents/a-1", "/api/environments/e-1"]);
+    expect(summary.pruned).toEqual(["Agent/owned-agent", "Environment/owned-env"]);
+  });
+
+  it("parsePlan round-trips", () => {
+    const plan = parsePlan('{"e":{"kind":"Environment","spec":{"name":"e"}}}');
+    expect(plan.e.kind).toBe("Environment");
+  });
+});
+
+describe("fountainRun", () => {
+  it("resolves the agent by name, starts, and polls to a terminal status", async () => {
+    let polls = 0;
+    const http: FountainHttp = async (method, path, body) => {
+      if (path.startsWith("/api/agents?search=")) {
+        return { status: 200, json: { data: [{ id: "agent-1", name: "researcher" }] } };
+      }
+      if (method === "POST" && path === "/api/conversations") {
+        expect((body as Record<string, unknown>).agent_id).toBe("agent-1");
+        return { status: 201, json: { data: { id: "conv-1" } } };
+      }
+      if (method === "GET" && path === "/api/conversations/conv-1") {
+        polls += 1;
+        return {
+          status: 200,
+          json: { data: { status: polls < 3 ? "running" : "completed" } },
+        };
+      }
+      throw new Error(`unrouted: ${method} ${path}`);
+    };
+
+    const result = await fountainRun(
+      { agent: "researcher", prompt: "hi", pollMs: 1, sleep: async () => {} },
+      http,
+    );
+    expect(result).toEqual({ conversationId: "conv-1", status: "completed", terminatedByDeadline: false });
+  });
+
+  it("terminates the conversation when the deadline passes", async () => {
+    const calls: string[] = [];
+    const http: FountainHttp = async (method, path) => {
+      calls.push(`${method} ${path}`);
+      if (path === "/api/conversations" && method === "POST") {
+        return { status: 201, json: { data: { id: "conv-2" } } };
+      }
+      if (method === "GET") return { status: 200, json: { data: { status: "running" } } };
+      return { status: 200, json: null };
+    };
+
+    const result = await fountainRun(
+      {
+        agent: "123e4567-e89b-42d3-a456-426614174000",
+        timeoutMs: 1,
+        pollMs: 1,
+        sleep: async () => {},
+      },
+      http,
+    );
+    expect(result.terminatedByDeadline).toBe(true);
+    expect(calls).toContain("POST /api/conversations/conv-2/terminate");
+  });
+});

package/src/op/activities/fountain-apply.ts

@@ -0,0 +1,249 @@
+/**
+ * fountain native applier.
+ *
+ * Direct-REST reconciler against fountain's API (the same surface
+ * `fountain apply` uses, but API-first: create-if-new, update-if-changed
+ * by name, optional owned-only prune). Input is the serializer's
+ * `fountain-plan.json` sidecar — entity name → { kind, spec } — so no
+ * YAML parsing happens on the apply side.
+ *
+ * Apply order is Environment → Vault → Agent: agents reference their
+ * environment by entity name in the plan, resolved to the live id here
+ * (mirroring the CLI's name→id resolution in apply.go).
+ *
+ * Secrets: `spec.secrets` entries ({key, value}) are stripped from the
+ * resource body and upserted through the secrets sub-resource. Values are
+ * write-only upstream, so this is upsert-always — a changed value cannot
+ * be detected, only overwritten. (BinaryBourbon/fountain#148's reference
+ * model would make this a plain diff; until then, upsert-always is the
+ * honest semantic.)
+ *
+ * Endpoint/token resolution: explicit args win, then FOUNTAIN_ENDPOINT /
+ * FOUNTAIN_TOKEN, then the hosted default endpoint.
+ */
+
+import { readFileSync } from "node:fs";
+
+export const DEFAULT_FOUNTAIN_BASE_URL = "https://founta.inevitable.fyi";
+
+/** Ownership marker checked by the owned-only prune. */
+export const OWNERSHIP_KEY = "managed-by";
+export const OWNERSHIP_VALUE = "chant";
+
+const KIND_PATHS: Record<string, string> = {
+  Environment: "environments",
+  Vault: "vaults",
+  Agent: "agents",
+};
+
+/** Environments before vaults before agents; prune runs in reverse. */
+const APPLY_ORDER = ["Environment", "Vault", "Agent"] as const;
+
+export interface PlanEntry {
+  kind: string;
+  spec: Record<string, unknown>;
+}
+
+export type FountainPlan = Record<string, PlanEntry>;
+
+export interface FountainHttp {
+  (method: string, path: string, body?: unknown): Promise<{ status: number; json: unknown }>;
+}
+
+export interface FountainApplyArgs {
+  /** Path to the serializer's fountain-plan.json. */
+  planPath?: string;
+  /** Inline plan content (takes precedence over planPath). */
+  planContent?: string;
+  endpoint?: string;
+  token?: string;
+  /** Delete chant-owned resources absent from the plan. Off by default. */
+  prune?: boolean;
+}
+
+export interface FountainApplySummary {
+  created: string[];
+  updated: string[];
+  pruned: string[];
+  secretsUpserted: number;
+}
+
+// ── Pure helpers ──────────────────────────────────────────────────────────
+
+export function resolveEndpoint(
+  args: { endpoint?: string } = {},
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const base = args.endpoint || env.FOUNTAIN_ENDPOINT || DEFAULT_FOUNTAIN_BASE_URL;
+  return base.replace(/\/$/, "");
+}
+
+export function resolveToken(
+  args: { token?: string } = {},
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const token = args.token || env.FOUNTAIN_TOKEN;
+  if (!token) throw new Error("fountainApply: no token — set FOUNTAIN_TOKEN or pass token");
+  return token;
+}
+
+export function parsePlan(content: string): FountainPlan {
+  return JSON.parse(content) as FountainPlan;
+}
+
+/** Split spec.secrets ({key, value}[]) from the resource body. Pure. */
+export function splitSecrets(spec: Record<string, unknown>): {
+  body: Record<string, unknown>;
+  secrets: Array<{ key: string; value: string }>;
+} {
+  const { secrets, ...body } = spec;
+  if (!Array.isArray(secrets)) return { body: spec, secrets: [] };
+  const valid = secrets.filter(
+    (s): s is { key: string; value: string } =>
+      !!s && typeof s === "object" && typeof (s as { key?: unknown }).key === "string",
+  );
+  return { body, secrets: valid };
+}
+
+/** Is a live resource chant-owned (by its metadata marker)? Pure. */
+export function isChantOwned(resource: { metadata?: unknown }): boolean {
+  const meta = resource.metadata;
+  if (!meta || typeof meta !== "object") return false;
+  return (meta as Record<string, unknown>)[OWNERSHIP_KEY] === OWNERSHIP_VALUE;
+}
+
+// ── HTTP ──────────────────────────────────────────────────────────────────
+
+export function defaultFountainHttp(endpoint: string, token: string): FountainHttp {
+  return async (method, path, body) => {
+    const res = await fetch(`${endpoint}${path}`, {
+      method,
+      headers: {
+        authorization: `Bearer ${token}`,
+        ...(body !== undefined ? { "content-type": "application/json" } : {}),
+      },
+      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    });
+    let json: unknown = null;
+    try {
+      json = await res.json();
+    } catch {
+      // 204s and empty bodies are fine.
+    }
+    return { status: res.status, json };
+  };
+}
+
+// ── Applier ───────────────────────────────────────────────────────────────
+
+interface LiveResource {
+  id: string;
+  name: string;
+  metadata?: Record<string, unknown>;
+}
+
+async function listByName(http: FountainHttp, kind: string): Promise<Map<string, LiveResource>> {
+  const { status, json } = await http("GET", `/api/${KIND_PATHS[kind]}`);
+  if (status !== 200) throw new Error(`fountainApply: list ${kind} failed (${status})`);
+  const data = (json as { data?: LiveResource[] })?.data ?? [];
+  return new Map(data.map((r) => [r.name, r]));
+}
+
+export async function fountainApply(
+  args: FountainApplyArgs,
+  http?: FountainHttp,
+): Promise<FountainApplySummary> {
+  const content = args.planContent ?? readFileSync(args.planPath!, "utf-8");
+  const plan = parsePlan(content);
+
+  const endpoint = resolveEndpoint(args);
+  const client = http ?? defaultFountainHttp(endpoint, resolveToken(args));
+
+  const summary: FountainApplySummary = { created: [], updated: [], pruned: [], secretsUpserted: 0 };
+  const idByKindAndName = new Map<string, string>();
+  const live = new Map<string, Map<string, LiveResource>>();
+  for (const kind of APPLY_ORDER) {
+    live.set(kind, await listByName(client, kind));
+  }
+
+  for (const kind of APPLY_ORDER) {
+    for (const [entityName, entry] of Object.entries(plan)) {
+      if (entry.kind !== kind) continue;
+
+      const { body, secrets } = splitSecrets(entry.spec);
+      const payload: Record<string, unknown> = { ...body };
+      // Manifest identity: the fountain resource is named after the spec's
+      // own `name` when present, else the entity name.
+      const resourceName = typeof payload.name === "string" ? (payload.name as string) : entityName;
+      payload.name = resourceName;
+
+      // Agent environment ref: the plan carries the referenced *entity*
+      // name; resolve through the id map (created this run) or live state.
+      if (kind === "Agent" && typeof payload.environment === "string") {
+        const refEntity = payload.environment as string;
+        const refPlanEntry = plan[refEntity];
+        const refResourceName =
+          refPlanEntry && typeof refPlanEntry.spec.name === "string"
+            ? (refPlanEntry.spec.name as string)
+            : refEntity;
+        const envId =
+          idByKindAndName.get(`Environment/${refEntity}`) ??
+          live.get("Environment")?.get(refResourceName)?.id;
+        if (!envId) throw new Error(`fountainApply: agent "${entityName}" references unknown environment "${refEntity}"`);
+        delete payload.environment;
+        payload.environment_id = envId;
+      }
+
+      const existing = live.get(kind)!.get(resourceName);
+      let id: string;
+      if (existing) {
+        const { status } = await client("PUT", `/api/${KIND_PATHS[kind]}/${existing.id}`, payload);
+        if (status !== 200) throw new Error(`fountainApply: update ${kind} "${resourceName}" failed (${status})`);
+        id = existing.id;
+        summary.updated.push(`${kind}/${resourceName}`);
+      } else {
+        const { status, json } = await client("POST", `/api/${KIND_PATHS[kind]}`, payload);
+        if (status !== 201 && status !== 200) {
+          throw new Error(`fountainApply: create ${kind} "${resourceName}" failed (${status})`);
+        }
+        id = (json as { data?: { id?: string } })?.data?.id ?? "";
+        summary.created.push(`${kind}/${resourceName}`);
+      }
+      idByKindAndName.set(`${kind}/${entityName}`, id);
+
+      // Secrets sub-resource: upsert-always (values are write-only upstream).
+      if (secrets.length > 0 && (kind === "Environment" || kind === "Vault")) {
+        for (const secret of secrets) {
+          const { status } = await client("POST", `/api/${KIND_PATHS[kind]}/${id}/secrets`, secret);
+          if (status !== 200 && status !== 201) {
+            throw new Error(`fountainApply: secret upsert on ${kind} "${resourceName}" failed (${status})`);
+          }
+          summary.secretsUpserted += 1;
+        }
+      }
+    }
+  }
+
+  if (args.prune) {
+    const planned = new Set<string>();
+    for (const [entityName, entry] of Object.entries(plan)) {
+      const resourceName =
+        typeof entry.spec.name === "string" ? (entry.spec.name as string) : entityName;
+      planned.add(`${entry.kind}/${resourceName}`);
+    }
+    // Reverse order: agents first, then vaults, then environments.
+    for (const kind of [...APPLY_ORDER].reverse()) {
+      for (const [name, resource] of live.get(kind)!) {
+        if (planned.has(`${kind}/${name}`)) continue;
+        if (!isChantOwned(resource)) continue;
+        const { status } = await client("DELETE", `/api/${KIND_PATHS[kind]}/${resource.id}`);
+        if (status !== 204 && status !== 200) {
+          throw new Error(`fountainApply: prune ${kind} "${name}" failed (${status})`);
+        }
+        summary.pruned.push(`${kind}/${name}`);
+      }
+    }
+  }
+
+  return summary;
+}

package/src/op/activities/fountain-run.ts

@@ -0,0 +1,95 @@
+/**
+ * fountainRun — start a conversation from a declared Agent and follow it
+ * to a terminal status.
+ *
+ * Conversations are runs, not declarables (the one fountain kind the
+ * lexicon deliberately does not model as a resource). This op is the
+ * imperative half: resolve the agent by name, POST the conversation,
+ * poll until `completed | failed | timed_out | terminated`, and terminate
+ * on deadline so a hung run never outlives the op that started it.
+ */
+
+import {
+  resolveEndpoint,
+  resolveToken,
+  defaultFountainHttp,
+  type FountainHttp,
+} from "./fountain-apply";
+
+export const TERMINAL_STATUSES = new Set(["completed", "failed", "timed_out", "terminated"]);
+
+export interface FountainRunArgs {
+  /** Agent name (resolved against /api/agents) or a raw agent id. */
+  agent: string;
+  prompt?: string;
+  /** Optional vault to attach (subject to the agent's allowlist upstream). */
+  vaultId?: string;
+  endpoint?: string;
+  token?: string;
+  /** Give up (and terminate the conversation) after this long. Default 10 min. */
+  timeoutMs?: number;
+  /** Poll interval. Default 5s. */
+  pollMs?: number;
+  /** Injectable clock/sleep for tests. */
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export interface FountainRunResult {
+  conversationId: string;
+  status: string;
+  /** True when the op hit its deadline and terminated the conversation. */
+  terminatedByDeadline: boolean;
+}
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export async function resolveAgentId(http: FountainHttp, agent: string): Promise<string> {
+  if (UUID_RE.test(agent)) return agent;
+  const { status, json } = await http("GET", `/api/agents?search=${encodeURIComponent(agent)}`);
+  if (status !== 200) throw new Error(`fountainRun: agent lookup failed (${status})`);
+  const data = (json as { data?: Array<{ id: string; name: string }> })?.data ?? [];
+  const exact = data.find((a) => a.name === agent);
+  if (!exact) throw new Error(`fountainRun: no agent named "${agent}"`);
+  return exact.id;
+}
+
+export async function fountainRun(
+  args: FountainRunArgs,
+  http?: FountainHttp,
+): Promise<FountainRunResult> {
+  const endpoint = resolveEndpoint(args);
+  const client = http ?? defaultFountainHttp(endpoint, resolveToken(args));
+  const sleep = args.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+  const timeoutMs = args.timeoutMs ?? 600_000;
+  const pollMs = args.pollMs ?? 5_000;
+
+  const agentId = await resolveAgentId(client, args.agent);
+
+  const createBody: Record<string, unknown> = { agent_id: agentId };
+  if (args.prompt !== undefined) createBody.prompt = args.prompt;
+  if (args.vaultId !== undefined) createBody.vault_id = args.vaultId;
+
+  const created = await client("POST", "/api/conversations", createBody);
+  if (created.status !== 201 && created.status !== 200) {
+    throw new Error(`fountainRun: conversation create failed (${created.status})`);
+  }
+  const conversationId = (created.json as { data?: { id?: string } })?.data?.id;
+  if (!conversationId) throw new Error("fountainRun: conversation create returned no id");
+
+  const deadline = Date.now() + timeoutMs;
+  let status = "pending";
+  while (Date.now() < deadline) {
+    const res = await client("GET", `/api/conversations/${conversationId}`);
+    if (res.status === 200) {
+      status = (res.json as { data?: { status?: string } })?.data?.status ?? status;
+      if (TERMINAL_STATUSES.has(status)) {
+        return { conversationId, status, terminatedByDeadline: false };
+      }
+    }
+    await sleep(pollMs);
+  }
+
+  // Deadline: end the conversation so the sandbox does not outlive the op.
+  await client("POST", `/api/conversations/${conversationId}/terminate`);
+  return { conversationId, status: "terminated", terminatedByDeadline: true };
+}

package/src/op/activities/index.ts

@@ -0,0 +1,28 @@
+/**
+ * fountain Op activities — resolved by the core activity registry when a
+ * project's `chant.config.ts` lists the `fountain` lexicon. Contributes
+ * the native applier (`fountainApply` — direct REST against fountain's
+ * API, no CLI, no state file) and the conversation runner (`fountainRun`).
+ */
+export {
+  fountainApply,
+  resolveEndpoint,
+  resolveToken,
+  parsePlan,
+  splitSecrets,
+  isChantOwned,
+  defaultFountainHttp,
+  DEFAULT_FOUNTAIN_BASE_URL,
+  OWNERSHIP_KEY,
+  OWNERSHIP_VALUE,
+} from "./fountain-apply";
+export type {
+  FountainApplyArgs,
+  FountainApplySummary,
+  FountainPlan,
+  PlanEntry,
+  FountainHttp,
+} from "./fountain-apply";
+
+export { fountainRun, resolveAgentId, TERMINAL_STATUSES } from "./fountain-run";
+export type { FountainRunArgs, FountainRunResult } from "./fountain-run";

package/src/package-cli.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env tsx
+/**
+ * Thin entry point for `npm run bundle` in lexicon-fountain.
+ * Generates src/generated/ files and writes dist/ bundle.
+ *
+ * NOTE: Uses top-level await (matching AWS/Azure pattern) to avoid
+ * event loop references from async wrappers keeping the process alive.
+ */
+import { packageLexicon } from "./codegen/package";
+import { writeBundleSpec } from "@intentius/chant/codegen/package";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+const pkgDir = dirname(fileURLToPath(import.meta.url));
+const distDir = join(pkgDir, "..", "dist");
+
+const verbose = process.argv.includes("--verbose") || !process.argv.includes("--quiet");
+const force = process.argv.includes("--force");
+
+const { spec, stats } = await packageLexicon({ verbose, force });
+writeBundleSpec(spec, distDir);
+
+console.error(
+  `Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills`,
+);
+console.error(`dist/ written to ${distDir}`);