@managoat/fountain-sdk 1.25.0

package/dist/conversation.js

@@ -0,0 +1,189 @@
+import { Run } from "./run.js";
+import { streamEvents } from "./sse.js";
+import { conversationUrl } from "./config.js";
+/**
+ * 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 class Conversation {
+    id;
+    http;
+    /** Where the log feed has been read to, so a follow-up skips the history. */
+    cursorValue;
+    constructor(http, id, cursor = 0) {
+        this.http = http;
+        this.id = id;
+        this.cursorValue = cursor;
+    }
+    /** Where a human watches this conversation. */
+    get url() {
+        return conversationUrl(this.id, this.http.config);
+    }
+    /** The conversation record: status, agent, turn count. */
+    async get() {
+        return this.http.data("GET", `/api/conversations/${this.id}`);
+    }
+    async status() {
+        return (await this.get()).status;
+    }
+    async turns() {
+        return this.http.list(`/api/conversations/${this.id}/turns`);
+    }
+    /** Send the next turn. Returns a `Run` — await it, or stream it. */
+    send(prompt, options = {}) {
+        const body = { prompt };
+        if (options.images?.length)
+            body.images = options.images;
+        const run = new Run(this.http, {
+            start: async () => {
+                // The cursor and the turn number both have to be taken *before* the
+                // prompt goes in, or we race the events it produces.
+                const after = await this.cursor();
+                const turnNumber = (await this.lastTurnNumber()) + 1;
+                await this.http.request("POST", `/api/conversations/${this.id}/prompts`, { body });
+                const conversation = await this.get();
+                return { conversation, turnNumber, after };
+            },
+        }, options);
+        // Keep the conversation's cursor moving as the run consumes the feed, so
+        // the next send starts where this one stopped.
+        void run
+            .finally(() => {
+            if (run.cursor > this.cursorValue)
+                this.cursorValue = run.cursor;
+        })
+            .catch(() => { });
+        return 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);
+     *   }
+     * }
+     * ```
+     */
+    async answer(requestId, optionId) {
+        await this.http.request("POST", `/api/conversations/${this.id}/requests/${encodeURIComponent(requestId)}`, { body: { option_id: optionId } });
+    }
+    /**
+     * 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.
+     */
+    async markRead() {
+        await this.http.request("POST", `/api/conversations/${this.id}/read`);
+    }
+    /**
+     * 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.
+     */
+    async history(options = {}) {
+        const streams = Array.isArray(options.streams) ? options.streams.join(",") : options.streams;
+        const limit = options.limit ?? 1000;
+        const out = [];
+        let after = options.after ?? 0;
+        for (;;) {
+            const page = await this.http.request("GET", `/api/conversations/${this.id}/events`, {
+                query: { after, limit, blocks: "true", streams },
+            });
+            const events = page?.data ?? [];
+            out.push(...events);
+            const meta = page?.meta ?? {};
+            if (!meta.has_more || meta.next_cursor === null || meta.next_cursor === undefined)
+                break;
+            after = meta.next_cursor;
+        }
+        const last = out.at(-1)?.id;
+        if (typeof last === "number" && last > this.cursorValue)
+            this.cursorValue = last;
+        return out;
+    }
+    /** The conversations this one spawned, as a tree. */
+    async tree() {
+        return this.http.data("GET", `/api/conversations/${this.id}/tree`);
+    }
+    /** Ask the agent to stop the turn it is on. The sandbox stays up. */
+    async interrupt() {
+        await this.http.request("POST", `/api/conversations/${this.id}/interrupt`);
+    }
+    /** Tear the sandbox down. Nothing resumes after this. */
+    async terminate() {
+        await this.http.request("POST", `/api/conversations/${this.id}/terminate`);
+    }
+    /** Delete the conversation and its history. */
+    async delete() {
+        await this.http.request("DELETE", `/api/conversations/${this.id}`);
+    }
+    /**
+     * 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 = {}) {
+        return streamEvents(this.http, this.id, options);
+    }
+    /** One page of the log feed as JSON, for a client that would rather poll. */
+    async eventPage(after = 0, limit = 1000) {
+        const out = await this.http.request("GET", `/api/conversations/${this.id}/events`, { query: { after, limit, blocks: "true" } });
+        const meta = out?.meta ?? {};
+        return {
+            events: out?.data ?? [],
+            nextCursor: typeof meta.next_cursor === "number" ? meta.next_cursor : after,
+            hasMore: Boolean(meta.has_more),
+        };
+    }
+    /** The highest turn number so far; the next prompt is this plus one. */
+    async lastTurnNumber() {
+        const turns = await this.turns();
+        return turns.reduce((max, turn) => Math.max(max, Number(turn.turn_number) || 0), 0);
+    }
+    /** Where this handle has read to, discovering it if nobody has looked yet. */
+    async cursor() {
+        return this.cursorValue > 0 ? this.cursorValue : this.discoverCursor();
+    }
+    /**
+     * 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.
+     */
+    async discoverCursor() {
+        let last = 0;
+        try {
+            for await (const event of streamEvents(this.http, this.id, {
+                streams: "stage",
+                wait: false,
+                maxRetries: 0,
+            })) {
+                if (typeof event.id === "number" && event.id > last)
+                    last = event.id;
+            }
+        }
+        catch {
+            // Not worth failing a send over; 0 replays, which is correct if noisy.
+            return 0;
+        }
+        this.cursorValue = last;
+        return last;
+    }
+}
+//# sourceMappingURL=conversation.js.map

package/dist/conversation.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Failures, keyed the way callers actually branch on them.
+ *
+ * The apps built on Fountain switch on the server's `error` string, not on the
+ * status: `conversation_busy` is a 400, `sandbox_quota_exceeded` is a 429 and
+ * `provisioning` is a 503, and what a UI wants to say about each has nothing
+ * to do with those numbers. So `code` is the primary axis here, status the
+ * secondary one, and the conditions worth retrying say so themselves.
+ */
+/** The `error` strings the API sends. Open — a new one is a string, not a break. */
+export type FountainErrorCode = "conversation_busy" | "provisioning" | "sprite_probe_failed" | "sandbox_quota_exceeded" | "sandbox_at_capacity" | "sandbox_not_found" | "sandbox_not_attachable" | "sandbox_identity_mismatch" | "sandbox_runtime_mismatch" | "insufficient_credits" | "fleet_full" | "subscription_required" | "rate_limited" | "account_suspended" | "environment_not_allowed" | "environment_not_found" | "vault_not_allowed" | "parent_conversation_not_found" | "not_found" | "unauthorized" | (string & {});
+export interface FountainErrorInit {
+    status?: number;
+    code?: FountainErrorCode;
+    body?: unknown;
+    /** Seconds the server asked us to wait, from `Retry-After`. */
+    retryAfter?: number | null;
+    cause?: unknown;
+}
+export declare class FountainError extends Error {
+    /** HTTP status, or 0 for a transport-level failure. */
+    readonly status: number;
+    /** The API's `error` field when it sent one. */
+    readonly code: FountainErrorCode | undefined;
+    /** The parsed response body, whatever shape it had. */
+    readonly body: unknown;
+    /** Seconds to wait before retrying, when the server said. */
+    readonly retryAfter: number | null;
+    constructor(message: string, init?: FountainErrorInit);
+    /**
+     * Whether trying the same call again could work. True for a busy
+     * conversation, a sandbox still coming up, a rate limit and 5xx — false for
+     * anything the caller has to change first.
+     */
+    get retryable(): boolean;
+    /** `errors: {field: [msg, …]}` as the server sends a 422; empty otherwise. */
+    get fieldErrors(): Record<string, string[]>;
+}
+/** No API key, or the key was rejected (401). */
+export declare class AuthError extends FountainError {
+}
+/**
+ * The account is out of credit (`insufficient_credits`, 402). `upgradeUrl` is
+ * the billing page, where credit is bought. The class keeps its old name so
+ * callers written against the subscription era still catch it.
+ */
+export declare class SubscriptionRequiredError extends FountainError {
+    get upgradeUrl(): string | undefined;
+}
+/** Wrong id, or it belongs to another account — Fountain does not distinguish (404). */
+export declare class NotFoundError extends FountainError {
+}
+/** The request was well-formed but rejected (422). Read `fieldErrors`. */
+export declare class ValidationError extends FountainError {
+}
+/** Too many requests (429). */
+export declare class RateLimitError extends FountainError {
+}
+/**
+ * The agent is still working on the previous prompt (`conversation_busy`, a
+ * 400). Wait for the turn in flight, then send again — `Conversation#send`
+ * with `waitForIdle` does that for you.
+ */
+export declare class ConversationBusyError extends FountainError {
+}
+/**
+ * The sandbox is not up yet, Fountain could not reach the provider to check
+ * (`provisioning` / `sprite_probe_failed`), or the deployment is at its fleet
+ * ceiling (`fleet_full`) — all 503 with a `Retry-After`. Nothing is wrong and
+ * nothing was changed; the same call will work shortly.
+ */
+export declare class NotReadyError extends FountainError {
+}
+/**
+ * The account is at its concurrent-sandbox cap (`sandbox_quota_exceeded`, 429).
+ * Deliberately not a billing error: terminate a conversation and continue.
+ */
+export declare class QuotaExceededError extends FountainError {
+    /** Sandboxes in use right now. */
+    get activeSandboxes(): number | undefined;
+    /** The cap. */
+    get limit(): number | undefined;
+}
+/** `run`/`send` gave up waiting. The turn is still running — resume it. */
+export declare class TimeoutError extends FountainError {
+    readonly conversationId: string;
+    /** Whatever the agent had said by the deadline. */
+    readonly partialText: string;
+    constructor(message: string, conversationId: string, partialText: string);
+}
+/** A name that matched no agent/vault/environment, or matched more than one. */
+export declare class ResolutionError extends FountainError {
+}
+/**
+ * The request never reached Fountain. In a browser this is nearly always CORS
+ * or a wrong base URL, and the message says so, because "Failed to fetch" has
+ * sent more than one person hunting through their own code.
+ */
+export declare class ConnectionError extends FountainError {
+}
+/** Pick the class for a failure. `code` decides; status is the fallback. */
+export declare function errorForStatus(status: number, body: unknown, method: string, url: string, headers?: Headers): FountainError;

