@managoat/fountain-sdk 1.25.0

package/dist/client.d.ts

@@ -0,0 +1,190 @@
+import { HttpClient, type FetchLike, type RequestOptions } from "./http.ts";
+import { type ConfigOptions, type ResolvedConfig } from "./config.ts";
+import { Run, type RunOptions } from "./run.ts";
+import { Conversation } from "./conversation.ts";
+import { Agents, Connections, Environments, Vaults } from "./resources.ts";
+import { Team } from "./team.ts";
+import { type StreamRequest } from "./sse.ts";
+import type { AuthMe, Catalog, ConversationRecord, LogEvent, SandboxDiff, SandboxFile, SandboxListing, SandboxRecord, SearchHit } from "./types.ts";
+export interface FountainOptions extends ConfigOptions {
+    /** Swap the fetch implementation — a test server, a proxy, an instrumented one. */
+    fetch?: FetchLike;
+    /** Timeout for ordinary API calls, in ms. Streams are never timed out. */
+    timeoutMs?: number;
+}
+export interface RunConfig extends RunOptions {
+    /** The agent to run, by name or id. */
+    agent: string;
+    /**
+     * A vault of secrets, by name or id. Its values win over the environment's
+     * on a key collision, and they are attached when the sandbox spawns — the
+     * prompt never carries them.
+     */
+    vault?: string;
+    /** An environment to provision from instead of the agent's own, by name or id. */
+    environment?: string;
+    /** Display title for the conversation. */
+    title?: string;
+    /** Images to attach to the first prompt, as the API's `ImageInput` shape. */
+    images?: unknown[];
+    /**
+     * Bind the conversation to an external channel. A second run with the same
+     * channel, agent and vault continues that conversation instead of opening a
+     * new one — how a chat harness keeps one thread on one sandbox.
+     */
+    channelId?: string;
+    /** With `channelId`: open a new conversation anyway. */
+    fresh?: boolean;
+    /** Override the generated sandbox name. */
+    spriteName?: string;
+    /**
+     * Attach to a sandbox you already have, by id, instead of provisioning a
+     * new one. It must be ready or suspended and built for the same agent,
+     * environment and vault; several conversations then share one disk.
+     */
+    sandbox?: string;
+    /**
+     * `"ephemeral"` (a sandbox for this conversation alone) or `"persistent"`
+     * (the agent's own machine, shared by every conversation of that agent,
+     * environment and vault). Defaults to the agent's `sandbox_mode`.
+     */
+    sandboxMode?: "ephemeral" | "persistent";
+}
+/**
+ * A Fountain client.
+ *
+ * ```ts
+ * const fountain = new Fountain();
+ * const run = await fountain.run("Upgrade us to Phoenix 1.8 and open a PR", {
+ *   agent: "reposage",
+ *   vault: "github-bot",
+ * });
+ * console.log(run.text, run.url);
+ * ```
+ *
+ * Credentials resolve the way the `fountain` CLI resolves them, so a script
+ * inherits whatever already works in your terminal. See `resolveConfig`.
+ */
+export declare class Fountain {
+    /** The raw HTTP client. Every endpoint this SDK does not wrap is still here. */
+    readonly api: HttpClient;
+    readonly config: ResolvedConfig;
+    /** Define, read, change and delete agents. */
+    readonly agents: Agents;
+    /** Environments and their secrets. */
+    readonly environments: Environments;
+    /** Vaults and their secrets. */
+    readonly vaults: Vaults;
+    /** The team: teammates, their threads and their routines. */
+    readonly team: Team;
+    /** Provider accounts Fountain holds the credential for (Gmail via OAuth). */
+    readonly connections: Connections;
+    private readonly resolver;
+    constructor(options?: FountainOptions);
+    /**
+     * Run an agent on a prompt in a fresh sandbox.
+     *
+     * Returns immediately with a handle: `await` it for the finished answer,
+     * `for await` it for events as they land, or read `.textStream`. The work
+     * starts either way.
+     */
+    run(prompt: string, config: RunConfig): Run;
+    /**
+     * Pick a conversation back up. The sandbox is still there and so is the
+     * agent's session — `send` costs one prompt, not a re-explanation.
+     */
+    resume(conversationId: string): Conversation;
+    /**
+     * The account's conversations, newest first.
+     *
+     * Roots only by default: a conversation an agent spawned from inside a
+     * sandbox is listed under its parent's tree, not again at the top level.
+     * Pass `{ rootsOnly: false }` for the flat list, children included.
+     */
+    conversations(opts?: {
+        rootsOnly?: boolean;
+        sandboxId?: string;
+    }): Promise<ConversationRecord[]>;
+    /**
+     * Who this key belongs to. The cheapest way to check a key works.
+     *
+     * `request`, not `data`: this is one of the few endpoints that answers with
+     * the object itself rather than `{data: …}`, so unwrapping would hand back
+     * `null` for a call that succeeded. `test/server.ts` lists the others.
+     */
+    me(): Promise<AuthMe>;
+    /**
+     * The form vocabulary: the runtimes, models and providers this deployment
+     * offers. A client that builds an agent form reads it from here rather than
+     * hard-coding a list that goes stale on the next Fountain release.
+     */
+    catalog(): Promise<Catalog>;
+    /**
+     * The account's sandboxes — the machines conversations run on — newest
+     * first, each with the conversations on it. Pass one's id as
+     * `run({ sandbox })` to put another conversation on it.
+     */
+    sandboxes(opts?: {
+        status?: string[];
+    }): Promise<SandboxRecord[]>;
+    /** One sandbox, by id. */
+    sandbox(id: string): Promise<SandboxRecord>;
+    /**
+     * Reset a persistent sandbox: destroy the agent's home so the next launch
+     * on the same agent, environment and vault builds a clean machine. The
+     * conversations on it are kept. Refused (`sandbox_not_resettable`) for an
+     * ephemeral or already-gone sandbox, and (`sandbox_mid_turn`) while a
+     * conversation on it runs a turn.
+     */
+    resetSandbox(id: string): Promise<void>;
+    /**
+     * The entries of one directory on a sandbox, directories first then by
+     * name (ADR 0039). `path` is absolute or relative to the agent's working
+     * directory; omit it for that directory itself.
+     *
+     * The three disk reads — this, `sandboxFile` and `sandboxDiff` — are the
+     * whole of what the API offers on a disk; there is no exec, and to run a
+     * command you send a prompt. They need a `full`-scope key, answer only for
+     * a `ready` sandbox (a parked one is not woken: `sandbox_not_ready`), are
+     * confined to `/home/sprite` and the runtime's workspace
+     * (`path_outside_sandbox`), and come back redacted — the sandbox's
+     * environment and vault values read `[REDACTED]`, as in the transcript.
+     */
+    sandboxFiles(id: string, path?: string): Promise<SandboxListing>;
+    /**
+     * One file on a sandbox. `content` is the text when `encoding` is `utf-8`
+     * and base64 otherwise; `size` is the whole file and `truncated` says
+     * whether `content` stopped at `maxBytes` (default 256 KiB, at most 4 MiB).
+     */
+    sandboxFile(id: string, path: string, opts?: {
+        maxBytes?: number;
+    }): Promise<SandboxFile>;
+    /**
+     * `git diff` of the repository containing `path` on a sandbox (default:
+     * the agent's working directory). `staged` diffs the index; `ref` diffs
+     * against a commit, branch or tag instead of HEAD.
+     */
+    sandboxDiff(id: string, opts?: {
+        path?: string;
+        staged?: boolean;
+        ref?: string;
+        maxBytes?: number;
+    }): Promise<SandboxDiff>;
+    /** Full-text search across the caller's conversations. */
+    search(query: string, opts?: {
+        limit?: number;
+    }): Promise<SearchHit[]>;
+    /**
+     * Every conversation the caller owns, on one connection.
+     *
+     * `team.stream()` is the same idea narrowed to the team. Use this when the
+     * client cares about conversations that are not teammates' — a dashboard,
+     * or a process watching work it spawned itself.
+     */
+    events(options?: StreamRequest): AsyncIterable<LogEvent>;
+    /** Forget the memoized agent/vault/environment listings. */
+    refresh(): void;
+    /** Shorthand for `api.request`, for endpoints this SDK does not wrap. */
+    request<T = unknown>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    private nextTurnNumber;
+}

