@managoat/fountain-sdk 1.25.0

package/dist/resources.js

@@ -0,0 +1,206 @@
+/**
+ * Payloads here use the API's own key names (`environment_id`, `mcp_servers`,
+ * `allowed_vault_ids`) rather than camelCase. That is a choice, not an
+ * oversight: an agent definition is the same object in the REST API, in a
+ * `fountain.yml` manifest and here, so one definition reads identically in all
+ * three and the API reference doubles as the SDK reference. Options that
+ * control the SDK's own behaviour — `timeoutMs`, `signal` — are camelCase,
+ * because those are not data.
+ */
+/**
+ * List, read, define, change and delete one kind of thing.
+ *
+ * `Patch` is its own parameter rather than `Partial<Input>`: the API's update
+ * schemas are not simply every create field made optional, and the generated
+ * ones say so exactly.
+ */
+class Collection {
+    http;
+    resolver;
+    path;
+    what;
+    constructor(http, resolver, path, what) {
+        this.http = http;
+        this.resolver = resolver;
+        this.path = path;
+        this.what = what;
+    }
+    /** Everything on the account. */
+    async list(search) {
+        return this.http.list(this.path, { query: { search } });
+    }
+    /** One of them, by name or id. */
+    async get(nameOrId) {
+        const { id } = await this.resolver.resolve(this.path, this.what, nameOrId);
+        return this.http.data("GET", `${this.path}/${id}`);
+    }
+    /** Define a new one. */
+    async create(input) {
+        const created = await this.http.data("POST", this.path, { body: input });
+        // A new name has to be findable by the next `run({ agent: "…" })`.
+        this.resolver.forget(this.path);
+        return created;
+    }
+    /** Change one. Only the fields you pass are touched. */
+    async update(nameOrId, patch) {
+        const { id } = await this.resolver.resolve(this.path, this.what, nameOrId);
+        const updated = await this.http.data("PATCH", `${this.path}/${id}`, { body: patch });
+        // The patch may have renamed it.
+        this.resolver.forget(this.path);
+        return updated;
+    }
+    /** Delete one. */
+    async delete(nameOrId) {
+        const { id } = await this.resolver.resolve(this.path, this.what, nameOrId);
+        await this.http.request("DELETE", `${this.path}/${id}`);
+        this.resolver.forget(this.path);
+    }
+}
+/**
+ * Secrets on an environment or a vault.
+ *
+ * Values are write-only: `list` returns keys, never what they are worth. That
+ * is the whole point — the SDK can put a credential into a sandbox and can
+ * never read it back out.
+ */
+class Secrets {
+    http;
+    resolver;
+    parentPath;
+    what;
+    constructor(http, resolver, parentPath, what) {
+        this.http = http;
+        this.resolver = resolver;
+        this.parentPath = parentPath;
+        this.what = what;
+    }
+    /** The keys stored here. Never the values. */
+    async list(parent) {
+        return this.http.list(`${await this.parentId(parent)}/secrets`);
+    }
+    /** Store a secret, or replace one with the same key. */
+    async set(parent, key, value) {
+        return this.http.data("POST", `${await this.parentId(parent)}/secrets`, {
+            body: { key, value },
+        });
+    }
+    /** Store several at once. */
+    async setAll(parent, secrets) {
+        const base = await this.parentId(parent);
+        const out = [];
+        // Serially: these are audited writes, and a partial failure should say
+        // which key it stopped on rather than leave a scattered half-write.
+        for (const [key, value] of Object.entries(secrets)) {
+            out.push(await this.http.data("POST", `${base}/secrets`, { body: { key, value } }));
+        }
+        return out;
+    }
+    /** Remove one, by key. */
+    async delete(parent, key) {
+        await this.http.request("DELETE", `${await this.parentId(parent)}/secrets/${encodeURIComponent(key)}`);
+    }
+    async parentId(nameOrId) {
+        const { id } = await this.resolver.resolve(this.parentPath, this.what, nameOrId);
+        return `${this.parentPath}/${id}`;
+    }
+}
+/** Vault metadata can change without reading or replacing its secret value. */
+class VaultSecrets extends Secrets {
+    async update(parent, key, patch) {
+        return this.http.data("PATCH", `${await this.parentId(parent)}/secrets/${encodeURIComponent(key)}`, { body: patch });
+    }
+}
+/** The agents on this account. */
+export class Agents extends Collection {
+    constructor(http, resolver) {
+        super(http, resolver, "/api/agents", "agent");
+    }
+}
+/** The environments on this account, and their secrets. */
+export class Environments extends Collection {
+    secrets;
+    constructor(http, resolver) {
+        super(http, resolver, "/api/environments", "environment");
+        this.secrets = new Secrets(http, resolver, this.path, this.what);
+    }
+}
+/**
+ * The provider accounts this tenant has signed in to, whose credentials
+ * Fountain holds (#1178). Connecting one is a browser round trip — send the
+ * account owner to `connect_url` from `providers()` — so there is no `create`
+ * here. An agent uses one by naming it in `mcp_servers`:
+ * `{ gmail: { connection: "<id>" } }`. Only for accounts the egress broker is
+ * on for; elsewhere every call is a `NotFoundError` (`connections_not_enabled`).
+ */
+export class Connections {
+    http;
+    /** Where connections get their tokens: Google, plus the tenant's own providers (#1186). */
+    providers;
+    constructor(http) {
+        this.http = http;
+        this.providers = new ConnectionProviders(http);
+    }
+    /** Every connection on the account, active or revoked. Never a token. */
+    async list() {
+        return this.http.list("/api/connections");
+    }
+    /** One connection by id. Unenveloped, as the server answers `show`. */
+    async get(id) {
+        return this.http.request("GET", `/api/connections/${encodeURIComponent(id)}`);
+    }
+    /** Revoke at the provider and delete. Agents that name it get `connection revoked`. */
+    async delete(id) {
+        await this.http.request("DELETE", `/api/connections/${encodeURIComponent(id)}`);
+    }
+}
+/**
+ * Connection providers (#1186): the platform provider (Google, id `google`),
+ * the tenant's own OAuth apps (`kind: "oauth2"`) and the remote MCP servers
+ * whose authorization Fountain discovered (`kind: "mcp"`). The client secret
+ * is write-only. Only for accounts the egress broker is on for.
+ */
+export class ConnectionProviders {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** Google first, then the tenant's own. */
+    async list() {
+        return this.http.list("/api/connection-providers");
+    }
+    /** One provider; `"google"` is the platform provider. */
+    async get(id) {
+        return this.http.request("GET", `/api/connection-providers/${encodeURIComponent(id)}`);
+    }
+    /**
+     * Define a provider. `kind: "oauth2"` takes the tenant's app registration;
+     * `kind: "mcp"` takes `mcp_url` and Fountain discovers the authorization
+     * server and registers a client where it can.
+     */
+    async create(input) {
+        return this.http.request("POST", "/api/connection-providers", { body: input });
+    }
+    /** Edit a tenant provider. A blank `client_secret` keeps the stored one. */
+    async update(id, patch) {
+        return this.http.request("PATCH", `/api/connection-providers/${encodeURIComponent(id)}`, {
+            body: patch,
+        });
+    }
+    /** Delete a tenant provider and every connection on it. */
+    async delete(id) {
+        await this.http.request("DELETE", `/api/connection-providers/${encodeURIComponent(id)}`);
+    }
+    /** Run MCP discovery again on an `mcp` provider. */
+    async discover(id) {
+        return this.http.request("POST", `/api/connection-providers/${encodeURIComponent(id)}/discover`);
+    }
+}
+/** The vaults on this account, and their secrets. */
+export class Vaults extends Collection {
+    secrets;
+    constructor(http, resolver) {
+        super(http, resolver, "/api/vaults", "vault");
+        this.secrets = new VaultSecrets(http, resolver, this.path, this.what);
+    }
+}
+//# sourceMappingURL=resources.js.map

