@flowget/ai 0.1.0

package/dist/emit-tool.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The `propose_workflow` tool — the ONE emit channel.
+ *
+ * The model authors a workflow by calling this tool; its arguments ARE
+ * the workflow graph (position-optional authoring schema) plus a short
+ * summary. A plain-text reply (no tool call) is a `message` instead —
+ * a plain answer or a clarifying question.
+ *
+ * The authoring schema uses internal `$ref: "#/$defs/…"` references.
+ * When embedded as a tool-parameter property those refs would resolve
+ * against the WRONG root, so we hoist the schema's `$defs` to the
+ * tool-parameters root and reference the graph as `#/$defs/WorkflowGraph`.
+ */
+import type { AiToolDefinition } from "./adapter.js";
+export declare const EMIT_TOOL_NAME = "propose_workflow";
+export declare function buildEmitTool(): AiToolDefinition;

package/dist/emit-tool.js

@@ -0,0 +1,48 @@
+/**
+ * The `propose_workflow` tool — the ONE emit channel.
+ *
+ * The model authors a workflow by calling this tool; its arguments ARE
+ * the workflow graph (position-optional authoring schema) plus a short
+ * summary. A plain-text reply (no tool call) is a `message` instead —
+ * a plain answer or a clarifying question.
+ *
+ * The authoring schema uses internal `$ref: "#/$defs/…"` references.
+ * When embedded as a tool-parameter property those refs would resolve
+ * against the WRONG root, so we hoist the schema's `$defs` to the
+ * tool-parameters root and reference the graph as `#/$defs/WorkflowGraph`.
+ */
+import { buildAuthoringSchema } from "./authoring-schema.js";
+import { isRecord } from "./guards.js";
+export const EMIT_TOOL_NAME = "propose_workflow";
+export function buildEmitTool() {
+    const schema = buildAuthoringSchema();
+    const schemaDefs = isRecord(schema["$defs"]) ? schema["$defs"] : {};
+    // The graph root, minus the JSON-Schema meta keys — its `$defs` are
+    // hoisted so nested `$ref: "#/$defs/WorkflowNode"` resolves.
+    const graphRoot = {};
+    for (const [key, value] of Object.entries(schema)) {
+        if (key === "$schema" || key === "$id" || key === "$defs")
+            continue;
+        graphRoot[key] = value;
+    }
+    return {
+        name: EMIT_TOOL_NAME,
+        description: "Emit the final workflow graph proposal. Call this exactly once, when you have a complete workflow that satisfies the user's command. The graph MUST use only node types present in the provided catalog and MUST validate against the workflow schema. Node positions are optional — omit them; the builder lays the graph out.",
+        parameters: {
+            type: "object",
+            additionalProperties: false,
+            required: ["graph", "summary"],
+            properties: {
+                graph: { $ref: "#/$defs/WorkflowGraph" },
+                summary: {
+                    type: "string",
+                    description: "One or two sentences describing what the workflow does (or what this change did to the existing graph).",
+                },
+            },
+            $defs: {
+                WorkflowGraph: graphRoot,
+                ...schemaDefs,
+            },
+        },
+    };
+}

package/dist/guardrail.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The guardrail — a pre-LLM policy gate.
+ *
+ * Runs BEFORE any model call (and before toolsets). It returns
+ * `allow` or `block(message)`; a block short-circuits the request into
+ * a `message` response with NO adapter call and NO token spend.
+ *
+ * There is **no default guardrail** — policy is the customer's. The
+ * port + call site ship; the customer supplies the rule (rate limits,
+ * banned intents, tenant policy, a moderation call, …).
+ */
+import type { Actor } from "@flowget/types";
+import type { AuthorRequest } from "./contract.js";
+export type GuardrailDecision = {
+    action: "allow";
+} | {
+    action: "block";
+    message: string;
+};
+export type GuardrailContext = {
+    actor?: Actor;
+};
+export type Guardrail = (request: AuthorRequest, context: GuardrailContext) => GuardrailDecision | Promise<GuardrailDecision>;
+/** Convenience: an `allow` decision. */
+export declare const allow: () => GuardrailDecision;
+/** Convenience: a `block` decision carrying the user-facing message. */
+export declare const block: (message: string) => GuardrailDecision;

