@spendgraph/tools 0.2.0

package/dist/builtin/think/index.d.ts

@@ -0,0 +1 @@
+export { think } from "./think.js";

package/dist/builtin/think/index.js

@@ -0,0 +1 @@
+export { think } from "./think.js";

package/dist/builtin/think/think.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Somewhere to reason without it becoming the answer.
+ *
+ * It does nothing, which is the point: the thought lands in the steps rather
+ * than in the reply, and a model given room to plan before a multi-step tool
+ * sequence uses the tools better.
+ */
+export declare function think(): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
+    readonly name: "thought";
+    readonly type: "text";
+    readonly required: true;
+    readonly maxLength: 4000;
+}]>>;

package/dist/builtin/think/think.js

@@ -0,0 +1,19 @@
+import { tool } from "../../tool/index.js";
+/**
+ * Somewhere to reason without it becoming the answer.
+ *
+ * It does nothing, which is the point: the thought lands in the steps rather
+ * than in the reply, and a model given room to plan before a multi-step tool
+ * sequence uses the tools better.
+ */
+export function think() {
+    return tool({
+        name: "think",
+        effect: "readonly",
+        description: "Think a step through before acting. Use it to check a plan against the rules, " +
+            "to work out what is still missing, or to decide between two tools. It changes " +
+            "nothing and returns nothing — it is scratch space, not an answer.",
+        args: [{ name: "thought", type: "text", required: true, maxLength: 4000 }],
+        run: () => "noted",
+    });
+}

package/dist/builtin/web-search/index.d.ts

@@ -0,0 +1 @@
+export { type SearchDepth, type WebSearchOptions, webSearch } from "./web-search.js";

package/dist/builtin/web-search/index.js

@@ -0,0 +1 @@
+export { webSearch } from "./web-search.js";

package/dist/builtin/web-search/reply.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The provider's reply as the tool hands it back.
+ *
+ * Sources come from `search_results` where the account returns them and from
+ * `citations` otherwise, so one tool works across both reply shapes. Citation
+ * and reasoning tokens are their own line items on a grounded model, and
+ * `computeCostMicros` takes both — dropping them prices a paid call at zero.
+ */
+export declare function readReply(body: unknown, fallbackModel: string, maxChars: number, maxResults: number): {
+    answer: string;
+    results: {
+        url: string;
+    }[];
+    model: string;
+    truncated: boolean;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        citationTokens: number;
+        reasoningTokens: number;
+        searchQueries: number;
+    };
+};

package/dist/builtin/web-search/reply.js

@@ -0,0 +1,35 @@
+function sources(raw) {
+    const listed = raw.search_results ?? [];
+    if (listed.length) {
+        return listed.flatMap((r) => (r.url ? [{ url: r.url, title: r.title, date: r.date }] : []));
+    }
+    return (raw.citations ?? []).map((url) => ({ url }));
+}
+/**
+ * The provider's reply as the tool hands it back.
+ *
+ * Sources come from `search_results` where the account returns them and from
+ * `citations` otherwise, so one tool works across both reply shapes. Citation
+ * and reasoning tokens are their own line items on a grounded model, and
+ * `computeCostMicros` takes both — dropping them prices a paid call at zero.
+ */
+export function readReply(body, fallbackModel, maxChars, maxResults) {
+    const raw = body;
+    const answer = raw.choices?.[0]?.message?.content ?? "";
+    const found = sources(raw);
+    const results = found.slice(0, maxResults);
+    const usage = raw.usage ?? {};
+    return {
+        answer: answer.slice(0, maxChars),
+        results,
+        model: raw.model ?? fallbackModel,
+        truncated: answer.length > maxChars || found.length > results.length,
+        usage: {
+            inputTokens: usage.prompt_tokens ?? 0,
+            outputTokens: usage.completion_tokens ?? 0,
+            citationTokens: usage.citation_tokens ?? 0,
+            reasoningTokens: usage.reasoning_tokens ?? 0,
+            searchQueries: usage.num_search_queries ?? 0,
+        },
+    };
+}