package/dist/errors.js

@@ -0,0 +1,197 @@
+/**
+ * Failures, keyed the way callers actually branch on them.
+ *
+ * The apps built on Fountain switch on the server's `error` string, not on the
+ * status: `conversation_busy` is a 400, `sandbox_quota_exceeded` is a 429 and
+ * `provisioning` is a 503, and what a UI wants to say about each has nothing
+ * to do with those numbers. So `code` is the primary axis here, status the
+ * secondary one, and the conditions worth retrying say so themselves.
+ */
+export class FountainError extends Error {
+    /** HTTP status, or 0 for a transport-level failure. */
+    status;
+    /** The API's `error` field when it sent one. */
+    code;
+    /** The parsed response body, whatever shape it had. */
+    body;
+    /** Seconds to wait before retrying, when the server said. */
+    retryAfter;
+    constructor(message, init = {}) {
+        super(message, init.cause !== undefined ? { cause: init.cause } : undefined);
+        this.name = new.target.name;
+        this.status = init.status ?? 0;
+        this.code = init.code;
+        this.body = init.body;
+        this.retryAfter = init.retryAfter ?? null;
+    }
+    /**
+     * Whether trying the same call again could work. True for a busy
+     * conversation, a sandbox still coming up, a rate limit and 5xx — false for
+     * anything the caller has to change first.
+     */
+    get retryable() {
+        if (RETRYABLE_CODES.has(this.code ?? ""))
+            return true;
+        return this.status === 429 || (this.status >= 500 && this.status < 600);
+    }
+    /** `errors: {field: [msg, …]}` as the server sends a 422; empty otherwise. */
+    get fieldErrors() {
+        const errors = this.body?.errors;
+        if (!errors || typeof errors !== "object" || Array.isArray(errors))
+            return {};
+        const out = {};
+        for (const [field, value] of Object.entries(errors)) {
+            if (Array.isArray(value))
+                out[field] = value.filter((v) => typeof v === "string");
+            else if (typeof value === "string")
+                out[field] = [value];
+        }
+        return out;
+    }
+}
+const RETRYABLE_CODES = new Set([
+    "conversation_busy",
+    "provisioning",
+    "sprite_probe_failed",
+    "sandbox_quota_exceeded",
+    // Another conversation's turn is using a one-at-a-time runtime's sandbox;
+    // it clears when that turn ends.
+    "sandbox_at_capacity",
+    "rate_limited",
+]);
+/** No API key, or the key was rejected (401). */
+export class AuthError extends FountainError {
+}
+/**
+ * The account is out of credit (`insufficient_credits`, 402). `upgradeUrl` is
+ * the billing page, where credit is bought. The class keeps its old name so
+ * callers written against the subscription era still catch it.
+ */
+export class SubscriptionRequiredError extends FountainError {
+    get upgradeUrl() {
+        const url = this.body?.upgrade_url;
+        return typeof url === "string" ? url : undefined;
+    }
+}
+/** Wrong id, or it belongs to another account — Fountain does not distinguish (404). */
+export class NotFoundError extends FountainError {
+}
+/** The request was well-formed but rejected (422). Read `fieldErrors`. */
+export class ValidationError extends FountainError {
+}
+/** Too many requests (429). */
+export class RateLimitError extends FountainError {
+}
+/**
+ * The agent is still working on the previous prompt (`conversation_busy`, a
+ * 400). Wait for the turn in flight, then send again — `Conversation#send`
+ * with `waitForIdle` does that for you.
+ */
+export class ConversationBusyError extends FountainError {
+}
+/**
+ * The sandbox is not up yet, Fountain could not reach the provider to check
+ * (`provisioning` / `sprite_probe_failed`), or the deployment is at its fleet
+ * ceiling (`fleet_full`) — all 503 with a `Retry-After`. Nothing is wrong and
+ * nothing was changed; the same call will work shortly.
+ */
+export class NotReadyError extends FountainError {
+}
+/**
+ * The account is at its concurrent-sandbox cap (`sandbox_quota_exceeded`, 429).
+ * Deliberately not a billing error: terminate a conversation and continue.
+ */
+export class QuotaExceededError extends FountainError {
+    /** Sandboxes in use right now. */
+    get activeSandboxes() {
+        return numberFrom(this.body, "active_sandboxes");
+    }
+    /** The cap. */
+    get limit() {
+        return numberFrom(this.body, "limit");
+    }
+}
+/** `run`/`send` gave up waiting. The turn is still running — resume it. */
+export class TimeoutError extends FountainError {
+    conversationId;
+    /** Whatever the agent had said by the deadline. */
+    partialText;
+    constructor(message, conversationId, partialText) {
+        super(message);
+        this.conversationId = conversationId;
+        this.partialText = partialText;
+    }
+}
+/** A name that matched no agent/vault/environment, or matched more than one. */
+export class ResolutionError extends FountainError {
+}
+/**
+ * The request never reached Fountain. In a browser this is nearly always CORS
+ * or a wrong base URL, and the message says so, because "Failed to fetch" has
+ * sent more than one person hunting through their own code.
+ */
+export class ConnectionError extends FountainError {
+}
+const HINTS = {
+    400: "bad request",
+    401: "unauthorized — check the API key",
+    402: "payment required — the account is out of credit",
+    403: "forbidden — the key may lack the scope for this call",
+    404: "not found — wrong id, or it belongs to another account",
+    409: "conflict",
+    422: "rejected",
+    429: "rate limited",
+    503: "temporarily unavailable",
+};
+/** Pick the class for a failure. `code` decides; status is the fallback. */
+export function errorForStatus(status, body, method, url, headers) {
+    const record = body && typeof body === "object" ? body : null;
+    const code = typeof record?.error === "string" ? record.error : undefined;
+    let detail = "";
+    if (record) {
+        const message = record.message ?? record.error ?? record.errors;
+        detail = typeof message === "string" ? message : message === undefined ? "" : JSON.stringify(message);
+    }
+    else if (typeof body === "string" && body.trim()) {
+        detail = body.trim().slice(0, 300);
+    }
+    const retryHeader = headers?.get("retry-after");
+    const retryAfter = retryHeader && Number.isFinite(Number(retryHeader)) ? Number(retryHeader) : null;
+    const message = [`HTTP ${status}`, HINTS[status], detail, `(${method} ${url})`]
+        .filter(Boolean)
+        .join(" ");
+    const init = { status, code, body, retryAfter };
+    switch (code) {
+        case "conversation_busy":
+            return new ConversationBusyError(message, init);
+        case "provisioning":
+        case "sprite_probe_failed":
+            return new NotReadyError(message, init);
+        case "sandbox_quota_exceeded":
+            return new QuotaExceededError(message, init);
+        case "subscription_required":
+        case "insufficient_credits":
+            return new SubscriptionRequiredError(message, init);
+        case "fleet_full":
+            return new NotReadyError(message, init);
+    }
+    switch (status) {
+        case 401:
+            return new AuthError(message, init);
+        case 402:
+            return new SubscriptionRequiredError(message, init);
+        case 404:
+            return new NotFoundError(message, init);
+        case 422:
+            return new ValidationError(message, init);
+        case 429:
+            return new RateLimitError(message, init);
+        default:
+            return new FountainError(message, init);
+    }
+}
+function numberFrom(body, key) {
+    const value = body?.[key];
+    return typeof value === "number" ? value : undefined;
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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