@flowget/ai 0.1.0

package/LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 Flowget
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/README.md

@@ -0,0 +1,238 @@
+# @flowget/ai
+
+**Request-first, stateless AI workflow-authoring primitives** for [Flowget](https://flowget.io).
+
+Send a natural-language command → get a schema-valid workflow graph back. `author(config, request)` owns the catalog, the LLM, toolsets, guardrail, authorizers, and validation. 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).
+
+**Stateless by design.** The workflow graph IS the state, so there is no session store — every request is self-contained. Optional continuity is carried by the _client_ via `context`. A chat is a thin, optional layer on the same primitive.
+
+```
+command + currentGraph? + actor?  →  { kind: "proposal", graph, summary } | { kind: "message", text }
+```
+
+- `proposal` — a workflow graph to preview / apply. Node positions are optional (the builder lays it out).
+- `message` — a text reply, including a **clarifying question** when the command is ambiguous.
+
+> ⚠️ **A proposal is model-authored — untrusted until approved.** Validation gates *runnability* (schema, known node types, resolvable refs), NOT field *values*: a malicious or mistaken value (e.g. an exfiltrating URL in an `http_request` node) passes. Never auto-apply a proposal without human review and/or a downstream field-value policy check. Treat `summary` (and any `message.text`) as untrusted model output — output-encode before rendering.
+
+## Install
+
+```bash
+npm install @flowget/ai
+# or: pnpm add @flowget/ai · yarn add @flowget/ai · bun add @flowget/ai
+```
+
+Developed with Bun internally; consumers can use any package manager and any Node-compatible runtime.
+
+## 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! }, // or a pre-loaded NodeMetadata[]
+});
+
+const event = await author(config, {
+  command: "When a webhook fires, email ops with the order payload",
+});
+
+if (event.kind === "proposal") {
+  console.log(event.summary, event.graph); // a workflow graph authored from YOUR registry
+} else {
+  console.log(event.text); // a clarifying question or a plain reply
+}
+```
+
+A `proposal` graph looks like:
+
+```json
+{
+  "kind": "proposal",
+  "summary": "Emails ops whenever the order webhook fires.",
+  "graph": {
+    "nodes": [
+      { "id": "trigger_1", "type": "webhook_trigger", "data": { "path": "/orders" } },
+      { "id": "email_1", "type": "send_email",
+        "data": { "to": "ops@example.com", "subject": "New order",
+                  "body": "{{ steps.trigger_1.output.payload }}" } }
+    ],
+    "edges": [{ "id": "e1", "source": "trigger_1", "target": "email_1" }]
+  }
+}
+```
+
+Point `catalog` at your own directory of node `.json` files (`{ registryDir }`) to author against your real catalog. `resolveConfig` loads the catalog; `finalizeConfig` is the sync variant when you already hold a `NodeMetadata[]`.
+
+## Configuration
+
+Every piece is a named, typed, swappable hook with a batteries-included default. Only `adapter` and `catalog` are required.
+
+| Option              | Default                                | What it does                                                            |
+| ------------------- | -------------------------------------- | ----------------------------------------------------------------------- |
+| `adapter`           | — (required)                           | The LLM. `openaiAdapter({ apiKey })` → OpenRouter, or BYO.              |
+| `catalog`           | — (required)                           | `NodeMetadata[]`, `{ registryDir }`, or `{ paths }`.                    |
+| `guardrail`         | none                                   | Pre-LLM policy gate → `allow` / `block(message)`.                       |
+| `authorizers`       | `[]`                                   | Verify the trusted actor before guardrail/toolsets.                    |
+| `toolsets`          | `[]`                                   | Actor-scoped, model-invoked tools.                                     |
+| `hooks`             | no-op                                  | `onProposal` / `onBlocked` audit sinks.                                |
+| `validator`         | AJV + catalog cross-ref + template-ref | Bounds what can become a proposal.                                     |
+| `persona`           | workflow-only persona                  | System-prompt override.                                                |
+| `model`             | adapter default                        | Model slug forwarded to the adapter.                                   |
+| `maxToolIterations` | `8`                                    | Max adapter turns per request.                                         |
+| `maxRepairAttempts` | `2`                                    | Max validate/repair retries before giving up with a `message`.        |
+
+### BYO LLM adapter
+
+The adapter is the only LLM-specific seam — one method:
+
+```ts
+import type { AiAdapter } from "@flowget/ai";
+
+const myAdapter: AiAdapter = {
+  async generate({ messages, tools }) {
+    // Call any LLM/gateway with the messages + tool definitions.
+    // Return the assistant's turn: free text and/or parsed tool calls.
+    return { text: null, toolCalls: [] };
+  },
+};
+```
+
+### Actor-scoped toolset
+
+Model-invoked tools run against your data, scoped by the `actor`. A domain miss is a **return value**; an infra fault **throws**. See [`examples/db-toolset.ts`](https://github.com/flowgethq/ai/blob/main/examples/db-toolset.ts) (in the repo — the `examples/` dir is not in the published tarball):
+
+```ts
+import type { Toolset } from "@flowget/ai";
+
+const dbToolset: Toolset = {
+  namespace: "db",
+  tools: [
+    {
+      name: "find_user",
+      description: "Look up a user by email within the caller's tenant.",
+      parameters: { type: "object", required: ["email"],
+        properties: { email: { type: "string" } } },
+      run: async (input, { actor }) => {
+        const user = await db.findUser({ email: String(input.email), tenantId: actor?.tenantId });
+        return user ? { found: true, user } : { found: false };
+      },
+    },
+  ],
+};
+```
+
+> ⚠️ **`actor` is client-supplied JSON — not trusted by default.** A toolset that scopes data by `actor` (like `tenantId` above) is only safe when an **`authorizer` verifies the actor first**; otherwise a client can spoof `tenantId` and read another tenant's data. Always wire an authorizer alongside an actor-scoped toolset:
+>
+> ```ts
+> await resolveConfig({ adapter, catalog, authorizers: [verifyActor], toolsets: [dbToolset] });
+> ```
+>
+> The package is auth-agnostic — it never forces authentication — so enforcing this is your call. See `requireVerifiedTenant` in `examples/db-toolset.ts`.
+
+### Guardrail + audit hooks
+
+> ⚠️ **Bounding request inputs is a hard integration requirement.** `command`, `currentGraph`, **and** `context` are all `JSON.stringify`'d into the prompt, and `currentGraph` / `context` can be re-sent up to `maxToolIterations` (default 8) times per request. The host MUST cap the size of **all three** before calling `author` — an unbounded `currentGraph` or `context` is as much a token-DoS as a huge `command`. A guardrail is the natural place:
+
+```ts
+import { resolveConfig, author, block, inMemoryAuditSink } from "@flowget/ai";
+
+const audit = inMemoryAuditSink(); // default append-only sink
+
+// Cap EVERY prompt input, not just the command.
+const tooBig = (value: unknown, max: number) =>
+  value !== undefined && JSON.stringify(value).length > max;
+
+const config = await resolveConfig({
+  adapter, catalog,
+  guardrail: (req) =>
+    req.command.length > 2_000 ||
+    tooBig(req.currentGraph, 50_000) ||
+    tooBig(req.context, 10_000)
+      ? block("Request too large.")
+      : { action: "allow" },
+  hooks: audit, // audit.entries collects every proposal / block
+});
+const event = await author(config, { command });
+```
+
+## Testing with a mock adapter (no LLM, no network)
+
+Drive the `author` primitive with a deterministic mock and assert the `message | proposal`:
+
+```ts
+import { resolveConfig, author, mockAdapter, mockProposeWorkflow } from "@flowget/ai";
+
+const config = await resolveConfig({
+  catalog,
+  adapter: mockAdapter([
+    mockProposeWorkflow(
+      { nodes: [{ id: "t1", type: "webhook_trigger", data: {} }], edges: [] },
+      "A one-node workflow.",
+    ),
+  ]),
+});
+
+const event = await author(config, { command: "start on a webhook" });
+// event: { kind: "proposal", graph, summary }
+```
+
+## Wrapping it in a transport
+
+`author` is transport-agnostic — the graph is the state, so a request is self-contained. Wrap it in whatever you already run (an HTTP route, a queue consumer, a CLI). A minimal Fetch handler:
+
+```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! },
+});
+
+export default {
+  async fetch(req: Request): Promise<Response> {
+    const { command, currentGraph, actor, context } = await req.json();
+    const event = await author(config, { command, currentGraph, actor, context });
+    return Response.json(event);
+  },
+};
+```
+
+Self-hosted or Flowget-hosted, the primitive is the same stateless call — any infra, any runtime, any transport.
+
+### Streaming (`authorStream`)
+
+For a chat "typing" feel, `authorStream` yields `text-delta`s as the model writes, then exactly one terminal `proposal` / `message` / `error`. Discriminate on `event.kind`. Frame the events over whatever streaming transport you run — **example wiring you build; the library pins no wire format.** A minimal SSE handler:
+
+```ts
+import { resolveConfig, authorStream, openaiAdapter } from "@flowget/ai";
+
+const config = await resolveConfig({
+  adapter: openaiAdapter({ apiKey: process.env.OPENROUTER_API_KEY! }),
+  catalog: { registryDir: process.env.REGISTRY_DIR! },
+});
+
+export default {
+  async fetch(req: Request): Promise<Response> {
+    const { command, currentGraph, actor, context } = await req.json();
+    const encoder = new TextEncoder();
+    const stream = new ReadableStream({
+      async start(controller) {
+        for await (const event of authorStream(config, { command, currentGraph, actor, context })) {
+          // event.kind: "text-delta" | "proposal" | "message" | "error"
+          controller.enqueue(encoder.encode(`event: ${event.kind}\ndata: ${JSON.stringify(event)}\n\n`));
+        }
+        controller.close();
+      },
+    });
+    return new Response(stream, { headers: { "content-type": "text/event-stream" } });
+  },
+};
+```
+
+An adapter without `generateStream` still works — `authorStream` emits no deltas, just the terminal event. A mid-stream failure arrives as a terminal `{ kind: "error", error }` rather than a throw, so your `case "error"` is reachable.
+
+## License
+
+[FSL-1.1-ALv2](./LICENSE).

package/dist/adapter.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The LLM seam. Everything model-specific lives behind `AiAdapter`;
+ * the rest of the library is provider-agnostic.
+ *
+ * The adapter is a thin transport: given a running conversation plus a
+ * set of callable tool definitions, produce the assistant's next turn
+ * (free text and/or tool calls). `author` owns prompt assembly, the
+ * tool-calling loop, validation, and repair — the adapter owns only
+ * "talk to the model."
+ *
+ * **BYO is one method.** Implement `generate` against any LLM or
+ * gateway and pass it as `config.adapter`. The default `openaiAdapter`
+ * maps this onto the `openai` SDK pointed at OpenRouter. The adapter is
+ * server-side config, held in closure, and is never serialized.
+ *
+ * **Two seams, one required.** `generate` (required) returns a full
+ * turn. `generateStream` (optional) emits token deltas for the chat
+ * "typing" feel: `author` consumes `generate`; `authorStream` consumes
+ * `generateStream` when present and transparently falls back to
+ * `generate` otherwise. Both feed the SAME validate/repair/tool logic.
+ *
+ * **Security.** An adapter MUST NOT leak credentials into thrown errors
+ * or returned text — scrub provider errors before rethrowing so the
+ * `apiKey` never reaches a caller-visible message. And treat the
+ * assistant's `text` and a proposal's `summary` as UNTRUSTED model
+ * output: a caller MUST output-encode them before rendering (they can
+ * carry markup or prompt-injection payloads).
+ */
+/** A tool the model may call, described by a JSON-Schema parameter shape. */
+export type AiToolDefinition = {
+    name: string;
+    description: string;
+    /** JSON Schema for the tool's arguments object. */
+    parameters: Record<string, unknown>;
+};
+/** A tool invocation the model requested, with already-parsed arguments. */
+export type AiToolCall = {
+    /** Provider-assigned call id — echoed back on the matching tool result. */
+    id: string;
+    name: string;
+    /** Parsed JSON arguments. Adapters parse the raw string before returning. */
+    arguments: Record<string, unknown>;
+};
+/** One message in the conversation handed to the adapter. */
+export type AiMessage = {
+    role: "system";
+    content: string;
+} | {
+    role: "user";
+    content: string;
+} | {
+    role: "assistant";
+    content: string | null;
+    toolCalls?: AiToolCall[];
+} | {
+    role: "tool";
+    toolCallId: string;
+    content: string;
+};
+export type AiGenerateRequest = {
+    messages: AiMessage[];
+    /** Tools the model may call this turn. May be empty. */
+    tools: AiToolDefinition[];
+    /** Optional per-call model override; adapters fall back to their own default. */
+    model?: string;
+    /** Cooperative cancellation for the underlying HTTP call. */
+    signal?: AbortSignal;
+};
+export type AiGenerateResult = {
+    /** Assistant free-text for this turn, or `null` when it only called tools. */
+    text: string | null;
+    /** Tool calls the model requested this turn. Empty when it replied with text. */
+    toolCalls: AiToolCall[];
+};
+/**
+ * A chunk of a streamed adapter turn. Text arrives incrementally as
+ * `text-delta`s; the turn ends with exactly one `result` carrying the full
+ * text plus the resolved tool calls (args accumulated across chunks). This is
+ * the forward-compatible streaming shape referenced in this file's header —
+ * BYO adapters opt in by implementing {@link AiAdapter.generateStream}; the
+ * ones that don't keep working through `generate`.
+ */
+export type AiStreamPart = {
+    type: "text-delta";
+    delta: string;
+} | {
+    type: "result";
+    result: AiGenerateResult;
+};
+export interface AiAdapter {
+    generate(request: AiGenerateRequest): Promise<AiGenerateResult>;
+    /**
+     * Optional token-level streaming. When present, `authorStream` forwards the
+     * `text-delta`s to the caller (chat "typing" feel) and uses the terminal
+     * `result` to run the same validate/repair/tool logic as `generate`. Absent
+     * ⇒ `authorStream` transparently falls back to `generate` (no deltas).
+     */
+    generateStream?(request: AiGenerateRequest): AsyncIterable<AiStreamPart>;
+}

package/dist/adapter.js

@@ -0,0 +1,29 @@
+/**
+ * The LLM seam. Everything model-specific lives behind `AiAdapter`;
+ * the rest of the library is provider-agnostic.
+ *
+ * The adapter is a thin transport: given a running conversation plus a
+ * set of callable tool definitions, produce the assistant's next turn
+ * (free text and/or tool calls). `author` owns prompt assembly, the
+ * tool-calling loop, validation, and repair — the adapter owns only
+ * "talk to the model."
+ *
+ * **BYO is one method.** Implement `generate` against any LLM or
+ * gateway and pass it as `config.adapter`. The default `openaiAdapter`
+ * maps this onto the `openai` SDK pointed at OpenRouter. The adapter is
+ * server-side config, held in closure, and is never serialized.
+ *
+ * **Two seams, one required.** `generate` (required) returns a full
+ * turn. `generateStream` (optional) emits token deltas for the chat
+ * "typing" feel: `author` consumes `generate`; `authorStream` consumes
+ * `generateStream` when present and transparently falls back to
+ * `generate` otherwise. Both feed the SAME validate/repair/tool logic.
+ *
+ * **Security.** An adapter MUST NOT leak credentials into thrown errors
+ * or returned text — scrub provider errors before rethrowing so the
+ * `apiKey` never reaches a caller-visible message. And treat the
+ * assistant's `text` and a proposal's `summary` as UNTRUSTED model
+ * output: a caller MUST output-encode them before rendering (they can
+ * carry markup or prompt-injection payloads).
+ */
+export {};

package/dist/author.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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 type { ResolvedConfig } from "./config.js";
+import type { AuthorEvent, AuthorRequest, AuthorStreamEvent } from "./contract.js";
+export type AuthorOptions = {
+    signal?: AbortSignal;
+};
+export declare function author(config: ResolvedConfig, request: AuthorRequest, options?: AuthorOptions): Promise<AuthorEvent>;
+/**
+ * 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 declare function authorStream(config: ResolvedConfig, request: AuthorRequest, options?: AuthorOptions): AsyncGenerator<AuthorStreamEvent>;