package/dist/builtin/web-search/web-search.d.ts

@@ -0,0 +1,50 @@
+/** How much searching one call is worth. */
+export type SearchDepth = "quick" | "pro" | "deep";
+export interface WebSearchOptions {
+    /** Perplexity key. Required, and read from here rather than the environment. */
+    apiKey: string;
+    /**
+     * Deepest tier the model may reach. Default `"pro"`.
+     *
+     * `"deep"` is opt-in because `sonar-deep-research` runs for minutes and bills
+     * reasoning and citation tokens on top of the usual two.
+     */
+    maxDepth?: SearchDepth;
+    /** Hosts results are restricted to. Set here, so the model cannot widen it. */
+    domains?: string[];
+    /** Give up after this. Defaults to 60000, or 300000 on a deep search. */
+    timeoutMs?: number;
+    /** Longest answer handed back. Default 20000 characters. */
+    maxChars?: number;
+    /** Longest source list handed back. Default 20. */
+    maxResults?: number;
+    /** Injected for tests. */
+    fetch?: typeof fetch;
+}
+/**
+ * The live web, through Perplexity's Sonar models.
+ *
+ * The tier is the model's to choose and yours to cap: `sonar-deep-research` is
+ * minutes and orders of magnitude, and a model reaching for it unprompted is
+ * the failure `maxDepth` exists to prevent. Tokens come back rather than a
+ * price, because what a search costs is the pricing table's business.
+ */
+export declare function webSearch(opts: WebSearchOptions): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
+    readonly name: "query";
+    readonly type: "string";
+    readonly required: true;
+    readonly maxLength: 1000;
+    readonly description: "What to find out, as a question. One thing, not several.";
+}, {
+    readonly name: "depth";
+    readonly type: "enum";
+    readonly required: false;
+    readonly options: readonly ["quick", "pro", "deep"];
+    readonly description: "Default quick. Raise it only when a first pass would not settle it.";
+}, {
+    readonly name: "recency";
+    readonly type: "enum";
+    readonly required: false;
+    readonly options: readonly ["day", "week", "month", "year"];
+    readonly description: "Only consider pages published within this. Leave unset for anything.";
+}]>>;

package/dist/builtin/web-search/web-search.js