package/dist/resources.js.map

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

package/dist/run.d.ts

@@ -0,0 +1,81 @@
+import type { HttpClient } from "./http.ts";
+import type { ConversationRecord as Conversation, RunEvent, RunResult } from "./types.ts";
+export interface RunPlan {
+    /** Open the conversation (a fresh `run`), or reuse one (`send`). */
+    start(): Promise<{
+        conversation: Conversation;
+        turnNumber: number;
+        after: number;
+    }>;
+}
+export interface RunOptions {
+    /** Stop waiting after this many ms and throw `TimeoutError`. `0` (default) waits. */
+    timeoutMs?: number;
+    /** Abort the run's own waiting. The turn keeps going in the sandbox. */
+    signal?: AbortSignal;
+    /** Keep every log event on the result. Off by default — a long turn is a lot of rows. */
+    collectEvents?: boolean;
+}
+/**
+ * A turn in flight.
+ *
+ * The work starts as soon as you call `run()`; what you do with this object
+ * decides how much of it you see. `await` it for the answer, iterate it for
+ * events as they land, or read `.textStream` for just the words. All three
+ * read the same underlying run — there is no second request behind them.
+ */
+export declare class Run implements Promise<RunResult>, AsyncIterable<RunEvent> {
+    readonly [Symbol.toStringTag]: string;
+    /** The conversation this turn runs in. Resolves as soon as it exists. */
+    readonly conversationId: Promise<string>;
+    /** Where a human watches it. Resolves with `conversationId`. */
+    readonly url: Promise<string>;
+    /** The full conversation record, once opened. */
+    readonly conversation: Promise<Conversation>;
+    private readonly http;
+    private readonly events;
+    private readonly completion;
+    private readonly opened;
+    private readonly abort;
+    private lastEventId;
+    private conversationIdValue;
+    constructor(http: HttpClient, plan: RunPlan, options?: RunOptions);
+    then<A = RunResult, B = never>(onfulfilled?: ((value: RunResult) => A | PromiseLike<A>) | null, onrejected?: ((reason: unknown) => B | PromiseLike<B>) | null): Promise<A | B>;
+    catch<B = never>(onrejected?: ((reason: unknown) => B | PromiseLike<B>) | null): Promise<RunResult | B>;
+    finally(onfinally?: (() => void) | null): Promise<RunResult>;
+    [Symbol.asyncIterator](): AsyncIterator<RunEvent>;
+    /** Just the words, as they arrive. */
+    get textStream(): AsyncIterable<string>;
+    /** Stop waiting. The turn keeps running in the sandbox; `interrupt()` stops that. */
+    cancel(): void;
+    /**
+     * Answer a permission request this turn is blocked on — the `requestId` and
+     * the `optionId` both come off a `{ type: "permission" }` event.
+     *
+     * ```ts
+     * for await (const event of run) {
+     *   if (event.type === "permission") {
+     *     const allow = event.request.options.find((o) => o.kind === "allow_once");
+     *     if (allow) await run.answer(event.request.requestId, allow.optionId);
+     *   }
+     * }
+     * ```
+     *
+     * Only an agent with an `ask` entry in its `permission_policy` produces
+     * these. Leave them unanswered and the server denies each one when it
+     * expires, so the turn finishes having skipped the work.
+     */
+    answer(requestId: string, optionId: string): Promise<void>;
+    /** Ask the agent to stop the turn it is on. The sandbox stays up. */
+    interrupt(): Promise<void>;
+    /** Tear the sandbox down. Nothing resumes after this. */
+    terminate(): Promise<void>;
+    /** The cursor to resume the log feed from — how a follow-up turn skips history. */
+    get cursor(): number;
+    private execute;
+    private follow;
+    /** The status as of the end of the wait, not as of the last event. */
+    private currentStatus;
+    /** The id, once known — for internal callers that already awaited the open. */
+    get id(): string | null;
+}

