@flowget/ai 0.1.0

package/dist/author.js

@@ -0,0 +1,244 @@
+/**
+ * The command → proposal core.
+ *
+ * Orchestration (stateless — nothing survives the call):
+ *   1. authorizers verify the trusted actor (throw ⇒ request rejected);
+ *   2. the guardrail runs pre-LLM (block ⇒ a `message`, no adapter call);
+ *   3. the tool-calling loop assembles the prompt, calls the adapter,
+ *      dispatches actor-scoped toolset calls, and validates/repairs the
+ *      emitted graph until it is valid — or the model asks a clarifying
+ *      question, or the bounds are hit;
+ *   4. audit hooks fire on the outcome.
+ *
+ * A `proposal` is only ever returned once the graph passes the
+ * validator (schema + catalog + structural + trigger-presence), so only
+ * runnable-shaped graphs reach the caller.
+ *
+ * {@link author} and {@link authorStream} share ONE per-turn decision
+ * ({@link stepTurn}); the only difference is how each fetches a turn —
+ * `adapter.generate` (buffered) vs {@link streamOneTurn} (token deltas).
+ */
+import { runAuthorizers } from "./authorizer.js";
+import { buildEmitTool, EMIT_TOOL_NAME } from "./emit-tool.js";
+import { buildInitialMessages } from "./prompt.js";
+/** Fallback text for a degenerate empty turn (no tool call, no text). */
+const EMPTY_TURN_MESSAGE = "I didn't produce a response. Please rephrase or add detail.";
+/** Given up after exhausting the per-request adapter-turn budget. */
+const MAX_STEPS_MESSAGE = "I could not complete the request within the allowed number of steps. Please try a more specific command.";
+export async function author(config, request, options = {}) {
+    const actor = request.actor;
+    // 1. Authorizers (throw ⇒ AuthorizationError bubbles to the handler).
+    await runAuthorizers(config.authorizers, actor, request);
+    // 2. Guardrail (pre-LLM). A block short-circuits with no token spend.
+    if (config.guardrail !== undefined) {
+        const decision = await config.guardrail(request, actor ? { actor } : {});
+        if (decision.action === "block") {
+            await config.hooks.onBlocked?.({
+                type: "blocked",
+                command: request.command,
+                ...(actor ? { actor } : {}),
+                reason: decision.message,
+            });
+            return { kind: "message", text: decision.message };
+        }
+    }
+    // 3. The tool-calling loop.
+    const event = await runToolLoop(config, request, options);
+    // 4. Audit the proposal.
+    if (event.kind === "proposal") {
+        await config.hooks.onProposal?.({
+            type: "proposal",
+            command: request.command,
+            ...(actor ? { actor } : {}),
+            summary: event.summary,
+            graph: event.graph,
+        });
+    }
+    return event;
+}
+/**
+ * Streaming sibling of {@link author}: identical orchestration, but the
+ * assistant's text is forwarded as `text-delta`s as it is generated (the chat
+ * "typing" feel), ending in exactly one terminal `proposal`, `message`, or
+ * `error`.
+ *
+ * Adapters that don't implement `generateStream` degrade cleanly — no deltas,
+ * just the terminal event. A failure DURING the stream is yielded as a
+ * terminal `{ kind: "error" }` (per {@link AuthorStreamEvent}) rather than
+ * thrown, so a consumer's `case "error"` is reachable. Pre-stream rejections
+ * (a throwing authorizer / guardrail) still throw, mirroring {@link author}
+ * so a transport can reject before opening the stream.
+ */
+export async function* authorStream(config, request, options = {}) {
+    const actor = request.actor;
+    // 1. Authorizers (throw ⇒ bubbles to the handler — pre-stream).
+    await runAuthorizers(config.authorizers, actor, request);
+    // 2. Guardrail (pre-LLM). A block short-circuits with no token spend.
+    if (config.guardrail !== undefined) {
+        const decision = await config.guardrail(request, actor ? { actor } : {});
+        if (decision.action === "block") {
+            await config.hooks.onBlocked?.({
+                type: "blocked",
+                command: request.command,
+                ...(actor ? { actor } : {}),
+                reason: decision.message,
+            });
+            yield { kind: "message", text: decision.message };
+            return;
+        }
+    }
+    // 3. The streaming tool loop — deltas out, terminal event returned.
+    //    Wrapped so a mid-stream failure becomes a terminal `error` event.
+    try {
+        const event = yield* runToolLoopStream(config, request, options);
+        // 4. Audit + emit the terminal event.
+        if (event.kind === "proposal") {
+            await config.hooks.onProposal?.({
+                type: "proposal",
+                command: request.command,
+                ...(actor ? { actor } : {}),
+                summary: event.summary,
+                graph: event.graph,
+            });
+            yield { kind: "proposal", graph: event.graph, summary: event.summary };
+        }
+        else {
+            yield { kind: "message", text: event.text };
+        }
+    }
+    catch (error) {
+        yield {
+            kind: "error",
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+function createTurnState(config, request) {
+    return {
+        tools: [buildEmitTool(), ...config.toolRegistry.definitions()],
+        messages: buildInitialMessages(request, {
+            catalog: config.catalog,
+            ...(config.persona !== undefined ? { persona: config.persona } : {}),
+        }),
+        toolContext: request.actor ? { actor: request.actor } : {},
+        repairs: 0,
+    };
+}
+function buildGenerateRequest(state, config, options) {
+    return {
+        messages: state.messages,
+        tools: state.tools,
+        ...(config.model !== undefined ? { model: config.model } : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
+    };
+}
+/**
+ * The one per-turn decision, shared by the buffered and streaming loops.
+ * Reads the adapter's result, mutates `state` (records the assistant
+ * turn + tool results, bumps the repair counter), and returns either a
+ * terminal {@link AuthorEvent} or the signal to run another turn.
+ */
+async function stepTurn(result, config, state) {
+    // No tool call ⇒ a plain-text message (a reply or a clarifying question).
+    if (result.toolCalls.length === 0) {
+        const text = result.text && result.text.length > 0 ? result.text : EMPTY_TURN_MESSAGE;
+        return { done: { kind: "message", text } };
+    }
+    // Record the assistant turn — the tool protocol requires a tool result
+    // for every tool call the assistant made.
+    state.messages.push({
+        role: "assistant",
+        content: result.text,
+        toolCalls: result.toolCalls,
+    });
+    for (const call of result.toolCalls) {
+        if (call.name === EMIT_TOOL_NAME) {
+            const graph = call.arguments["graph"];
+            const summary = typeof call.arguments["summary"] === "string"
+                ? call.arguments["summary"]
+                : "";
+            const verdict = config.validator(graph);
+            if (verdict.ok) {
+                // Return immediately — a later tool call in the same turn (e.g. a
+                // throwing toolset dispatch) must not discard a valid proposal.
+                return {
+                    done: { kind: "proposal", graph: graph, summary },
+                };
+            }
+            state.repairs++;
+            state.messages.push({
+                role: "tool",
+                toolCallId: call.id,
+                content: "The workflow did not validate. Fix ALL of these and call propose_workflow again:\n- " +
+                    verdict.errors.join("\n- "),
+            });
+        }
+        else if (config.toolRegistry.has(call.name)) {
+            const toolResult = await config.toolRegistry.dispatch(call, state.toolContext);
+            state.messages.push({
+                role: "tool",
+                toolCallId: call.id,
+                content: toolResult,
+            });
+        }
+        else {
+            // The model hallucinated a tool — tell it what actually exists.
+            state.messages.push({
+                role: "tool",
+                toolCallId: call.id,
+                content: `Unknown tool "${call.name}". Available tools: ${state.tools
+                    .map((tool) => tool.name)
+                    .join(", ")}.`,
+            });
+        }
+    }
+    if (state.repairs > config.maxRepairAttempts) {
+        return {
+            done: {
+                kind: "message",
+                text: `I could not produce a valid workflow after ${config.maxRepairAttempts} repair attempt(s). Please refine your request.`,
+            },
+        };
+    }
+    return { continue: true };
+}
+/** Buffered tool loop: fetch each turn via `adapter.generate`. */
+async function runToolLoop(config, request, options) {
+    const state = createTurnState(config, request);
+    for (let iteration = 0; iteration < config.maxToolIterations; iteration++) {
+        const result = await config.adapter.generate(buildGenerateRequest(state, config, options));
+        const step = await stepTurn(result, config, state);
+        if ("done" in step)
+            return step.done;
+    }
+    return { kind: "message", text: MAX_STEPS_MESSAGE };
+}
+/** One adapter turn, streamed: yields text deltas, returns the full result.
+ * Falls back to `generate` when the adapter has no `generateStream`. */
+async function* streamOneTurn(adapter, request) {
+    if (adapter.generateStream === undefined) {
+        return await adapter.generate(request);
+    }
+    let result;
+    for await (const part of adapter.generateStream(request)) {
+        if (part.type === "text-delta") {
+            yield { kind: "text-delta", delta: part.delta };
+        }
+        else {
+            result = part.result;
+        }
+    }
+    return result ?? { text: null, toolCalls: [] };
+}
+/** Streaming tool loop: fetch each turn via {@link streamOneTurn}, forwarding
+ * its text deltas, then feed the full result to the shared {@link stepTurn}. */
+async function* runToolLoopStream(config, request, options) {
+    const state = createTurnState(config, request);
+    for (let iteration = 0; iteration < config.maxToolIterations; iteration++) {
+        const result = yield* streamOneTurn(config.adapter, buildGenerateRequest(state, config, options));
+        const step = await stepTurn(result, config, state);
+        if ("done" in step)
+            return step.done;
+    }
+    return { kind: "message", text: MAX_STEPS_MESSAGE };
+}

package/dist/authoring-schema.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The **authoring schema** — the JSON Schema the AI emits against.
+ *
+ * It is the canonical `WorkflowGraph` schema that `@flowget/types`
+ * ships (`@flowget/types/schemas/workflow.schema.json`), with a single
+ * relaxation: `position` is no longer required on a node. The AI emits
+ * topology + config; the builder lays the graph out later. Deriving it
+ * from the shipped schema keeps a **single source of truth** — no
+ * hand-maintained copy to drift.
+ */
+/** Load the canonical workflow-graph JSON schema shipped by `@flowget/types`. */
+export declare function loadWorkflowSchema(): Record<string, unknown>;
+/**
+ * The position-optional authoring schema, derived from the shipped
+ * workflow schema. Returns a fresh object each call (safe to mutate).
+ */
+export declare function buildAuthoringSchema(): Record<string, unknown>;

package/dist/authoring-schema.js

@@ -0,0 +1,53 @@
+/**
+ * The **authoring schema** — the JSON Schema the AI emits against.
+ *
+ * It is the canonical `WorkflowGraph` schema that `@flowget/types`
+ * ships (`@flowget/types/schemas/workflow.schema.json`), with a single
+ * relaxation: `position` is no longer required on a node. The AI emits
+ * topology + config; the builder lays the graph out later. Deriving it
+ * from the shipped schema keeps a **single source of truth** — no
+ * hand-maintained copy to drift.
+ */
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { isRecord } from "./guards.js";
+const require = createRequire(import.meta.url);
+/**
+ * Memoized canonical schema. The file is stable for the process
+ * lifetime, and `loadWorkflowSchema` sits on the hot path
+ * (`buildSystemPrompt` + `buildEmitTool`, both per `author()` call), so
+ * the `readFileSync` + `JSON.parse` runs exactly once. Callers MUST
+ * treat the result as immutable — `buildAuthoringSchema` clones before
+ * mutating, and prompt assembly reads it non-destructively.
+ */
+let cachedSchema;
+/** Load the canonical workflow-graph JSON schema shipped by `@flowget/types`. */
+export function loadWorkflowSchema() {
+    if (cachedSchema !== undefined)
+        return cachedSchema;
+    const schemaPath = require.resolve("@flowget/types/schemas/workflow.schema.json");
+    const parsed = JSON.parse(readFileSync(schemaPath, "utf8"));
+    if (!isRecord(parsed)) {
+        throw new Error("workflow.schema.json did not parse to an object — @flowget/types may be corrupt.");
+    }
+    cachedSchema = parsed;
+    return parsed;
+}
+/**
+ * The position-optional authoring schema, derived from the shipped
+ * workflow schema. Returns a fresh object each call (safe to mutate).
+ */
+export function buildAuthoringSchema() {
+    const schema = structuredClone(loadWorkflowSchema());
+    const defs = schema["$defs"];
+    if (isRecord(defs)) {
+        const node = defs["WorkflowNode"];
+        if (isRecord(node) && Array.isArray(node["required"])) {
+            node["required"] = node["required"].filter((key) => key !== "position");
+        }
+    }
+    // Distinct $id so an AJV instance can hold both this and the
+    // canonical schema without a duplicate-id collision.
+    schema["$id"] = "https://schemas.flowget.com/workflow-authoring/v1.json";
+    return schema;
+}

package/dist/authorizer.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Authorizers — verify the TRUSTED actor before the guardrail and
+ * toolsets run.
+ *
+ * The actor is stamped by the customer's BFF and handed to `author()`
+ * on the request; an authorizer is where you VERIFY it (signature
+ * check, tenant lookup, scope assertion). Authorizers run first, in
+ * order. Any authorizer that throws rejects the whole request — throw
+ * {@link AuthorizationError} to carry a status your transport can map
+ * to a response (401 by default).
+ *
+ * Auth-agnostic stance: the library never forces authentication. With
+ * no authorizers configured and no actor on the request, the request
+ * proceeds anonymously — identity enforcement is the customer's choice.
+ */
+import type { Actor } from "@flowget/types";
+import type { AuthorRequest } from "./contract.js";
+export declare class AuthorizationError extends Error {
+    name: string;
+    readonly status: number;
+    constructor(message: string, status?: number);
+}
+export type Authorizer = (actor: Actor | undefined, request: AuthorRequest) => void | Promise<void>;
+/** Run every authorizer in order; the first throw rejects the request. */
+export declare function runAuthorizers(authorizers: readonly Authorizer[], actor: Actor | undefined, request: AuthorRequest): Promise<void>;

package/dist/authorizer.js

@@ -0,0 +1,29 @@
+/**
+ * Authorizers — verify the TRUSTED actor before the guardrail and
+ * toolsets run.
+ *
+ * The actor is stamped by the customer's BFF and handed to `author()`
+ * on the request; an authorizer is where you VERIFY it (signature
+ * check, tenant lookup, scope assertion). Authorizers run first, in
+ * order. Any authorizer that throws rejects the whole request — throw
+ * {@link AuthorizationError} to carry a status your transport can map
+ * to a response (401 by default).
+ *
+ * Auth-agnostic stance: the library never forces authentication. With
+ * no authorizers configured and no actor on the request, the request
+ * proceeds anonymously — identity enforcement is the customer's choice.
+ */
+export class AuthorizationError extends Error {
+    name = "AuthorizationError";
+    status;
+    constructor(message, status = 401) {
+        super(message);
+        this.status = status;
+    }
+}
+/** Run every authorizer in order; the first throw rejects the request. */
+export async function runAuthorizers(authorizers, actor, request) {
+    for (const authorizer of authorizers) {
+        await authorizer(actor, request);
+    }
+}

package/dist/catalog.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Catalog loading — the ONLY substrate the AI needs.
+ *
+ * The catalog is the customer's node metadata: the `.json` files under
+ * their `REGISTRY_DIR`, loaded via `@flowget/registry-loader`. We load
+ * ONLY the node `.json` (never `import` the executor `.ts`, never boot
+ * a worker, never touch Temporal), exactly the loader's documented
+ * web-side pattern. The library's dependency footprint stays tiny.
+ */
+import type { BuilderHints, NodeMetadata } from "@flowget/types";
+/** A single catalog entry — a node's projected metadata. */
+export type CatalogNode = NodeMetadata<BuilderHints>;
+/**
+ * Where the catalog comes from. Three accepted forms:
+ *
+ * - A pre-loaded `CatalogNode[]` — the customer already has metadata
+ *   (e.g. from their own build step) and hands it in directly.
+ * - `{ registryDir }` — a `REGISTRY_DIR`-shaped specifier string
+ *   (filesystem paths and/or npm subpaths, brace-expandable, comma-
+ *   separated), resolved and walked for you.
+ * - `{ paths }` — already-resolved absolute base paths to walk.
+ */
+export type CatalogSource = CatalogNode[] | {
+    registryDir: string;
+    cwd?: string;
+} | {
+    paths: readonly string[];
+};
+/** Resolve any {@link CatalogSource} to a flat `CatalogNode[]`. */
+export declare function resolveCatalog(source: CatalogSource): Promise<CatalogNode[]>;

package/dist/catalog.js

@@ -0,0 +1,22 @@
+/**
+ * Catalog loading — the ONLY substrate the AI needs.
+ *
+ * The catalog is the customer's node metadata: the `.json` files under
+ * their `REGISTRY_DIR`, loaded via `@flowget/registry-loader`. We load
+ * ONLY the node `.json` (never `import` the executor `.ts`, never boot
+ * a worker, never touch Temporal), exactly the loader's documented
+ * web-side pattern. The library's dependency footprint stays tiny.
+ */
+import { discoverRegistry, expandBraces, parseRegistryEnv, projectMetadata, resolveRegistrySpecifier, } from "@flowget/registry-loader";
+/** Resolve any {@link CatalogSource} to a flat `CatalogNode[]`. */
+export async function resolveCatalog(source) {
+    if (Array.isArray(source))
+        return [...source];
+    const paths = "registryDir" in source
+        ? parseRegistryEnv(source.registryDir)
+            .flatMap(expandBraces)
+            .map((entry) => resolveRegistrySpecifier(entry, source.cwd ? { cwd: source.cwd } : {}))
+        : [...source.paths];
+    const records = await discoverRegistry({ paths });
+    return records.map((record) => projectMetadata(record.json, record.jsonPath));
+}

package/dist/config.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Authoring configuration for `author()` — every piece a named, typed,
+ * swappable hook with a batteries-included default. `adapter` and
+ * `catalog` are the only required fields.
+ */
+import type { AiAdapter } from "./adapter.js";
+import type { Authorizer } from "./authorizer.js";
+import type { CatalogNode, CatalogSource } from "./catalog.js";
+import type { Guardrail } from "./guardrail.js";
+import type { AuditHooks } from "./hooks.js";
+import type { Toolset } from "./toolset.js";
+import { ToolRegistry } from "./toolset.js";
+import type { WorkflowValidator, WorkflowValidatorFactory } from "./validator.js";
+export declare const DEFAULT_MAX_TOOL_ITERATIONS = 8;
+export declare const DEFAULT_MAX_REPAIR_ATTEMPTS = 2;
+export type AiConfig = {
+    /** The LLM. Default: `openaiAdapter({ apiKey })` → OpenRouter. */
+    adapter: AiAdapter;
+    /** The node catalog — the substrate the AI authors against. */
+    catalog: CatalogSource;
+    /** Pre-LLM policy gate. No default (policy is the customer's). */
+    guardrail?: Guardrail;
+    /** Verify the trusted actor before guardrail/toolsets. Default: none. */
+    authorizers?: Authorizer[];
+    /** Actor-scoped, model-invoked tools. Default: none. */
+    toolsets?: Toolset[];
+    /** Audit sinks for proposals / blocks. Default: no-op. */
+    hooks?: AuditHooks;
+    /** Persona override for the system prompt. Default: workflow-only persona. */
+    persona?: string;
+    /** Workflow-validator factory. Default: AJV + catalog + template-ref. */
+    validator?: WorkflowValidatorFactory;
+    /** Default model slug forwarded to the adapter. Adapter picks its own if absent. */
+    model?: string;
+    /** Max adapter turns per request. Default 8. */
+    maxToolIterations?: number;
+    /** Max emit re-validation (repair) attempts per request. Default 2. */
+    maxRepairAttempts?: number;
+};
+/** Fully-resolved runtime config — every default applied. */
+export type ResolvedConfig = {
+    adapter: AiAdapter;
+    catalog: CatalogNode[];
+    validator: WorkflowValidator;
+    toolRegistry: ToolRegistry;
+    guardrail: Guardrail | undefined;
+    authorizers: Authorizer[];
+    hooks: AuditHooks;
+    persona: string | undefined;
+    model: string | undefined;
+    maxToolIterations: number;
+    maxRepairAttempts: number;
+};
+/** Build a {@link ResolvedConfig} from config + an already-loaded catalog. */
+export declare function finalizeConfig(config: AiConfig, catalog: CatalogNode[]): ResolvedConfig;
+/** Resolve config fully, loading the catalog from its source first. */
+export declare function resolveConfig(config: AiConfig): Promise<ResolvedConfig>;

package/dist/config.js

@@ -0,0 +1,36 @@
+/**
+ * Authoring configuration for `author()` — every piece a named, typed,
+ * swappable hook with a batteries-included default. `adapter` and
+ * `catalog` are the only required fields.
+ */
+import { resolveCatalog } from "./catalog.js";
+import { EMIT_TOOL_NAME } from "./emit-tool.js";
+import { ToolRegistry } from "./toolset.js";
+import { createWorkflowValidator } from "./validator.js";
+export const DEFAULT_MAX_TOOL_ITERATIONS = 8;
+export const DEFAULT_MAX_REPAIR_ATTEMPTS = 2;
+/** Build a {@link ResolvedConfig} from config + an already-loaded catalog. */
+export function finalizeConfig(config, catalog) {
+    if (catalog.length === 0) {
+        throw new Error("resolveConfig: the resolved catalog is empty. Point `catalog` at a REGISTRY_DIR containing node `.json` files, or pass a pre-loaded NodeMetadata[]. The AI cannot author a workflow with no node types.");
+    }
+    const validatorFactory = config.validator ?? createWorkflowValidator;
+    return {
+        adapter: config.adapter,
+        catalog,
+        validator: validatorFactory(catalog),
+        toolRegistry: new ToolRegistry(config.toolsets ?? [], [EMIT_TOOL_NAME]),
+        guardrail: config.guardrail,
+        authorizers: config.authorizers ?? [],
+        hooks: config.hooks ?? {},
+        persona: config.persona,
+        model: config.model,
+        maxToolIterations: config.maxToolIterations ?? DEFAULT_MAX_TOOL_ITERATIONS,
+        maxRepairAttempts: config.maxRepairAttempts ?? DEFAULT_MAX_REPAIR_ATTEMPTS,
+    };
+}
+/** Resolve config fully, loading the catalog from its source first. */
+export async function resolveConfig(config) {
+    const catalog = await resolveCatalog(config.catalog);
+    return finalizeConfig(config, catalog);
+}

package/dist/contract.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The shapes `author()` / `authorStream()` return.
+ *
+ * Stateless: every request is self-contained. The workflow graph IS
+ * the state, so there is no session store. Optional continuity is
+ * carried by the CALLER via {@link AuthorRequest.context} — the library
+ * never persists anything across requests.
+ *
+ * These are plain data shapes, not a wire format. YOU choose the
+ * transport: return an {@link AuthorEvent} as a JSON response, push
+ * {@link AuthorStreamEvent}s over SSE / WebSocket, or consume them
+ * in-process. The library ships no HTTP server.
+ */
+import type { Actor, WorkflowEdge, WorkflowNode } from "@flowget/types";
+/**
+ * A node in an *authored* graph. Identical to `@flowget/types`'
+ * `WorkflowNode` except `position` is **optional** — the AI emits
+ * topology + config, and the builder lays the graph out (iteration 2).
+ * A downstream consumer that needs coordinates fills them in.
+ */
+export type AuthoredNode = Omit<WorkflowNode, "position"> & {
+    position?: {
+        x: number;
+        y: number;
+    };
+};
+/**
+ * The graph `author()` proposes. Position-optional sibling of
+ * `WorkflowGraph`; still validates against the workflow JSON schema
+ * with the `position` requirement relaxed (see `authoring-schema.ts`).
+ */
+export type AuthoredGraph = {
+    nodes: AuthoredNode[];
+    edges: WorkflowEdge[];
+};
+/**
+ * The input to {@link author} / {@link authorStream}.
+ *
+ * - `command` — the natural-language instruction (required).
+ * - `currentGraph` — the graph being edited, for a targeted tweak.
+ *   Absent for a from-scratch authoring.
+ * - `actor` — the caller identity, as **caller-supplied JSON**. It is
+ *   threaded to `authorizers`, the guardrail, and actor-scoped
+ *   toolsets. **It is NOT trusted or verified by default** — the
+ *   library performs no signature or shape check. It becomes
+ *   trustworthy ONLY once you configure an `authorizer` that verifies
+ *   it (per the auth-agnostic stance). Any actor-scoped toolset that
+ *   gates data access on `actor` (e.g. by `tenantId`) therefore
+ *   REQUIRES an authorizer, or a caller can spoof the actor. Absent for
+ *   an anonymous deployment.
+ * - `context` — opaque, caller-carried continuity payload. The library
+ *   forwards it to the model as extra grounding but never inspects or
+ *   persists it.
+ *
+ * **Bound the inputs (host responsibility).** `command`, `currentGraph`,
+ * and `context` are all serialized into the prompt, and `currentGraph` /
+ * `context` can be re-sent across repair turns (up to `maxToolIterations`).
+ * The host MUST cap the size of ALL THREE before calling — an unbounded
+ * `currentGraph` or `context` is as much a token-DoS as a huge `command`.
+ * See the README guardrail example.
+ */
+export type AuthorRequest = {
+    command: string;
+    currentGraph?: AuthoredGraph;
+    actor?: Actor;
+    context?: unknown;
+};
+/**
+ * A workflow-graph proposal to preview / apply.
+ *
+ * **Model-authored, untrusted until approved.** The graph is a model
+ * suggestion, not a vetted artifact. Validation gates *runnability*
+ * (schema shape, known node types, resolvable references) — it does NOT
+ * vet field *values*: a malicious or mistaken value (e.g. an
+ * exfiltrating URL in an `http_request` node) passes validation. Never
+ * auto-apply a proposal without human review and/or a downstream
+ * field-value policy check. Treat `summary` as untrusted model output
+ * too (output-encode before rendering).
+ */
+export type AuthorProposal = {
+    kind: "proposal";
+    graph: AuthoredGraph;
+    summary: string;
+};
+/**
+ * A text reply — a plain answer, a refusal, or a **clarifying
+ * question** when the command is ambiguous. Conversation emerges only
+ * when useful; the default is a one-shot proposal.
+ */
+export type AuthorMessage = {
+    kind: "message";
+    text: string;
+};
+/**
+ * The discriminated result of {@link author}: exactly one
+ * {@link AuthorProposal} or {@link AuthorMessage}. Discriminate on
+ * `kind`. This is a plain value — serialize it over whatever transport
+ * you run (a JSON response, a queue message, an in-process return); the
+ * library pins no wire format.
+ */
+export type AuthorEvent = AuthorProposal | AuthorMessage;
+/**
+ * A streamed authoring event (see {@link authorStream}). Assistant text
+ * arrives incrementally as `text-delta`s; the stream ends with exactly one
+ * terminal `proposal`, `message`, or `error`. The terminal `message.text` is
+ * the full, authoritative text (a client that rendered the deltas can ignore
+ * it or use it to reconcile). A mid-stream failure is a terminal `error`.
+ *
+ * Discriminate on `kind` — the same key as {@link AuthorEvent}. These are
+ * plain values: frame them over SSE, a WebSocket, or an in-process async
+ * iterator as you see fit. The library pins no wire format.
+ */
+export type AuthorStreamEvent = {
+    kind: "text-delta";
+    delta: string;
+} | {
+    kind: "proposal";
+    graph: AuthoredGraph;
+    summary: string;
+} | {
+    kind: "message";
+    text: string;
+} | {
+    kind: "error";
+    error: string;
+};

package/dist/contract.js

@@ -0,0 +1,14 @@
+/**
+ * The shapes `author()` / `authorStream()` return.
+ *
+ * Stateless: every request is self-contained. The workflow graph IS
+ * the state, so there is no session store. Optional continuity is
+ * carried by the CALLER via {@link AuthorRequest.context} — the library
+ * never persists anything across requests.
+ *
+ * These are plain data shapes, not a wire format. YOU choose the
+ * transport: return an {@link AuthorEvent} as a JSON response, push
+ * {@link AuthorStreamEvent}s over SSE / WebSocket, or consume them
+ * in-process. The library ships no HTTP server.
+ */
+export {};