@@ -0,0 +1,93 @@
+import { tool } from "../../tool/index.js";
+import { readReply } from "./reply.js";
+const DEPTHS = ["quick", "pro", "deep"];
+const MODELS = {
+    quick: "sonar",
+    pro: "sonar-pro",
+    deep: "sonar-deep-research",
+};
+const ENDPOINT = "https://api.perplexity.ai/chat/completions";
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEEP_TIMEOUT_MS = 300_000;
+const DEFAULT_MAX_CHARS = 20_000;
+const DEFAULT_MAX_RESULTS = 20;
+const ERROR_DETAIL_CHARS = 500;
+function describe(maxDepth, domains) {
+    return ("Searches the live web and returns an answer with the sources it rests on. Use it for " +
+        "anything that turns on current facts — prices, releases, who holds a post, what " +
+        "changed. quick is one pass and is right for most lookups; pro searches wider and cites " +
+        "more." +
+        (maxDepth === "deep"
+            ? " deep is an exhaustive multi-step review: minutes, and many times the cost. Ask for it only when a wrong answer is expensive."
+            : " deep is not enabled here.") +
+        (domains?.length ? ` Results come only from ${domains.join(", ")}.` : ""));
+}
+/**
+ * The live web, through Perplexity's Sonar models.
+ *
+ * The tier is the model's to choose and yours to cap: `sonar-deep-research` is
+ * minutes and orders of magnitude, and a model reaching for it unprompted is
+ * the failure `maxDepth` exists to prevent. Tokens come back rather than a
+ * price, because what a search costs is the pricing table's business.
+ */
+export function webSearch(opts) {
+    if (!opts.apiKey?.trim()) {
+        throw new Error("webSearch needs a Perplexity apiKey; it will not read one from the process.");
+    }
+    const doFetch = opts.fetch ?? globalThis.fetch;
+    const maxDepth = opts.maxDepth ?? "pro";
+    return tool({
+        name: "web_search",
+        description: describe(maxDepth, opts.domains),
+        effect: "readonly",
+        args: [
+            {
+                name: "query",
+                type: "string",
+                required: true,
+                maxLength: 1000,
+                description: "What to find out, as a question. One thing, not several.",
+            },
+            {
+                name: "depth",
+                type: "enum",
+                required: false,
+                options: ["quick", "pro", "deep"],
+                description: "Default quick. Raise it only when a first pass would not settle it.",
+            },
+            {
+                name: "recency",
+                type: "enum",
+                required: false,
+                options: ["day", "week", "month", "year"],
+                description: "Only consider pages published within this. Leave unset for anything.",
+            },
+        ],
+        run: async ({ query, depth = "quick", recency }) => {
+            if (DEPTHS.indexOf(depth) > DEPTHS.indexOf(maxDepth)) {
+                throw new Error(`web_search was asked for "${depth}", above the "${maxDepth}" this deployment allows.`);
+            }
+            const model = MODELS[depth];
+            const fallback = depth === "deep" ? DEEP_TIMEOUT_MS : DEFAULT_TIMEOUT_MS;
+            const res = await doFetch(ENDPOINT, {
+                method: "POST",
+                signal: AbortSignal.timeout(opts.timeoutMs ?? fallback),
+                headers: {
+                    authorization: `Bearer ${opts.apiKey}`,
+                    "content-type": "application/json",
+                },
+                body: JSON.stringify({
+                    model,
+                    messages: [{ role: "user", content: query }],
+                    ...(recency ? { search_recency_filter: recency } : {}),
+                    ...(opts.domains?.length ? { search_domain_filter: opts.domains } : {}),
+                }),
+            });
+            if (!res.ok) {
+                const detail = (await res.text()).slice(0, ERROR_DETAIL_CHARS);
+                throw new Error(`Perplexity returned ${res.status} for ${model}: ${detail}`);
+            }
+            return readReply(await res.json(), model, opts.maxChars ?? DEFAULT_MAX_CHARS, opts.maxResults ?? DEFAULT_MAX_RESULTS);
+        },
+    });
+}

package/dist/builtin/write-document/commission.d.ts

