@managoat/fountain-sdk 1.25.0

package/dist/turn.js

@@ -0,0 +1,205 @@
+const TERMINAL_TURN_STATES = new Set(["done", "failed", "interrupted"]);
+/**
+ * Folds the log feed into one turn's answer.
+ *
+ * The feed carries every turn of the conversation and every stream of each
+ * turn, so "what did the agent just say" is a filtering problem, not a
+ * concatenation one. This class is the filter:
+ *
+ *   - a `stage`/`turn` event opens and closes the turn we are following, and
+ *     is the only thing that says how it ended;
+ *   - `output` events carry server-parsed `blocks`; only `text` is the answer,
+ *     `tool_use` is noise worth naming, `thinking` is neither;
+ *   - text that follows a tool call is a new message, so it gets a paragraph
+ *     break — the rule that stops a transcript reading as one run-on sentence.
+ *
+ * The joining rules are ported from the Hermes plugin, which learned them
+ * against real runtimes: ACP streams one message as chunks that join with
+ * nothing, while a legacy stdout row is a whole message and joins as a
+ * paragraph.
+ */
+export class TurnFollower {
+    turnNumber;
+    turnId = null;
+    started = false;
+    state = null;
+    exitCode = null;
+    reason = null;
+    chunks = [];
+    tools = [];
+    breakBeforeText = false;
+    constructor(turnNumber, turnId = null) {
+        this.turnNumber = turnNumber;
+        this.turnId = turnId;
+    }
+    get text() {
+        return this.chunks.join("").trim();
+    }
+    get toolsUsed() {
+        return [...this.tools];
+    }
+    get finished() {
+        return this.state !== null;
+    }
+    /** Fold one event in, and report what a streaming caller should be told. */
+    apply(event) {
+        if (event.kind === "stage")
+            return this.applyStage(event);
+        if (event.kind !== "output")
+            return [];
+        return this.applyOutput(event);
+    }
+    applyStage(event) {
+        if (event.stage !== "turn")
+            return [];
+        const meta = parseJson(event.data) ?? {};
+        if (!this.matchesTurn(meta))
+            return [];
+        if (event.state === "started") {
+            this.started = true;
+            this.turnId = asString(meta.turn_id) ?? this.turnId;
+            return [{ type: "turn-start", turnNumber: this.turnNumber, turnId: this.turnId }];
+        }
+        if (event.state && TERMINAL_TURN_STATES.has(event.state)) {
+            this.state = event.state;
+            this.turnId = this.turnId ?? asString(meta.turn_id);
+            if (typeof meta.exit_code === "number")
+                this.exitCode = meta.exit_code;
+            const reason = asString(meta.reason) ?? asString(meta.stop_reason);
+            if (reason)
+                this.reason = reason;
+            return [
+                { type: "turn-end", state: this.state, exitCode: this.exitCode, reason: this.reason },
+            ];
+        }
+        return [];
+    }
+    matchesTurn(meta) {
+        if (this.turnId && asString(meta.turn_id) === this.turnId)
+            return true;
+        return meta.turn_number === this.turnNumber;
+    }
+    applyOutput(event) {
+        const turnId = asString(event.turn_id);
+        // A different turn's output — history, or a turn someone else started.
+        if (this.turnId && turnId && turnId !== this.turnId)
+            return [];
+        // Output from before our turn opened is the tail of an older one.
+        if (!this.started && !this.turnId)
+            return [];
+        const acp = event.stream === "acp";
+        const out = [];
+        for (const block of event.blocks ?? []) {
+            out.push({ type: "block", block, event });
+            out.push(...this.applyBlock(block, acp));
+        }
+        return out;
+    }
+    applyBlock(block, acp) {
+        const body = block.body ?? "";
+        if (block.kind === "text") {
+            if (!body)
+                return [];
+            const prefix = this.paragraphBreak(acp);
+            if (prefix)
+                this.chunks.push(prefix);
+            this.chunks.push(body);
+            this.breakBeforeText = false;
+            return [{ type: "text", text: prefix + body }];
+        }
+        if (block.kind === "thinking") {
+            return body ? [{ type: "thinking", text: body }] : [];
+        }
+        // `raw` and `init` are transport bookkeeping: not output, and not a break.
+        if (block.kind === "raw" || block.kind === "init")
+            return [];
+        this.breakBeforeText = true;
+        // The turn is now blocked until somebody answers. Surface it as its own
+        // event rather than a bare block, because a caller that does not handle it
+        // loses the tool call to the server's deny-on-timeout.
+        if (block.kind === "permission_request") {
+            const request = toPermissionRequest(block);
+            return request ? [{ type: "permission", request, block }] : [];
+        }
+        if (block.kind === "tool_use") {
+            const name = asString(block.name);
+            if (!name)
+                return [];
+            if (!this.tools.includes(name))
+                this.tools.push(name);
+            return [{ type: "tool", name, block }];
+        }
+        // A `result` block is the answer only when the runtime said nothing else.
+        if (block.kind === "result" && !this.chunks.length && body) {
+            this.chunks.push(body);
+            return [{ type: "text", text: body }];
+        }
+        if (block.kind === "error" && body) {
+            const text = `\n[error] ${body}\n`;
+            this.chunks.push(text);
+            return [{ type: "text", text }];
+        }
+        return [];
+    }
+    /**
+     * ACP chunks are pieces of one message and join with nothing; anything after
+     * a tool call is a new message. A legacy row is a whole message either way.
+     */
+    paragraphBreak(acp) {
+        if (!this.chunks.length)
+            return "";
+        if (acp && !this.breakBeforeText)
+            return "";
+        const last = this.chunks[this.chunks.length - 1] ?? "";
+        return last.endsWith("\n") ? "" : "\n\n";
+    }
+}
+/**
+ * Read a `permission_request` block into something answerable.
+ *
+ * No `request_id` means there is nothing a caller could send back, and an
+ * empty `options` list means there is nothing they could choose — either way
+ * the block is a notice, not a question, so it is dropped rather than handed
+ * over as a request that cannot be answered.
+ */
+function toPermissionRequest(block) {
+    const requestId = asString(block.request_id);
+    if (!requestId)
+        return null;
+    const options = [];
+    for (const raw of block.options ?? []) {
+        if (!raw || typeof raw !== "object")
+            continue;
+        const option = raw;
+        const optionId = asString(option.optionId) ?? asString(option.option_id);
+        if (!optionId)
+            continue;
+        options.push({ ...option, optionId });
+    }
+    if (!options.length)
+        return null;
+    return {
+        requestId,
+        summary: asString(block.summary) ?? asString(block.body),
+        toolName: asString(block.name),
+        toolId: asString(block.tool_id),
+        options,
+    };
+}
+function parseJson(raw) {
+    if (raw && typeof raw === "object")
+        return raw;
+    if (typeof raw !== "string" || !raw.trim())
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function asString(value) {
+    return typeof value === "string" && value ? value : null;
+}
+//# sourceMappingURL=turn.js.map

package/dist/turn.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,144 @@
+/**
+ * The SDK's own vocabulary.
+ *
+ * Anything the API defines comes from `schemas.ts`, which is generated from
+ * the OpenAPI document — so it cannot drift. What is left here is what a spec
+ * cannot say: that many log events fold into one *turn*, that a run can be
+ * awaited or streamed, and how a turn ended.
+ */
+export type { Agent, AgentInput, AgentPatch, AuthMe, Block, Catalog, Connection, ConnectionProvider, ConnectionProviderInput, ConnectionProviderPatch, ConversationRecord, ConversationTreeNode, Environment, EnvironmentInput, EnvironmentPatch, ImageInput, LogEvent, Repository, Runner, SandboxDiff, SandboxEntry, SandboxFile, SandboxListing, SandboxRecord, Schedule, ScheduleInput, SchedulePatch, SearchHit, Secret, TeamAddInput, TeamCommsStatus, Teammate, TeammateContact, Turn, Vault, VaultInput, VaultPatch, VaultSecret, VaultSecretMetadataPatch, } from "./schemas.ts";
+import type { Agent, Block, ConversationRecord, LogEvent } from "./schemas.ts";
+/** The agent runtimes Fountain can start. */
+export type Runtime = NonNullable<Agent["runtime"]>;
+/** Sandbox backends. `null` on an agent means "the instance default". */
+export type SandboxProvider = NonNullable<Agent["sandbox_provider"]>;
+/** A conversation's lifecycle status. */
+export type ConversationStatus = ConversationRecord["status"];
+/**
+ * A skill given to an agent — either written into the sandbox verbatim, or
+ * installed from GitHub. Exactly one of `content` or `source` per entry; the
+ * spec cannot express that, so this narrows what the generated type allows.
+ */
+export type SkillInput = {
+    name: string;
+    content: string;
+    source?: never;
+    ref?: never;
+} | {
+    source: string;
+    ref?: string;
+    name?: string;
+    content?: never;
+};
+/**
+ * A log event off `/api/team/stream`, which multiplexes every teammate's
+ * conversation onto one connection and labels each payload with the two ids a
+ * roster routes on. Both are absent on a single-conversation stream, and on
+ * the `team` / `schedule` notices the same endpoint interleaves.
+ */
+export interface TeamEvent extends LogEvent {
+    conversation_id?: string;
+    agent_id?: string;
+}
+/** The log-event streams a conversation carries. */
+export type Stream = "stdout" | "stderr" | "acp" | "stage";
+/**
+ * One choice an agent offered when it asked permission. `optionId` is what an
+ * answer sends back; `kind` is the vocabulary a UI can render without reading
+ * the label (`allow_once`, `allow_always`, `reject_once`, `reject_always`, …).
+ * Runtimes may add fields, so the rest is left open.
+ */
+export interface PermissionOption {
+    optionId: string;
+    kind?: string;
+    name?: string;
+    [key: string]: unknown;
+}
+/**
+ * The agent is holding a tool call, waiting to be told whether to run it.
+ *
+ * Only agents with an `ask` entry in `permission_policy` produce these; the
+ * default is `auto_allow` and never asks. Nothing else in the turn advances
+ * until this is answered, and if nobody answers before the server's timeout it
+ * is denied — so a caller that ignores these on an `ask` agent gets a turn that
+ * does less than it was told to, not an error.
+ */
+export interface PermissionRequest {
+    /** Pass this to `answer`. */
+    requestId: string;
+    /** What the agent wants to do, in the runtime's words. */
+    summary: string | null;
+    /** The tool it is asking about. Claude titles this with the command itself. */
+    toolName: string | null;
+    toolId: string | null;
+    /** The choices the agent offered, in its order. Answer with one of these. */
+    options: PermissionOption[];
+}
+/** How a turn ended. `timeout` means the SDK stopped waiting, not that the agent did. */
+export type TurnState = "done" | "failed" | "interrupted" | "timeout";
+/** What a run emits while it works. */
+export type RunEvent = {
+    type: "conversation";
+    conversationId: string;
+    conversation: ConversationRecord;
+    url: string;
+} | {
+    type: "turn-start";
+    turnNumber: number;
+    turnId: string | null;
+} | {
+    type: "text";
+    text: string;
+} | {
+    type: "thinking";
+    text: string;
+} | {
+    type: "tool";
+    name: string;
+    block: Block;
+} | {
+    type: "permission";
+    request: PermissionRequest;
+    block: Block;
+} | {
+    type: "block";
+    block: Block;
+    event: LogEvent;
+} | {
+    type: "event";
+    event: LogEvent;
+} | {
+    type: "turn-end";
+    state: TurnState;
+    exitCode: number | null;
+    reason: string | null;
+};
+/** The finished turn. */
+export interface RunResult {
+    /** The conversation the turn ran in. Keep it: the sandbox is still there. */
+    conversationId: string;
+    /** Where a human watches it. */
+    url: string;
+    /** Which turn this was — 1 for a fresh `run`, 2+ for a `send`. */
+    turnNumber: number;
+    /** Everything the agent said, tool noise removed. */
+    text: string;
+    /** Tool names the agent used, in the order it first used each. */
+    toolsUsed: string[];
+    /** How the turn ended. */
+    state: TurnState;
+    /** The runtime's exit code when it reported one. */
+    exitCode: number | null;
+    /** Why it stopped, when the runtime said. */
+    reason: string | null;
+    /** The conversation's status when the turn ended. */
+    status: string | null;
+    /** Every log event consumed, when `collectEvents` was set. */
+    events?: LogEvent[];
+}
+/** A named thing an agent can be given: an environment or a vault. */
+export interface NamedResource {
+    id: string;
+    name: string;
+    [key: string]: unknown;
+}

package/dist/types.js

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

package/dist/types.js.map

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

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@managoat/fountain-sdk",
+  "version": "1.25.0",
+  "description": "Run a coding agent on a real computer, with your repos and your credentials, in one call.",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20.19"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/managoat/fountain.git",
+    "directory": "sdk/typescript"
+  },
+  "homepage": "https://github.com/managoat/fountain/tree/main/sdk/typescript",
+  "keywords": [
+    "fountain",
+    "agent",
+    "sandbox",
+    "coding-agent",
+    "acp",
+    "sdk"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "node": "./dist/node.js",
+      "browser": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "generate": "openapi-typescript ${FOUNTAIN_OPENAPI:-../../dist/openapi.json} -o src/generated/openapi.ts",
+    "verify-contract": "node scripts/verify-contract.mjs",
+    "conformance": "node --test test/conformance.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test test/*.test.ts",
+    "prepublishOnly": "node scripts/ci-publishes.mjs && npm run typecheck && npm test && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.0",
+    "openapi-typescript": "^7.13.0",
+    "typescript": "^5.7.0"
+  },
+  "browser": {
+    "./dist/node.js": "./dist/index.js"
+  }
+}