package/dist/guardrail.js

@@ -0,0 +1,18 @@
+/**
+ * The guardrail — a pre-LLM policy gate.
+ *
+ * Runs BEFORE any model call (and before toolsets). It returns
+ * `allow` or `block(message)`; a block short-circuits the request into
+ * a `message` response with NO adapter call and NO token spend.
+ *
+ * There is **no default guardrail** — policy is the customer's. The
+ * port + call site ship; the customer supplies the rule (rate limits,
+ * banned intents, tenant policy, a moderation call, …).
+ */
+/** Convenience: an `allow` decision. */
+export const allow = () => ({ action: "allow" });
+/** Convenience: a `block` decision carrying the user-facing message. */
+export const block = (message) => ({
+    action: "block",
+    message,
+});

package/dist/guards.d.ts

@@ -0,0 +1,3 @@
+/** Internal shared type guards. Not part of the public barrel. */
+/** True for a plain object (not null, not an array). */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/guards.js

@@ -0,0 +1,5 @@
+/** Internal shared type guards. Not part of the public barrel. */
+/** True for a plain object (not null, not an array). */
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/hooks.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Audit hooks — the observability seam.
+ *
+ * `onProposal` fires when a valid workflow proposal is produced;
+ * `onBlocked` fires when the guardrail blocks a request. Route them to
+ * the customer's permanent audit sink (their format / SIEM). The
+ * hooks are best-effort side channels — they run after the decision
+ * and never alter the response.
+ *
+ * A batteries-included append-only sink ({@link inMemoryAuditSink}) is
+ * provided for local dev and tests.
+ */
+import type { Actor } from "@flowget/types";
+import type { AuthoredGraph } from "./contract.js";
+export type ProposalAuditEvent = {
+    type: "proposal";
+    command: string;
+    actor?: Actor;
+    summary: string;
+    graph: AuthoredGraph;
+};
+export type BlockedAuditEvent = {
+    type: "blocked";
+    command: string;
+    actor?: Actor;
+    /** The guardrail's user-facing block message. */
+    reason: string;
+};
+export type AuditEvent = ProposalAuditEvent | BlockedAuditEvent;
+export type AuditHooks = {
+    onProposal?: (event: ProposalAuditEvent) => void | Promise<void>;
+    onBlocked?: (event: BlockedAuditEvent) => void | Promise<void>;
+};
+export type InMemoryAuditSink = Required<AuditHooks> & {
+    /** Append-only log of every audit event, in order. */
+    readonly entries: readonly AuditEvent[];
+};
+/**
+ * A default append-only, in-memory audit sink. Every proposal / block
+ * is pushed to `entries`. Swap for a durable sink in production.
+ */
+export declare function inMemoryAuditSink(): InMemoryAuditSink;

package/dist/hooks.js