@@ -0,0 +1,56 @@
+import { type AbortSignalLike, type MoaClientConfig } from "./http.js";
+import type { CommissionInput, CommissionResult } from "./types.js";
+/**
+ * Moa's task surface — fire, then await.
+ *
+ * `create()` hands back an id immediately and `get()` reads it; pass `waitMs`
+ * (or use {@link pollUntilDone}) to long-poll, so one call is awaited rather
+ * than a loop tight-polling. `cancel()` is optional so a test stub stays small.
+ */
+export interface CommissionClient {
+    create(input: CommissionInput): Promise<string>;
+    get(id: string, opts?: {
+        waitMs?: number;
+        signal?: AbortSignalLike;
+    }): Promise<CommissionResult>;
+    cancel?(id: string): Promise<void>;
+}
+/**
+ * HTTP {@link CommissionClient} over Moa's task API (`POST /tasks` → `GET /tasks/:id`).
+ *
+ * The request body carries the ask as prose — Moa's artifact pipeline is
+ * prompt-driven and `POST /tasks` strips unknown fields, so context, design and
+ * deliverables are blocks on the task rather than parameters beside it.
+ */
+export declare function createCommissionClient(config?: MoaClientConfig): CommissionClient;
+/** The sane ceiling for a chat-bound call. A rendered document wants minutes, not this. */
+export declare const INTERACTIVE_TIMEOUT_MS = 30000;
+/** Thrown by {@link pollUntilDone} when the caller's abort signal fires. */
+export declare class CommissionAbortedError extends Error {
+    readonly commissionId: string;
+    constructor(commissionId: string);
+}
+/** Thrown when the wait ran out. The task itself is still running server-side. */
+export declare class CommissionTimeoutError extends Error {
+    readonly commissionId: string;
+    readonly timeoutMs: number;
+    constructor(commissionId: string, timeoutMs: number);
+}
+export interface PollOptions {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    /**
+     * Stops the wait and throws {@link CommissionAbortedError}, cutting the held
+     * long-poll with it. The task keeps running — cancelling it is the caller's call.
+     */
+    signal?: AbortSignalLike;
+    /**
+     * How long to wait before re-reading a done task whose result has not landed
+     * yet. Moa flips the status slightly before it writes. Default 0.
+     */
+    settleMs?: number;
+    /** Keep settling while a done task carries no artifacts. Set it when files were asked for. */
+    expectArtifacts?: boolean;
+}
+/** Wait for a commission to settle, long-polling rather than tight-polling. */
+export declare function pollUntilDone(client: CommissionClient, id: string, opts?: PollOptions): Promise<CommissionResult>;

package/dist/builtin/write-document/commission.js