package/dist/client.js

@@ -0,0 +1,225 @@
+import { HttpClient } from "./http.js";
+import { resolveConfig } from "./config.js";
+import { Resolver } from "./resolve.js";
+import { Run } from "./run.js";
+import { Conversation } from "./conversation.js";
+import { Agents, Connections, Environments, Vaults } from "./resources.js";
+import { Team, normalizeStreams } from "./team.js";
+import { streamPath } from "./sse.js";
+/**
+ * A Fountain client.
+ *
+ * ```ts
+ * const fountain = new Fountain();
+ * const run = await fountain.run("Upgrade us to Phoenix 1.8 and open a PR", {
+ *   agent: "reposage",
+ *   vault: "github-bot",
+ * });
+ * console.log(run.text, run.url);
+ * ```
+ *
+ * Credentials resolve the way the `fountain` CLI resolves them, so a script
+ * inherits whatever already works in your terminal. See `resolveConfig`.
+ */
+export class Fountain {
+    /** The raw HTTP client. Every endpoint this SDK does not wrap is still here. */
+    api;
+    config;
+    /** Define, read, change and delete agents. */
+    agents;
+    /** Environments and their secrets. */
+    environments;
+    /** Vaults and their secrets. */
+    vaults;
+    /** The team: teammates, their threads and their routines. */
+    team;
+    /** Provider accounts Fountain holds the credential for (Gmail via OAuth). */
+    connections;
+    resolver;
+    constructor(options = {}) {
+        this.config = resolveConfig(options);
+        this.api = new HttpClient(this.config, {
+            fetch: options.fetch,
+            timeoutMs: options.timeoutMs,
+        });
+        this.resolver = new Resolver(this.api);
+        this.agents = new Agents(this.api, this.resolver);
+        this.environments = new Environments(this.api, this.resolver);
+        this.vaults = new Vaults(this.api, this.resolver);
+        this.team = new Team(this.api, this.resolver);
+        this.connections = new Connections(this.api);
+    }
+    /**
+     * Run an agent on a prompt in a fresh sandbox.
+     *
+     * Returns immediately with a handle: `await` it for the finished answer,
+     * `for await` it for events as they land, or read `.textStream`. The work
+     * starts either way.
+     */
+    run(prompt, config) {
+        const options = {
+            timeoutMs: config.timeoutMs,
+            signal: config.signal,
+            collectEvents: config.collectEvents,
+        };
+        return new Run(this.api, {
+            start: async () => {
+                const [agent, vaultId, environmentId] = await Promise.all([
+                    this.resolver.resolve("/api/agents", "agent", config.agent),
+                    this.resolver.resolveId("/api/vaults", "vault", config.vault),
+                    this.resolver.resolveId("/api/environments", "environment", config.environment),
+                ]);
+                const body = { agent_id: agent.id };
+                if (prompt)
+                    body.prompt = prompt;
+                if (vaultId)
+                    body.vault_id = vaultId;
+                if (environmentId)
+                    body.environment_id = environmentId;
+                if (config.title)
+                    body.title = config.title;
+                if (config.images?.length)
+                    body.images = config.images;
+                if (config.channelId)
+                    body.channel_id = config.channelId;
+                if (config.fresh)
+                    body.fresh = true;
+                if (config.spriteName)
+                    body.sprite_name = config.spriteName;
+                if (config.sandbox)
+                    body.sandbox_id = config.sandbox;
+                if (config.sandboxMode)
+                    body.sandbox_mode = config.sandboxMode;
+                const conversation = await this.api.data("POST", "/api/conversations", { body });
+                // `channel_id` may have resumed an existing conversation, in which
+                // case this prompt is not turn 1. Ask, rather than assume.
+                const turnNumber = config.channelId ? await this.nextTurnNumber(conversation.id) : 1;
+                return { conversation, turnNumber, after: 0 };
+            },
+        }, options);
+    }
+    /**
+     * Pick a conversation back up. The sandbox is still there and so is the
+     * agent's session — `send` costs one prompt, not a re-explanation.
+     */
+    resume(conversationId) {
+        return new Conversation(this.api, conversationId);
+    }
+    /**
+     * The account's conversations, newest first.
+     *
+     * Roots only by default: a conversation an agent spawned from inside a
+     * sandbox is listed under its parent's tree, not again at the top level.
+     * Pass `{ rootsOnly: false }` for the flat list, children included.
+     */
+    async conversations(opts = {}) {
+        return this.api.list("/api/conversations", {
+            query: { roots_only: opts.rootsOnly === false ? undefined : "true", sandbox_id: opts.sandboxId },
+        });
+    }
+    /**
+     * Who this key belongs to. The cheapest way to check a key works.
+     *
+     * `request`, not `data`: this is one of the few endpoints that answers with
+     * the object itself rather than `{data: …}`, so unwrapping would hand back
+     * `null` for a call that succeeded. `test/server.ts` lists the others.
+     */
+    async me() {
+        return this.api.request("GET", "/api/auth/me");
+    }
+    /**
+     * The form vocabulary: the runtimes, models and providers this deployment
+     * offers. A client that builds an agent form reads it from here rather than
+     * hard-coding a list that goes stale on the next Fountain release.
+     */
+    async catalog() {
+        return this.api.data("GET", "/api/catalog");
+    }
+    /**
+     * The account's sandboxes — the machines conversations run on — newest
+     * first, each with the conversations on it. Pass one's id as
+     * `run({ sandbox })` to put another conversation on it.
+     */
+    async sandboxes(opts = {}) {
+        return this.api.list("/api/sandboxes", {
+            query: { status: opts.status?.join(",") },
+        });
+    }
+    /** One sandbox, by id. */
+    async sandbox(id) {
+        return this.api.data("GET", `/api/sandboxes/${id}`);
+    }
+    /**
+     * Reset a persistent sandbox: destroy the agent's home so the next launch
+     * on the same agent, environment and vault builds a clean machine. The
+     * conversations on it are kept. Refused (`sandbox_not_resettable`) for an
+     * ephemeral or already-gone sandbox, and (`sandbox_mid_turn`) while a
+     * conversation on it runs a turn.
+     */
+    async resetSandbox(id) {
+        await this.api.request("DELETE", `/api/sandboxes/${id}`);
+    }
+    /**
+     * The entries of one directory on a sandbox, directories first then by
+     * name (ADR 0039). `path` is absolute or relative to the agent's working
+     * directory; omit it for that directory itself.
+     *
+     * The three disk reads — this, `sandboxFile` and `sandboxDiff` — are the
+     * whole of what the API offers on a disk; there is no exec, and to run a
+     * command you send a prompt. They need a `full`-scope key, answer only for
+     * a `ready` sandbox (a parked one is not woken: `sandbox_not_ready`), are
+     * confined to `/home/sprite` and the runtime's workspace
+     * (`path_outside_sandbox`), and come back redacted — the sandbox's
+     * environment and vault values read `[REDACTED]`, as in the transcript.
+     */
+    async sandboxFiles(id, path) {
+        return this.api.data("GET", `/api/sandboxes/${id}/files`, { query: { path } });
+    }
+    /**
+     * One file on a sandbox. `content` is the text when `encoding` is `utf-8`
+     * and base64 otherwise; `size` is the whole file and `truncated` says
+     * whether `content` stopped at `maxBytes` (default 256 KiB, at most 4 MiB).
+     */
+    async sandboxFile(id, path, opts = {}) {
+        return this.api.data("GET", `/api/sandboxes/${id}/file`, {
+            query: { path, max_bytes: opts.maxBytes },
+        });
+    }
+    /**
+     * `git diff` of the repository containing `path` on a sandbox (default:
+     * the agent's working directory). `staged` diffs the index; `ref` diffs
+     * against a commit, branch or tag instead of HEAD.
+     */
+    async sandboxDiff(id, opts = {}) {
+        return this.api.data("GET", `/api/sandboxes/${id}/diff`, {
+            query: { path: opts.path, staged: opts.staged, ref: opts.ref, max_bytes: opts.maxBytes },
+        });
+    }
+    /** Full-text search across the caller's conversations. */
+    async search(query, opts = {}) {
+        return this.api.list("/api/search", { query: { q: query, limit: opts.limit } });
+    }
+    /**
+     * Every conversation the caller owns, on one connection.
+     *
+     * `team.stream()` is the same idea narrowed to the team. Use this when the
+     * client cares about conversations that are not teammates' — a dashboard,
+     * or a process watching work it spawned itself.
+     */
+    events(options = {}) {
+        return streamPath(this.api, "/api/events/stream", { blocks: true, ...normalizeStreams(options) });
+    }
+    /** Forget the memoized agent/vault/environment listings. */
+    refresh() {
+        this.resolver.clear();
+    }
+    /** Shorthand for `api.request`, for endpoints this SDK does not wrap. */
+    request(method, path, options) {
+        return this.api.request(method, path, options);
+    }
+    async nextTurnNumber(conversationId) {
+        const turns = await this.api.list(`/api/conversations/${conversationId}/turns`);
+        return turns.reduce((max, t) => Math.max(max, Number(t.turn_number) || 0), 0) + 1;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,49 @@
+export declare const DEFAULT_BASE_URL = "https://managoat.com";
+/** Where a human reads a transcript. Fountain's own UI is a console (see CLAUDE.md). */
+export declare const DEFAULT_APP_URL = "https://fountain-conversations.demo.managoat.com/";
+export interface ResolvedConfig {
+    baseUrl: string;
+    apiKey: string;
+    appUrl: string;
+    /** Set when running inside a Fountain sandbox; stamps spawned conversations as children. */
+    parentConversationId: string | undefined;
+}
+export interface ConfigOptions {
+    /** Bearer token. Falls back to the environment, then `~/.fountain/credentials`. */
+    apiKey?: string;
+    /** Your Fountain deployment. Defaults to the hosted one. */
+    baseUrl?: string;
+    /** Credentials-file profile. Defaults to `$FOUNTAIN_PROFILE` or `default`. */
+    profile?: string;
+    /** Base of the conversations app, for `run.url`. `""` falls back to the API URL. */
+    appUrl?: string;
+}
+/**
+ * How to read `~/.fountain/credentials`, when there is a filesystem.
+ *
+ * The eleven apps built on Fountain so far are browser apps, and a bare
+ * `import "node:fs"` at the top of this module breaks their bundles. So the
+ * file reader is injected: `@managoat/fountain-sdk` resolves to a Node entry that
+ * installs one, and to this browser-safe module everywhere else. Nothing here
+ * touches a Node built-in.
+ */
+export type CredentialsReader = (profile: string) => Record<string, string>;
+/** Install a credentials-file reader. Called by the Node entry point. */
+export declare function setCredentialsReader(reader: CredentialsReader | null): void;
+/** Parse the INI-ish file `fountain auth login` writes. Exported for the Node entry. */
+export declare function parseCredentials(raw: string, profile: string): Record<string, string>;
+/**
+ * Resolve credentials the way the `fountain` CLI does, so a script inherits
+ * whatever already works in the terminal:
+ *
+ *   apiKey:  option → FOUNTAIN_API_KEY → FOUNTAIN_TOKEN → ~/.fountain/credentials
+ *   baseUrl: option → FOUNTAIN_BASE_URL → ~/.fountain/credentials → hosted
+ *
+ * `FOUNTAIN_TOKEN` is what a Fountain sandbox exports for the agent inside it,
+ * so an agent that reaches for this SDK delegates with the conversation-scoped
+ * token it already has — and the conversations it starts are recorded as its
+ * children.
+ */
+export declare function resolveConfig(options?: ConfigOptions): ResolvedConfig;
+/** The URL a human opens to watch this conversation. */
+export declare function conversationUrl(conversationId: string, config: ResolvedConfig): string;

package/dist/config.js

@@ -0,0 +1,87 @@
+export const DEFAULT_BASE_URL = "https://managoat.com";
+/** Where a human reads a transcript. Fountain's own UI is a console (see CLAUDE.md). */
+export const DEFAULT_APP_URL = "https://fountain-conversations.demo.managoat.com/";
+function unquote(value) {
+    const v = (value ?? "").trim();
+    if (v.length >= 2 && v[0] === v[v.length - 1] && (v[0] === '"' || v[0] === "'")) {
+        return v.slice(1, -1).trim();
+    }
+    return v;
+}
+let credentialsReader = null;
+/** Install a credentials-file reader. Called by the Node entry point. */
+export function setCredentialsReader(reader) {
+    credentialsReader = reader;
+}
+/** Parse the INI-ish file `fountain auth login` writes. Exported for the Node entry. */
+export function parseCredentials(raw, profile) {
+    const out = {};
+    let section = "";
+    for (const line of raw.split("\n")) {
+        const text = line.trim();
+        if (!text || text.startsWith("#") || text.startsWith(";"))
+            continue;
+        if (text.startsWith("[") && text.endsWith("]")) {
+            section = text.slice(1, -1).trim();
+            continue;
+        }
+        if (section !== profile)
+            continue;
+        const eq = text.indexOf("=");
+        if (eq === -1)
+            continue;
+        out[text.slice(0, eq).trim()] = unquote(text.slice(eq + 1));
+    }
+    return out;
+}
+/** Absent, unreadable, or no reader installed is not an error — it contributes nothing. */
+function readCredentials(profile) {
+    try {
+        return credentialsReader?.(profile) ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+const env = (name) => {
+    // `process` is absent in a browser and undefined-typed in a worker.
+    const vars = globalThis.process?.env;
+    return (vars?.[name] ?? "").trim();
+};
+/**
+ * Resolve credentials the way the `fountain` CLI does, so a script inherits
+ * whatever already works in the terminal:
+ *
+ *   apiKey:  option → FOUNTAIN_API_KEY → FOUNTAIN_TOKEN → ~/.fountain/credentials
+ *   baseUrl: option → FOUNTAIN_BASE_URL → ~/.fountain/credentials → hosted
+ *
+ * `FOUNTAIN_TOKEN` is what a Fountain sandbox exports for the agent inside it,
+ * so an agent that reaches for this SDK delegates with the conversation-scoped
+ * token it already has — and the conversations it starts are recorded as its
+ * children.
+ */
+export function resolveConfig(options = {}) {
+    const profile = (options.profile ?? "").trim() || env("FOUNTAIN_PROFILE") || "default";
+    let creds;
+    const credentials = () => (creds ??= readCredentials(profile));
+    let apiKey = (options.apiKey ?? "").trim() || env("FOUNTAIN_API_KEY") || env("FOUNTAIN_TOKEN");
+    if (!apiKey)
+        apiKey = credentials().api_key ?? "";
+    let baseUrl = (options.baseUrl ?? "").trim() || env("FOUNTAIN_BASE_URL");
+    if (!baseUrl)
+        baseUrl = credentials().base_url || DEFAULT_BASE_URL;
+    const appUrl = options.appUrl !== undefined ? options.appUrl.trim() : env("FOUNTAIN_APP_URL") || DEFAULT_APP_URL;
+    return {
+        baseUrl: baseUrl.replace(/\/+$/, ""),
+        apiKey,
+        appUrl: appUrl.replace(/\/+$/, ""),
+        parentConversationId: env("FOUNTAIN_CONVERSATION_ID") || undefined,
+    };
+}
+/** The URL a human opens to watch this conversation. */
+export function conversationUrl(conversationId, config) {
+    if (!config.appUrl)
+        return `${config.baseUrl}/api/conversations/${conversationId}`;
+    return `${config.appUrl}/#/c/${conversationId}`;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/conversation.d.ts

@@ -0,0 +1,100 @@
+import type { HttpClient } from "./http.ts";
+import type { ConversationRecord, LogEvent, Stream, Turn } from "./types.ts";
+import { Run, type RunOptions } from "./run.ts";
+import { type StreamOptions } from "./sse.ts";
+export interface SendOptions extends RunOptions {
+    /** Images to attach to the prompt, as the API's `ImageInput` shape. */
+    images?: unknown[];
+}
+/**
+ * A conversation you already have — the sandbox is still there, and so is
+ * everything the agent learned in it.
+ *
+ * This is the piece no stateless agent API has. `resume(id).send(...)` costs
+ * one prompt, not a re-explanation of the whole task, because the machine, the
+ * checkout and the session are exactly where the last turn left them.
+ */
+export declare class Conversation {
+    readonly id: string;
+    private readonly http;
+    /** Where the log feed has been read to, so a follow-up skips the history. */
+    private cursorValue;
+    constructor(http: HttpClient, id: string, cursor?: number);
+    /** Where a human watches this conversation. */
+    get url(): string;
+    /** The conversation record: status, agent, turn count. */
+    get(): Promise<ConversationRecord>;
+    status(): Promise<ConversationRecord["status"]>;
+    turns(): Promise<Turn[]>;
+    /** Send the next turn. Returns a `Run` — await it, or stream it. */
+    send(prompt: string, options?: SendOptions): Run;
+    /**
+     * Answer a permission request the agent is holding a tool call on.
+     *
+     * `optionId` has to be one of the ids the agent offered on the
+     * `permission_request` block — the server refuses anything else with a 422
+     * rather than forwarding it. Answer promptly: the request expires, and an
+     * expired one is denied.
+     *
+     * ```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 conversation.answer(event.request.requestId, allow.optionId);
+     *   }
+     * }
+     * ```
+     */
+    answer(requestId: string, optionId: string): Promise<void>;
+    /**
+     * Mark everything so far as read, clearing the teammate's unread badge.
+     *
+     * Every application built on Fountain calls this — it is what stops a UI
+     * shouting about messages the person is currently looking at.
+     */
+    markRead(): Promise<void>;
+    /**
+     * Everything the feed holds, oldest first, paged until drained.
+     *
+     * The other universal one: a UI opening a thread needs the transcript so
+     * far, and the JSON feed pages at 1000. `streams` narrows what comes back —
+     * `["acp"]` for a transcript, `["stage"]` for the lifecycle alone.
+     */
+    history(options?: {
+        streams?: Stream[] | string;
+        after?: number;
+        limit?: number;
+    }): Promise<LogEvent[]>;
+    /** The conversations this one spawned, as a tree. */
+    tree(): Promise<unknown>;
+    /** 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>;
+    /** Delete the conversation and its history. */
+    delete(): Promise<void>;
+    /**
+     * The raw log feed, reconnecting on its own. Everything, from `after`
+     * onwards, of every turn — `run`/`send` is the filtered view of this.
+     */
+    events(options?: StreamOptions): AsyncIterable<LogEvent>;
+    /** One page of the log feed as JSON, for a client that would rather poll. */
+    eventPage(after?: number, limit?: number): Promise<{
+        events: LogEvent[];
+        nextCursor: number;
+        hasMore: boolean;
+    }>;
+    /** The highest turn number so far; the next prompt is this plus one. */
+    lastTurnNumber(): Promise<number>;
+    /** Where this handle has read to, discovering it if nobody has looked yet. */
+    cursor(): Promise<number>;
+    /**
+     * Find the end of the log feed cheaply.
+     *
+     * A cold `resume().send()` has no cursor, and starting from 0 would replay
+     * every event of every earlier turn before reaching ours. Draining the
+     * `stage` stream (`wait=false`) is a few rows for even a long conversation,
+     * and its ids are the same global ids the full feed uses.
+     */
+    private discoverCursor;
+}