package/dist/run.js

@@ -0,0 +1,247 @@
+import { TurnFollower } from "./turn.js";
+import { streamEvents } from "./sse.js";
+import { Broadcast, deferred } from "./queue.js";
+import { conversationUrl } from "./config.js";
+import { TimeoutError } from "./errors.js";
+const TERMINAL_CONVERSATION_STATUSES = new Set(["failed", "terminated"]);
+/**
+ * A turn in flight.
+ *
+ * The work starts as soon as you call `run()`; what you do with this object
+ * decides how much of it you see. `await` it for the answer, iterate it for
+ * events as they land, or read `.textStream` for just the words. All three
+ * read the same underlying run — there is no second request behind them.
+ */
+export class Run {
+    [Symbol.toStringTag] = "Run";
+    /** The conversation this turn runs in. Resolves as soon as it exists. */
+    conversationId;
+    /** Where a human watches it. Resolves with `conversationId`. */
+    url;
+    /** The full conversation record, once opened. */
+    conversation;
+    http;
+    events = new Broadcast();
+    completion;
+    opened = deferred();
+    abort = new AbortController();
+    lastEventId = 0;
+    conversationIdValue = null;
+    constructor(http, plan, options = {}) {
+        this.http = http;
+        this.conversation = this.opened.promise;
+        this.conversationId = hushed(this.conversation.then((c) => c.id));
+        this.url = hushed(this.conversation.then((c) => conversationUrl(c.id, http.config)));
+        this.completion = this.execute(plan, options);
+        // A caller may only ever iterate, or only ever read `conversationId`. None
+        // of these derived promises may crash the process for want of a handler —
+        // the failure still arrives on whichever one is actually awaited.
+        hushed(this.completion);
+    }
+    then(onfulfilled, onrejected) {
+        return this.completion.then(onfulfilled, onrejected);
+    }
+    catch(onrejected) {
+        return this.completion.catch(onrejected);
+    }
+    finally(onfinally) {
+        return this.completion.finally(onfinally);
+    }
+    [Symbol.asyncIterator]() {
+        return this.events[Symbol.asyncIterator]();
+    }
+    /** Just the words, as they arrive. */
+    get textStream() {
+        const events = this.events;
+        return {
+            async *[Symbol.asyncIterator]() {
+                for await (const event of events) {
+                    if (event.type === "text")
+                        yield event.text;
+                }
+            },
+        };
+    }
+    /** Stop waiting. The turn keeps running in the sandbox; `interrupt()` stops that. */
+    cancel() {
+        this.abort.abort();
+    }
+    /**
+     * Answer a permission request this turn is blocked on — the `requestId` and
+     * the `optionId` both come off a `{ type: "permission" }` event.
+     *
+     * ```ts
+     * for await (const event of run) {
+     *   if (event.type === "permission") {
+     *     const allow = event.request.options.find((o) => o.kind === "allow_once");
+     *     if (allow) await run.answer(event.request.requestId, allow.optionId);
+     *   }
+     * }
+     * ```
+     *
+     * Only an agent with an `ask` entry in its `permission_policy` produces
+     * these. Leave them unanswered and the server denies each one when it
+     * expires, so the turn finishes having skipped the work.
+     */
+    async answer(requestId, optionId) {
+        const id = await this.conversationId;
+        await this.http.request("POST", `/api/conversations/${id}/requests/${encodeURIComponent(requestId)}`, { body: { option_id: optionId } });
+    }
+    /** Ask the agent to stop the turn it is on. The sandbox stays up. */
+    async interrupt() {
+        const id = await this.conversationId;
+        await this.http.request("POST", `/api/conversations/${id}/interrupt`);
+    }
+    /** Tear the sandbox down. Nothing resumes after this. */
+    async terminate() {
+        const id = await this.conversationId;
+        await this.http.request("POST", `/api/conversations/${id}/terminate`);
+    }
+    /** The cursor to resume the log feed from — how a follow-up turn skips history. */
+    get cursor() {
+        return this.lastEventId;
+    }
+    async execute(plan, options) {
+        try {
+            const { conversation, turnNumber, after } = await plan.start();
+            this.conversationIdValue = conversation.id;
+            this.lastEventId = after;
+            this.opened.resolve(conversation);
+            const url = conversationUrl(conversation.id, this.http.config);
+            this.events.push({ type: "conversation", conversationId: conversation.id, conversation, url });
+            const result = await this.follow(conversation, turnNumber, after, options, url);
+            this.events.close();
+            return result;
+        }
+        catch (error) {
+            this.opened.reject(error);
+            this.events.close(error);
+            throw error;
+        }
+    }
+    async follow(conversation, turnNumber, after, options, url) {
+        const follower = new TurnFollower(turnNumber);
+        const collected = [];
+        const signal = options.signal
+            ? AbortSignal.any([options.signal, this.abort.signal])
+            : this.abort.signal;
+        let failure = null;
+        let timedOut = false;
+        const timeoutMs = options.timeoutMs ?? 0;
+        const timer = timeoutMs > 0
+            ? setTimeout(() => {
+                timedOut = true;
+                this.abort.abort();
+            }, timeoutMs)
+            : null;
+        timer?.unref?.();
+        try {
+            for await (const event of streamEvents(this.http, conversation.id, { after, signal })) {
+                if (typeof event.id === "number" && event.id > this.lastEventId)
+                    this.lastEventId = event.id;
+                if (options.collectEvents)
+                    collected.push(event);
+                this.events.push({ type: "event", event });
+                for (const out of follower.apply(event))
+                    this.events.push(out);
+                if (follower.finished)
+                    break;
+                // A stage that can mean the conversation is over. Which stages those
+                // are is not a list worth hard-coding — `provision/failed` stops the
+                // server, `setup/failed` may not, and `sandbox/done` is a suspend
+                // (resumable) or a reclaim (not) depending on a field. So ask the
+                // conversation instead of guessing: if it is terminal, no turn event
+                // is ever coming and waiting for one hangs forever.
+                if (mayEndConversation(event)) {
+                    const status = await this.currentStatus(conversation);
+                    if (status && TERMINAL_CONVERSATION_STATUSES.has(status)) {
+                        failure = { reason: stageReason(event) };
+                        break;
+                    }
+                }
+            }
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+        if (timedOut) {
+            throw new TimeoutError(`Timed out after ${timeoutMs}ms waiting for turn ${turnNumber}. ` +
+                `The turn is still running — resume conversation ${conversation.id}.`, conversation.id, follower.text);
+        }
+        const status = await this.currentStatus(conversation);
+        if (!follower.finished) {
+            // The conversation died under the turn, or the caller stopped waiting.
+            // Either way say so, rather than reporting an empty answer as normal.
+            const state = failure ? "failed" : "timeout";
+            this.events.push({ type: "turn-end", state, exitCode: null, reason: failure?.reason ?? null });
+        }
+        const result = {
+            conversationId: conversation.id,
+            url,
+            turnNumber,
+            text: follower.text,
+            toolsUsed: follower.toolsUsed,
+            state: follower.state ?? (failure ? "failed" : "timeout"),
+            exitCode: follower.exitCode,
+            reason: follower.reason ?? failure?.reason ?? null,
+            status,
+        };
+        if (options.collectEvents)
+            result.events = collected;
+        return result;
+    }
+    /** The status as of the end of the wait, not as of the last event. */
+    async currentStatus(conversation) {
+        try {
+            const fresh = await this.http.data("GET", `/api/conversations/${conversation.id}`);
+            return fresh?.status ?? conversation.status ?? null;
+        }
+        catch {
+            return conversation.status ?? null;
+        }
+    }
+    /** The id, once known — for internal callers that already awaited the open. */
+    get id() {
+        return this.conversationIdValue;
+    }
+}
+/**
+ * Stage events worth checking the conversation's status over.
+ *
+ * `state` is a closed vocabulary — started/done/failed/interrupted — so a
+ * destroyed sandbox and a parked one are both `sandbox`/`done`, told apart by
+ * a field in the payload. Rather than encode that, treat every one of these as
+ * "go and ask" and let the conversation's own status decide.
+ */
+function mayEndConversation(event) {
+    if (event.kind !== "stage")
+        return false;
+    if (event.stage === "turn")
+        return false; // the follower owns the turn's own fate
+    return event.state === "failed" || event.stage === "terminate" || event.stage === "sandbox";
+}
+/** Why a stage said it ended, when it said. */
+function stageReason(event) {
+    let meta = event.data;
+    if (typeof meta === "string") {
+        try {
+            meta = JSON.parse(meta);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!meta || typeof meta !== "object")
+        return null;
+    const record = meta;
+    const reason = record.message ?? record.reason;
+    const label = typeof reason === "string" && reason ? reason : null;
+    return label ? `${event.stage}/${event.state}: ${label}` : `${event.stage}/${event.state}`;
+}
+/** Mark a promise as handled without changing what it settles to. */
+function hushed(promise) {
+    promise.catch(() => { });
+    return promise;
+}
+//# sourceMappingURL=run.js.map

package/dist/run.js.map

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

package/dist/schemas.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The API's own types, straight from its OpenAPI document.
+ *
+ * `src/generated/openapi.ts` is produced by `npm run generate` from the same
+ * spec the server serves at `GET /api/openapi.json`, and CI regenerates it and
+ * fails on a diff. So these are not a description of the API that someone has
+ * to remember to update — they are the API, and a field added to a schema in
+ * Elixir shows up here on the next build.
+ *
+ * The hand-written layer above this one exists for the things a spec cannot
+ * express: what a *turn* is (many log events folded into one answer), that a
+ * run can be awaited or streamed, and which of 85 paths are worth a verb.
+ */
+import type { components } from "./generated/openapi.ts";
+type S = components["schemas"];
+/** `T` with `K` made optional — for fields the API defaults and the generator does not. */
+type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+/** A named, re-runnable agent config — runtime, model, skills, environment. */
+export type Agent = S["Agent"];
+/** Everything that decides how a run behaves, before the prompt. */
+export type AgentInput = S["AgentRequest"];
+/** A partial agent definition, for `update`. */
+export type AgentPatch = S["AgentUpdate"];
+/** The sandbox shape an agent runs in: packages, repos, env vars, networking. */
+export type Environment = S["Environment"];
+export type EnvironmentInput = S["EnvironmentRequest"];
+export type EnvironmentPatch = S["EnvironmentUpdate"];
+/** A free-floating bag of env-var overrides, chosen per conversation. */
+export type Vault = S["Vault"];
+export type VaultInput = S["VaultRequest"];
+export type VaultPatch = S["VaultUpdate"];
+/** One run of an agent inside a sandbox. */
+export type ConversationRecord = S["Conversation"];
+/** A machine, with the conversations on it. */
+export type SandboxRecord = S["SandboxDetail"];
+/** One directory on a sandbox, directories first (ADR 0039). */
+export type SandboxListing = S["SandboxListing"];
+/** One entry of a `SandboxListing`. */
+export type SandboxEntry = S["SandboxEntry"];
+/** One file on a sandbox, redacted; `content` is text or base64 per `encoding`. */
+export type SandboxFile = S["SandboxFile"];
+/** `git diff` of a repository on a sandbox, redacted. */
+export type SandboxDiff = S["SandboxDiff"];
+/** One prompt and everything the agent did in response. */
+export type Turn = S["Turn"];
+/** One row of a conversation's log feed. */
+export type LogEvent = S["LogEvent"];
+/** A server-parsed piece of an agent's output (`?blocks=true`). */
+export type Block = S["Block"];
+/** A stored secret. Values are write-only — the API never returns them. */
+export type Secret = S["Secret"];
+export type VaultSecret = S["VaultSecret"];
+export type VaultSecretMetadataPatch = S["VaultSecretMetadataRequest"];
+/** An agent that has been put on the team, with its standing conversation. */
+export type Teammate = S["Teammate"];
+export type TeamAddInput = S["TeamAddRequest"];
+/** A cron that runs a teammate with a prompt. */
+export type Schedule = S["TeamSchedule"];
+/**
+ * Creating one. `enabled` and `one_off` are optional on the wire — the server
+ * defaults them to `true` and `false` — but the generator marks a property
+ * that carries a default as required, so they are relaxed back here.
+ */
+export type ScheduleInput = Optional<S["TeamScheduleCreateRequest"], "enabled" | "one_off">;
+export type SchedulePatch = S["TeamScheduleUpdateRequest"];
+export type TeamCommsStatus = S["TeamCommsStatus"];
+export type TeammateContact = S["TeammateContact"];
+/** The form vocabulary: runtimes, models, providers a client can offer. */
+export type Catalog = S["CatalogResponse"]["data"];
+/** One hit from full-text search across the caller's conversations. */
+export type SearchHit = S["SearchHit"];
+/** A node in a conversation's spawn tree. */
+export type ConversationTreeNode = S["ConversationTreeNode"];
+export type Runner = S["Runner"];
+/** A provider account the tenant signed in to once; Fountain holds the credential (#1178). */
+export type Connection = S["Connection"];
+/**
+ * Where a connection's tokens come from (#1186): the platform provider
+ * (Google, id `google`), the tenant's own OAuth app at a service (`oauth2`),
+ * or a remote MCP server whose authorization Fountain discovered (`mcp`).
+ */
+export type ConnectionProvider = S["ConnectionProvider"];
+/** Defining one. `kind: "mcp"` needs only `mcp_url`; the rest comes from discovery. */
+export type ConnectionProviderInput = S["ConnectionProviderRequest"];
+export type ConnectionProviderPatch = Partial<ConnectionProviderInput>;
+export type Repository = S["Repository"];
+export type ImageInput = S["ImageInput"];
+export type AuthMe = S["AuthMeResponse"];
+/** Every path and operation, for callers reaching past the wrapped verbs. */
+export type { paths, components, operations } from "./generated/openapi.ts";

package/dist/schemas.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=schemas.js.map

package/dist/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":""}