@@ -0,0 +1,163 @@
+import { createRequest, MoaApiError } from "./http.js";
+const TASK_STATUS = {
+    queued: "pending",
+    running: "running",
+    succeeded: "done",
+    failed: "failed",
+    canceled: "failed",
+};
+const ARTIFACT_FORMATS = ["md", "pdf", "docx", "pptx"];
+const formatOf = (name) => {
+    const ext = name?.split(".").pop()?.toLowerCase();
+    return ext && ARTIFACT_FORMATS.includes(ext) ? ext : undefined;
+};
+function toArtifacts(raw) {
+    if (!raw?.length)
+        return undefined;
+    const artifacts = raw.flatMap((a) => {
+        const format = formatOf(a.name);
+        if (!format || !(a.url || a.data))
+            return [];
+        return [
+            {
+                name: a.name ?? `document.${format}`,
+                format,
+                url: a.url,
+                data: a.data,
+                mime: a.contentType,
+                sizeBytes: a.sizeBytes,
+            },
+        ];
+    });
+    return artifacts.length ? artifacts : undefined;
+}
+function deliverablesBlock(formats) {
+    return (`\n\n<deliverables>\nBesides the text answer, save the finished deliverable ` +
+        `into the artifacts/ directory of your working dir as: ` +
+        `${formats.map((f) => `one .${f} file`).join(", ")}.\n</deliverables>`);
+}
+function taskText(input) {
+    let task = input.task;
+    if (input.context)
+        task += `\n\n<context>\n${input.context}\n</context>`;
+    if (input.design)
+        task += `\n\n<design>\n${input.design}\n</design>`;
+    if (input.artifacts?.length)
+        task += deliverablesBlock(input.artifacts);
+    return task;
+}
+/**
+ * HTTP {@link CommissionClient} over Moa's task API (`POST /tasks` → `GET /tasks/:id`).
+ *
+ * The request body carries the ask as prose — Moa's artifact pipeline is
+ * prompt-driven and `POST /tasks` strips unknown fields, so context, design and
+ * deliverables are blocks on the task rather than parameters beside it.
+ */
+export function createCommissionClient(config = {}) {
+    const request = createRequest(config);
+    return {
+        async create(input) {
+            const created = await request("/tasks", {
+                method: "POST",
+                body: {
+                    task: taskText(input),
+                    mode: "striker",
+                    ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+                    ...(input.newSessionId ? { newSessionId: input.newSessionId } : {}),
+                },
+            });
+            if (!created.id)
+                throw new MoaApiError("Moa did not return a task id", 502);
+            return created.id;
+        },
+        async get(id, opts) {
+            const qs = opts?.waitMs && opts.waitMs > 0 ? `?waitMs=${Math.floor(opts.waitMs)}` : "";
+            const t = await request(`/tasks/${encodeURIComponent(id)}${qs}`, {
+                signal: opts?.signal,
+            });
+            const status = t.status ? TASK_STATUS[t.status] : undefined;
+            return {
+                id: t.id ?? id,
+                status: status ?? "running",
+                output: t.result,
+                error: t.error,
+                costUsd: t.costUsd,
+                numTurns: t.numTurns,
+                sessionId: t.sessionId,
+                artifacts: toArtifacts(t.artifacts),
+            };
+        },
+        async cancel(id) {
+            await request(`/tasks/${encodeURIComponent(id)}`, { method: "DELETE" });
+        },
+    };
+}
+/** The sane ceiling for a chat-bound call. A rendered document wants minutes, not this. */
+export const INTERACTIVE_TIMEOUT_MS = 30_000;
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+const SETTLE_ATTEMPTS = 3;
+const LONGPOLL_WINDOW_MS = 25_000;
+/** Thrown by {@link pollUntilDone} when the caller's abort signal fires. */
+export class CommissionAbortedError extends Error {
+    commissionId;
+    constructor(commissionId) {
+        super(`Commission ${commissionId} was cancelled by the caller.`);
+        this.name = "CommissionAbortedError";
+        this.commissionId = commissionId;
+    }
+}
+/** Thrown when the wait ran out. The task itself is still running server-side. */
+export class CommissionTimeoutError extends Error {
+    commissionId;
+    timeoutMs;
+    constructor(commissionId, timeoutMs) {
+        super(`Commission ${commissionId} did not complete within ${timeoutMs / 1000}s. ` +
+            `The task may still be running in the background.`);
+        this.name = "CommissionTimeoutError";
+        this.commissionId = commissionId;
+        this.timeoutMs = timeoutMs;
+    }
+}
+const sleep = (ms, signal) => new Promise((resolve) => {
+    const onAbort = () => resolve();
+    signal?.addEventListener("abort", onAbort, { once: true });
+    setTimeout(() => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve();
+    }, ms);
+});
+/** Wait for a commission to settle, long-polling rather than tight-polling. */
+export async function pollUntilDone(client, id, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? INTERACTIVE_TIMEOUT_MS;
+    const pollIntervalMs = opts.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const settleMs = opts.settleMs ?? 0;
+    const signal = opts.signal;
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+        if (signal?.aborted)
+            throw new CommissionAbortedError(id);
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            throw new CommissionTimeoutError(id, timeoutMs);
+        let result;
+        try {
+            result = await client.get(id, { waitMs: Math.min(remaining, LONGPOLL_WINDOW_MS), signal });
+        }
+        catch (err) {
+            if (signal?.aborted)
+                throw new CommissionAbortedError(id);
+            throw err;
+        }
+        if (result.status === "failed")
+            return result;
+        if (result.status === "done") {
+            const unsettled = (r) => !r.output?.trim() || (opts.expectArtifacts === true && !r.artifacts?.length);
+            for (let i = 0; settleMs > 0 && i < SETTLE_ATTEMPTS && unsettled(result); i++) {
+                await sleep(settleMs);
+                result = await client.get(id);
+            }
+            return result;
+        }
+        await sleep(Math.min(pollIntervalMs, Math.max(0, deadline - Date.now())), signal);
+    }
+}

package/dist/builtin/write-document/design.d.ts