@@ -0,0 +1,28 @@
+/**
+ * Audit hooks — the observability seam.
+ *
+ * `onProposal` fires when a valid workflow proposal is produced;
+ * `onBlocked` fires when the guardrail blocks a request. Route them to
+ * the customer's permanent audit sink (their format / SIEM). The
+ * hooks are best-effort side channels — they run after the decision
+ * and never alter the response.
+ *
+ * A batteries-included append-only sink ({@link inMemoryAuditSink}) is
+ * provided for local dev and tests.
+ */
+/**
+ * A default append-only, in-memory audit sink. Every proposal / block
+ * is pushed to `entries`. Swap for a durable sink in production.
+ */
+export function inMemoryAuditSink() {
+    const entries = [];
+    return {
+        entries,
+        onProposal: (event) => {
+            entries.push(event);
+        },
+        onBlocked: (event) => {
+            entries.push(event);
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `@flowget/ai` — request-first, stateless AI workflow-authoring PRIMITIVES.
+ *
+ * `author(config, request)` turns a natural-language command + the
+ * customer's node catalog into a schema-valid Flowget workflow graph.
+ * This package ships **primitives, not an HTTP server**: build a config
+ * with `resolveConfig` and call `author`, then wrap it in whatever
+ * transport you need (a customer who wants an API writes it themselves).
+ * Every piece — the LLM adapter, catalog source, guardrail, authorizers,
+ * toolsets, audit hooks, validator — is a named, typed, swappable hook
+ * with a batteries-included default.
+ *
+ * Quickstart:
+ *
+ * ```ts
+ * import { resolveConfig, author, openaiAdapter } from "@flowget/ai";
+ *
+ * const config = await resolveConfig({
+ *   adapter: openaiAdapter({ apiKey: process.env.OPENROUTER_API_KEY! }),
+ *   catalog: { registryDir: process.env.REGISTRY_DIR! },
+ * });
+ * const event = await author(config, { command: "email ops on new orders" });
+ * // event.kind is "proposal" (a workflow graph) or "message" (a text reply).
+ * ```
+ *
+ * The public surface is an EXPLICIT allow-list (not `export *`): only the
+ * names below are semver-stable API. Prompt-assembly, schema-loading, and
+ * emit-tool internals (`buildSystemPrompt`, `loadWorkflowSchema`,
+ * `buildEmitTool`, `runAuthorizers`, `ToolRegistry`, …) are deliberately
+ * kept private so they can evolve without a breaking change.
+ */
+export { author, authorStream } from "./author.js";
+export { AuthorizationError } from "./authorizer.js";
+export { buildAuthoringSchema } from "./authoring-schema.js";
+export { resolveCatalog } from "./catalog.js";
+export { finalizeConfig, resolveConfig } from "./config.js";
+export { EMIT_TOOL_NAME } from "./emit-tool.js";
+export { allow, block } from "./guardrail.js";
+export { inMemoryAuditSink } from "./hooks.js";
+export { mockAdapter, mockMessage, mockProposeWorkflow, mockToolCall, } from "./mock-adapter.js";
+export { DEFAULT_MODEL, OPENROUTER_BASE_URL, openaiAdapter, } from "./openai-adapter.js";
+export { DEFAULT_PERSONA, getDefaultSystemPrompt } from "./prompt.js";
+export { assertSafeUrl, UnsafeUrlError } from "./ssrf.js";
+export { createWorkflowValidator } from "./validator.js";
+export type { AiAdapter, AiGenerateRequest, AiGenerateResult, AiMessage, AiStreamPart, AiToolCall, AiToolDefinition, } from "./adapter.js";
+export type { AuthorOptions } from "./author.js";
+export type { Authorizer } from "./authorizer.js";
+export type { CatalogNode, CatalogSource } from "./catalog.js";
+export type { AiConfig, ResolvedConfig } from "./config.js";
+export type { AuthoredGraph, AuthoredNode, AuthorEvent, AuthorMessage, AuthorProposal, AuthorRequest, AuthorStreamEvent, } from "./contract.js";
+export type { Guardrail, GuardrailContext, GuardrailDecision, } from "./guardrail.js";
+export type { AuditEvent, AuditHooks, BlockedAuditEvent, InMemoryAuditSink, ProposalAuditEvent, } from "./hooks.js";
+export type { MockAdapter, MockScript, MockTurn } from "./mock-adapter.js";
+export type { OpenAiAdapterOptions, OpenAiChatClient, } from "./openai-adapter.js";
+export type { AssertSafeUrlOptions } from "./ssrf.js";
+export type { Tool, ToolContext, Toolset } from "./toolset.js";
+export type { ValidationResult, WorkflowValidator, WorkflowValidatorFactory, } from "./validator.js";

package/dist/index.js

@@ -0,0 +1,45 @@
+/**
+ * `@flowget/ai` — request-first, stateless AI workflow-authoring PRIMITIVES.
+ *
+ * `author(config, request)` turns a natural-language command + the
+ * customer's node catalog into a schema-valid Flowget workflow graph.
+ * This package ships **primitives, not an HTTP server**: build a config
+ * with `resolveConfig` and call `author`, then wrap it in whatever
+ * transport you need (a customer who wants an API writes it themselves).
+ * Every piece — the LLM adapter, catalog source, guardrail, authorizers,
+ * toolsets, audit hooks, validator — is a named, typed, swappable hook
+ * with a batteries-included default.
+ *
+ * Quickstart:
+ *
+ * ```ts
+ * import { resolveConfig, author, openaiAdapter } from "@flowget/ai";
+ *
+ * const config = await resolveConfig({
+ *   adapter: openaiAdapter({ apiKey: process.env.OPENROUTER_API_KEY! }),
+ *   catalog: { registryDir: process.env.REGISTRY_DIR! },
+ * });
+ * const event = await author(config, { command: "email ops on new orders" });
+ * // event.kind is "proposal" (a workflow graph) or "message" (a text reply).
+ * ```
+ *
+ * The public surface is an EXPLICIT allow-list (not `export *`): only the
+ * names below are semver-stable API. Prompt-assembly, schema-loading, and
+ * emit-tool internals (`buildSystemPrompt`, `loadWorkflowSchema`,
+ * `buildEmitTool`, `runAuthorizers`, `ToolRegistry`, …) are deliberately
+ * kept private so they can evolve without a breaking change.
+ */
+// --- Runtime API (values) ---
+export { author, authorStream } from "./author.js";
+export { AuthorizationError } from "./authorizer.js";
+export { buildAuthoringSchema } from "./authoring-schema.js";
+export { resolveCatalog } from "./catalog.js";
+export { finalizeConfig, resolveConfig } from "./config.js";
+export { EMIT_TOOL_NAME } from "./emit-tool.js";
+export { allow, block } from "./guardrail.js";
+export { inMemoryAuditSink } from "./hooks.js";
+export { mockAdapter, mockMessage, mockProposeWorkflow, mockToolCall, } from "./mock-adapter.js";
+export { DEFAULT_MODEL, OPENROUTER_BASE_URL, openaiAdapter, } from "./openai-adapter.js";
+export { DEFAULT_PERSONA, getDefaultSystemPrompt } from "./prompt.js";
+export { assertSafeUrl, UnsafeUrlError } from "./ssrf.js";
+export { createWorkflowValidator } from "./validator.js";

package/dist/mock-adapter.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A deterministic mock `AiAdapter` — the E2E testing seam.
+ *
+ * Drive `author` / `authorStream` with a scripted mock instead of a
+ * live LLM: pass an array of turns (returned in order) or a function of
+ * the request, then assert the resulting `message | proposal`. No
+ * network, no API key, fully deterministic. This is exactly how a
+ * customer writes an acceptance test against their own config.
+ */
+import type { AiAdapter, AiGenerateRequest, AiGenerateResult } from "./adapter.js";
+export type MockTurn = AiGenerateResult;
+export type MockScript = MockTurn[] | ((request: AiGenerateRequest, callIndex: number) => MockTurn | Promise<MockTurn>);
+export type MockAdapter = AiAdapter & {
+    /** Every request the adapter received, in order — assert against these. */
+    readonly calls: readonly AiGenerateRequest[];
+};
+export declare function mockAdapter(script: MockScript): MockAdapter;
+/** A plain-text turn — becomes a `message` (reply or clarifying question). */
+export declare function mockMessage(text: string): MockTurn;
+/** A turn that calls a named (toolset) tool with the given arguments. */
+export declare function mockToolCall(name: string, args: Record<string, unknown>, id?: string): MockTurn;
+/** A turn that emits a workflow proposal via the `propose_workflow` tool. */
+export declare function mockProposeWorkflow(graph: unknown, summary: string, id?: string): MockTurn;

package/dist/mock-adapter.js

@@ -0,0 +1,48 @@
+/**
+ * A deterministic mock `AiAdapter` — the E2E testing seam.
+ *
+ * Drive `author` / `authorStream` with a scripted mock instead of a
+ * live LLM: pass an array of turns (returned in order) or a function of
+ * the request, then assert the resulting `message | proposal`. No
+ * network, no API key, fully deterministic. This is exactly how a
+ * customer writes an acceptance test against their own config.
+ */
+import { EMIT_TOOL_NAME } from "./emit-tool.js";
+export function mockAdapter(script) {
+    const calls = [];
+    let index = 0;
+    return {
+        calls,
+        async generate(request) {
+            calls.push(request);
+            const callIndex = index++;
+            if (typeof script === "function")
+                return script(request, callIndex);
+            const turn = script[callIndex];
+            if (turn === undefined) {
+                throw new Error(`mockAdapter: no scripted turn for adapter call #${callIndex} (script has ${script.length} turn(s)).`);
+            }
+            return turn;
+        },
+    };
+}
+/** A plain-text turn — becomes a `message` (reply or clarifying question). */
+export function mockMessage(text) {
+    return { text, toolCalls: [] };
+}
+// Monotonic suffix so a default id is unique even when the same tool is
+// scripted twice (two `mockToolCall("x", …)` turns must not share `call_x`).
+let nextCallId = 0;
+/** A turn that calls a named (toolset) tool with the given arguments. */
+export function mockToolCall(name, args, id = `call_${name}_${nextCallId++}`) {
+    return { text: null, toolCalls: [{ id, name, arguments: args }] };
+}
+/** A turn that emits a workflow proposal via the `propose_workflow` tool. */
+export function mockProposeWorkflow(graph, summary, id = `call_propose_${nextCallId++}`) {
+    return {
+        text: null,
+        toolCalls: [
+            { id, name: EMIT_TOOL_NAME, arguments: { graph, summary } },
+        ],
+    };
+}

package/dist/openai-adapter.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The default `AiAdapter`: the `openai` SDK pointed at OpenRouter's
+ * OpenAI-compatible endpoint, using native tool-calling.
+ *
+ * Zero-config path: `openaiAdapter({ apiKey })`. Swap the model or
+ * point at another OpenAI-compatible gateway via `model` / `baseURL`.
+ * For a non-OpenAI LLM, implement {@link AiAdapter} directly instead.
+ *
+ * **Credential handling.** `apiKey` is captured in closure at
+ * construct and never appears on a public method signature. `baseURL`
+ * is SSRF-validated once at construct (`assertSafeUrl`); runtime calls
+ * do not re-validate.
+ */
+import OpenAI from "openai";
+import type { AiAdapter } from "./adapter.js";
+/** OpenRouter's OpenAI-compatible base URL — the default upstream. */
+export declare const OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1";
+/**
+ * A default OpenRouter model slug. Tool-calling capable and cheap;
+ * override per deployment via `model` (or per call via the request).
+ */
+export declare const DEFAULT_MODEL = "openai/gpt-4o-mini";
+/**
+ * The slice of the `openai` client this adapter uses. Declared
+ * structurally so a test can inject a fake client without a network
+ * round-trip, and so the public type never widens to the full SDK.
+ */
+export type OpenAiChatClient = {
+    chat: {
+        completions: {
+            create(params: OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming, options?: {
+                signal?: AbortSignal;
+            }): Promise<{
+                choices: Array<{
+                    message: OpenAI.Chat.Completions.ChatCompletionMessage;
+                }>;
+            }>;
+            create(params: OpenAI.Chat.Completions.ChatCompletionCreateParamsStreaming, options?: {
+                signal?: AbortSignal;
+            }): Promise<AsyncIterable<OpenAI.Chat.Completions.ChatCompletionChunk>>;
+        };
+    };
+};
+export type OpenAiAdapterOptions = {
+    /** Credential, captured in closure. Never travels on any method. */
+    apiKey: string;
+    /** OpenAI-compatible base URL. Defaults to OpenRouter. SSRF-validated at construct. */
+    baseURL?: string;
+    /** Default model slug used when a request does not override it. */
+    model?: string;
+    /** SSRF-guard escape hatch for a knowingly-private mirror. */
+    allowHosts?: readonly string[];
+    /** Extra headers to send on every request (e.g. OpenRouter attribution). */
+    defaultHeaders?: Record<string, string>;
+    /**
+     * Inject a pre-built client. Primarily a testing seam — pass a fake
+     * to exercise request/response mapping without hitting the network.
+     * When omitted, a real `openai` client is constructed.
+     */
+    client?: OpenAiChatClient;
+};
+export declare function openaiAdapter(options: OpenAiAdapterOptions): AiAdapter;

package/dist/openai-adapter.js

@@ -0,0 +1,176 @@
+/**
+ * The default `AiAdapter`: the `openai` SDK pointed at OpenRouter's
+ * OpenAI-compatible endpoint, using native tool-calling.
+ *
+ * Zero-config path: `openaiAdapter({ apiKey })`. Swap the model or
+ * point at another OpenAI-compatible gateway via `model` / `baseURL`.
+ * For a non-OpenAI LLM, implement {@link AiAdapter} directly instead.
+ *
+ * **Credential handling.** `apiKey` is captured in closure at
+ * construct and never appears on a public method signature. `baseURL`
+ * is SSRF-validated once at construct (`assertSafeUrl`); runtime calls
+ * do not re-validate.
+ */
+import OpenAI from "openai";
+import { assertSafeUrl } from "./ssrf.js";
+/** OpenRouter's OpenAI-compatible base URL — the default upstream. */
+export const OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1";
+/**
+ * A default OpenRouter model slug. Tool-calling capable and cheap;
+ * override per deployment via `model` (or per call via the request).
+ */
+export const DEFAULT_MODEL = "openai/gpt-4o-mini";
+export function openaiAdapter(options) {
+    if (typeof options.apiKey !== "string" || options.apiKey.length === 0) {
+        throw new Error("openaiAdapter: `apiKey` is required and must be a non-empty string.");
+    }
+    const baseURL = options.baseURL ?? OPENROUTER_BASE_URL;
+    assertSafeUrl(baseURL, options.allowHosts ? { allowHosts: options.allowHosts } : {});
+    const defaultModel = options.model ?? DEFAULT_MODEL;
+    const client = options.client ??
+        new OpenAI({
+            apiKey: options.apiKey,
+            baseURL,
+            ...(options.defaultHeaders
+                ? { defaultHeaders: options.defaultHeaders }
+                : {}),
+        });
+    return {
+        async generate(request) {
+            const params = {
+                model: request.model ?? defaultModel,
+                messages: request.messages.map(toOpenAiMessage),
+                ...(request.tools.length > 0
+                    ? {
+                        tools: request.tools.map(toOpenAiTool),
+                        tool_choice: "auto",
+                    }
+                    : {}),
+            };
+            const response = await client.chat.completions.create(params, request.signal ? { signal: request.signal } : undefined);
+            const message = response.choices[0]?.message;
+            return {
+                text: message?.content ?? null,
+                toolCalls: extractToolCalls(message),
+            };
+        },
+        async *generateStream(request) {
+            const params = {
+                model: request.model ?? defaultModel,
+                messages: request.messages.map(toOpenAiMessage),
+                stream: true,
+                ...(request.tools.length > 0
+                    ? {
+                        tools: request.tools.map(toOpenAiTool),
+                        tool_choice: "auto",
+                    }
+                    : {}),
+            };
+            const stream = await client.chat.completions.create(params, request.signal ? { signal: request.signal } : undefined);
+            let text = "";
+            // Tool-call args stream in fragments keyed by their choice index; we
+            // accumulate id/name/arguments across chunks and parse once at the end.
+            const toolCalls = new Map();
+            for await (const chunk of stream) {
+                const delta = chunk.choices[0]?.delta;
+                if (delta?.content) {
+                    text += delta.content;
+                    yield { type: "text-delta", delta: delta.content };
+                }
+                for (const call of delta?.tool_calls ?? []) {
+                    const acc = toolCalls.get(call.index) ?? { id: "", name: "", args: "" };
+                    if (call.id)
+                        acc.id = call.id;
+                    if (call.function?.name)
+                        acc.name = call.function.name;
+                    if (call.function?.arguments)
+                        acc.args += call.function.arguments;
+                    toolCalls.set(call.index, acc);
+                }
+            }
+            const resolved = [...toolCalls.values()]
+                .filter((call) => call.name.length > 0)
+                .map((call) => ({
+                id: call.id,
+                name: call.name,
+                arguments: parseArguments(call.args),
+            }));
+            yield {
+                type: "result",
+                result: { text: text.length > 0 ? text : null, toolCalls: resolved },
+            };
+        },
+    };
+}
+function toOpenAiMessage(message) {
+    switch (message.role) {
+        case "system":
+            return { role: "system", content: message.content };
+        case "user":
+            return { role: "user", content: message.content };
+        case "tool":
+            return {
+                role: "tool",
+                tool_call_id: message.toolCallId,
+                content: message.content,
+            };
+        case "assistant":
+            return {
+                role: "assistant",
+                content: message.content,
+                ...(message.toolCalls && message.toolCalls.length > 0
+                    ? {
+                        tool_calls: message.toolCalls.map((call) => ({
+                            id: call.id,
+                            type: "function",
+                            function: {
+                                name: call.name,
+                                arguments: JSON.stringify(call.arguments),
+                            },
+                        })),
+                    }
+                    : {}),
+            };
+    }
+}
+function toOpenAiTool(tool) {
+    return {
+        type: "function",
+        function: {
+            name: tool.name,
+            description: tool.description,
+            parameters: tool.parameters,
+        },
+    };
+}
+function extractToolCalls(message) {
+    if (!message?.tool_calls)
+        return [];
+    const out = [];
+    for (const call of message.tool_calls) {
+        if (call.type !== "function")
+            continue;
+        out.push({
+            id: call.id,
+            name: call.function.name,
+            arguments: parseArguments(call.function.arguments),
+        });
+    }
+    return out;
+}
+function parseArguments(raw) {
+    if (raw.trim().length === 0)
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return {};
+    }
+    catch {
+        // Malformed JSON from the model — surface an empty object so the
+        // validate/repair loop rejects and re-prompts rather than crashing.
+        return {};
+    }
+}

package/dist/prompt.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Prompt assembly — the grounding + persona + request.
+ *
+ * The **system prompt** is a stable prefix: persona, the customer's
+ * node catalog, and a compact reference to the workflow-graph shape.
+ * Being stable across a request's repair turns (and across requests
+ * with the same catalog) makes it the natural **prompt-caching
+ * prefix** — providers that cache by leading-token prefix amortize it.
+ *
+ * The **user prompt** carries the variable part: the command, the
+ * optional `currentGraph` being edited, and the optional client-carried
+ * `context`.
+ *
+ * Grounding note: the AUTHORITATIVE emission schema rides on the
+ * `propose_workflow` tool's parameters (the model fills it directly).
+ * The schema echoed here is trimmed (verbose `markdownDescription`
+ * copy stripped) so the model understands the graph model without
+ * paying for the full annotated schema twice.
+ */
+import type { AiMessage } from "./adapter.js";
+import type { CatalogNode } from "./catalog.js";
+import type { AuthorRequest } from "./contract.js";
+export declare const DEFAULT_PERSONA = "You are Flowget's workflow-authoring assistant. You turn a user's natural-language request into a valid Flowget workflow graph, using ONLY the nodes in the provided catalog.\n\nRules:\n- Author the smallest correct workflow that satisfies the request \u2014 do not add nodes the request did not ask for.\n- A runnable workflow needs at least one node whose category is \"trigger\".\n- Use only node \"type\" values that appear in the catalog (a node's \"type\" equals a catalog entry's \"id\"). Never invent a node type.\n- Wire nodes with edges. An edge's \"source\"/\"target\" are node ids. For branch routing, set an edge \"sourceHandle\" to one of the source node's declared handle ids.\n- To use an upstream node's output in a downstream node's config, write a template: {{ steps.<nodeId>.output.<key> }} for a node's output or {{ trigger.<key> }} for the trigger payload. Only reference node ids that exist in the graph.\n- Node \"position\" is optional \u2014 omit it; the builder lays the graph out.\n- Most config fields hold a scalar, but some are COMPOUND objects. A field of type \"schedule\" takes: { \"spec\": { \"cron\": \"0 8 * * *\", \"timezone\": \"UTC\" }, \"overlap\": \"skip\" }. The cron (or \"intervalSeconds\": <number> instead of cron) and \"timezone\" nest UNDER \"spec\"; \"spec\" is required with exactly one of cron or intervalSeconds; \"overlap\" is optional (defaults \"skip\"). Do NOT emit a flat { \"cron\", \"timezone\" }.\n- When the request is ambiguous or under-specified, DO NOT guess. Reply in plain text with ONE concise clarifying question instead of calling the tool.\n- If the request is NOT an authorable runnable workflow \u2014 e.g. \"clear/discard/empty the canvas\", \"delete everything\", \"start over\", or anything that would require an empty or non-runnable graph \u2014 do NOT call propose_workflow. Reply in plain text explaining that you author runnable workflows and that clearing the canvas is a manual action (delete the nodes directly in the builder). NEVER echo the current graph unchanged as a no-op proposal.\n- If a current graph is provided and it ALREADY satisfies the request, reply in plain text saying the workflow already does that, instead of proposing an unchanged graph.\n- When (and only when) you have a complete, valid workflow to author or change, call the \"propose_workflow\" tool exactly once.";
+export type SystemPromptInput = {
+    catalog: readonly CatalogNode[];
+    /** Persona override; falls back to {@link DEFAULT_PERSONA}. */
+    persona?: string;
+};
+export declare function buildSystemPrompt(input: SystemPromptInput): string;
+/**
+ * The EXACT default system prompt `author` sends for a given catalog
+ * — {@link DEFAULT_PERSONA} + the catalog + the workflow-graph schema
+ * (loaded from `@flowget/types`, the single source of truth). This is
+ * the un-overridden `buildSystemPrompt({ catalog })` the author loop
+ * uses when `config.persona` is unset (see `runToolLoop` in
+ * `author.ts`).
+ *
+ * A thin, intent-revealing public entry point for consumers that need
+ * the real prompt without reaching into the author loop or replicating
+ * the persona — e.g. an out-of-process evaluation harness that measures
+ * the raw model output the library's own prompt elicits. The schema is
+ * loaded internally (never injected) so the prompt can never drift from
+ * the shipped `@flowget/types` schema.
+ */
+export declare function getDefaultSystemPrompt(catalog: readonly CatalogNode[]): string;
+export declare function buildUserPrompt(request: AuthorRequest): string;
+export declare function buildInitialMessages(request: AuthorRequest, system: SystemPromptInput): AiMessage[];