@@ -0,0 +1,49 @@
+import type { ArtifactFormat } from "./types.js";
+/**
+ * The house style a commissioned document is built to.
+ *
+ * Every field is optional because a caller overrides only what its brand
+ * actually fixes; the rest falls back to {@link DEFAULT_DESIGN}.
+ */
+export interface DesignGuide {
+    /** What the style is called, so the document can say which one it followed. */
+    name?: string;
+    fonts?: {
+        heading?: string;
+        body?: string;
+        mono?: string;
+    };
+    palette?: {
+        primary?: string;
+        accent?: string;
+        text?: string;
+        muted?: string;
+        surface?: string;
+    };
+    /** Page size, margins, grid, density. */
+    layout?: string;
+    /** How a figure earns its place and what it may not do. */
+    charts?: string;
+    /** How the writing sounds. */
+    tone?: string;
+    /** Fetchable logo, dropped on the cover and nowhere else. */
+    logoUrl?: string;
+    /** Hard rules, appended to the defaults rather than replacing them. */
+    rules?: readonly string[];
+}
+/**
+ * What a document looks like when nobody has said.
+ *
+ * Chosen to be defensible rather than distinctive: one typeface, one accent,
+ * real whitespace, and figures that carry a single message.
+ */
+export declare const DEFAULT_DESIGN: DesignGuide;
+/**
+ * A caller's guide over the defaults: named fields win, `rules` accumulate.
+ *
+ * Rules append because they are constraints — a brand adding "never use red"
+ * means it as well as the defaults, not instead of them.
+ */
+export declare function mergeDesign(base: DesignGuide, over?: DesignGuide): DesignGuide;
+/** The guide as the block Moa reads, since its artifact pipeline is prompt-driven. */
+export declare function renderDesign(guide: DesignGuide, format: ArtifactFormat, notes?: string): string;

package/dist/builtin/write-document/design.js

@@ -0,0 +1,99 @@
+/**
+ * What a document looks like when nobody has said.
+ *
+ * Chosen to be defensible rather than distinctive: one typeface, one accent,
+ * real whitespace, and figures that carry a single message.
+ */
+export const DEFAULT_DESIGN = {
+    name: "Spendgraph house style",
+    fonts: { heading: "Inter", body: "Inter", mono: "JetBrains Mono" },
+    palette: {
+        primary: "#0F172A",
+        accent: "#2563EB",
+        text: "#111827",
+        muted: "#64748B",
+        surface: "#FFFFFF",
+    },
+    layout: "A4 portrait, 20mm margins, a single text column at 60-75 characters, a 4pt spacing scale, " +
+        "and one heading scale used consistently (28/20/16/12). Whitespace is the design.",
+    charts: "One message per figure, stated in its caption. Label series directly where there are three " +
+        "or fewer. No 3D, no gradients, no gridline heavier than the data, no pie chart past three " +
+        "slices, and axes that start at zero unless the caption says why not.",
+    tone: "Plain and specific. Lead with the finding, then the evidence. No filler adjectives, no " +
+        "throat-clearing, no sentence that survives being deleted.",
+    rules: [
+        "A cover carrying the title, date and author, and no other ornament.",
+        "Every number traceable to something in the source material; invent nothing.",
+        "Tables for anything being compared; prose for anything being argued.",
+        "No stock imagery, no clip art, no placeholder text in the finished file.",
+        "Page numbers on every page after the cover.",
+    ],
+};
+const FORMAT_CRAFT = {
+    pdf: "Cover, then contents if it runs past four pages, then the body. Figures captioned and " +
+        "referenced from the text. Nothing straddles a page break: no orphan heading, no split table row.",
+    pptx: "16:9. One idea per slide, and the title is that idea as a sentence — a claim, not a label. " +
+        "At most six lines of body per slide, one figure per slide at most, and everything you cut " +
+        "goes into the speaker notes. Close on decisions and next steps, not on 'thank you'.",
+    docx: "Real Word styles for headings rather than manual bold, a table-of-contents field rather " +
+        "than a typed list, a header row on every table, and captions on figures.",
+    md: "A title heading, ATX headings throughout, tables for comparisons, fenced code with a language tag, and no HTML.",
+};
+function mergeGroup(base, over) {
+    if (!base)
+        return over;
+    if (!over)
+        return base;
+    return { ...base, ...over };
+}
+/**
+ * A caller's guide over the defaults: named fields win, `rules` accumulate.
+ *
+ * Rules append because they are constraints — a brand adding "never use red"
+ * means it as well as the defaults, not instead of them.
+ */
+export function mergeDesign(base, over) {
+    if (!over)
+        return base;
+    return {
+        ...base,
+        ...over,
+        fonts: mergeGroup(base.fonts, over.fonts),
+        palette: mergeGroup(base.palette, over.palette),
+        rules: [...(base.rules ?? []), ...(over.rules ?? [])],
+    };
+}
+const line = (label, value) => (value ? [`${label}: ${value}`] : []);
+/** The guide as the block Moa reads, since its artifact pipeline is prompt-driven. */
+export function renderDesign(guide, format, notes) {
+    const { fonts, palette } = guide;
+    const parts = [
+        ...line("Style", guide.name),
+        ...line("Typefaces", [
+            fonts?.heading && `headings ${fonts.heading}`,
+            fonts?.body && `body ${fonts.body}`,
+            fonts?.mono && `code ${fonts.mono}`,
+        ]
+            .filter(Boolean)
+            .join(", ") || undefined),
+        ...line("Palette", [
+            palette?.primary && `primary ${palette.primary}`,
+            palette?.accent && `accent ${palette.accent}`,
+            palette?.text && `text ${palette.text}`,
+            palette?.muted && `muted ${palette.muted}`,
+            palette?.surface && `surface ${palette.surface}`,
+        ]
+            .filter(Boolean)
+            .join(", ") || undefined),
+        ...line("Layout", guide.layout),
+        ...line("Figures", guide.charts),
+        ...line("Voice", guide.tone),
+        ...line("Logo", guide.logoUrl),
+        `Format craft (.${format}): ${FORMAT_CRAFT[format]}`,
+        ...(guide.rules?.length ? [`Rules:\n${guide.rules.map((r) => `- ${r}`).join("\n")}`] : []),
+        ...(notes?.trim()
+            ? [`Overrides for this document, which win over everything above:\n${notes.trim()}`]
+            : []),
+    ];
+    return parts.join("\n");
+}

package/dist/builtin/write-document/http.d.ts

@@ -0,0 +1,34 @@
+/** Anything shaped like an `AbortSignal`, so a Worker's own signal fits too. */
+export interface AbortSignalLike {
+    readonly aborted: boolean;
+    addEventListener(type: "abort", listener: () => void, opts?: {
+        once?: boolean;
+    }): void;
+    removeEventListener(type: "abort", listener: () => void): void;
+}
+/** Where Moa lives, unless a config says otherwise. */
+export declare const MOA_BASE_URL = "https://api.fnmoa.com";
+export interface MoaClientConfig {
+    /** Read from here rather than the environment, as every other builtin does. */
+    apiKey?: string;
+    baseUrl?: string;
+    /** Ceiling on one HTTP call, not on the commission. Default 60000. */
+    timeoutMs?: number;
+    /** Injected for tests. */
+    fetch?: typeof fetch;
+}
+/** A non-2xx from Moa, carrying the status so a caller can tell 4xx from 5xx. */
+export declare class MoaApiError extends Error {
+    readonly status: number;
+    readonly detail?: string;
+    constructor(message: string, status: number, detail?: string);
+}
+interface RequestOptions {
+    method?: string;
+    body?: unknown;
+    signal?: AbortSignalLike;
+    timeoutMs?: number;
+}
+/** One `request<T>(path, opts)` against Moa, with auth, timeout and error shape settled. */
+export declare function createRequest(config?: MoaClientConfig): <T>(path: string, opts?: RequestOptions) => Promise<T>;
+export {};