@synergenius/flow-weaver 0.33.1 → 0.44.0

package/dist/runtime/strict-json.d.ts

@@ -0,0 +1,15 @@
+export interface StrictJsonLimits {
+    readonly maxDepth: number;
+    readonly maxStringBytes: number;
+    readonly maxObjectKeys: number;
+    readonly maxArrayItems: number;
+    readonly maxAggregateEntries: number;
+}
+export declare function parseStrictJson(text: string, limits: StrictJsonLimits): unknown;
+export type StrictJsonErrorCode = "malformed" | "oversized";
+export declare class StrictJsonError extends Error {
+    readonly code: StrictJsonErrorCode;
+    readonly name = "StrictJsonError";
+    constructor(code: StrictJsonErrorCode, message: string);
+}
+//# sourceMappingURL=strict-json.d.ts.map

package/dist/server/access.d.ts

@@ -0,0 +1,12 @@
+import type { ServerRequest, ServerResponse } from './transport.js';
+export declare const isLoopback: (host: string) => boolean;
+/** Whether the request carries the token, compared in constant time. No token configured means every request is. */
+export declare function authorized(req: ServerRequest, token: string | undefined): boolean;
+/**
+ * CORS headers for the configured origin(s). A browser accepts one origin
+ * in the header, so with a list the request's own Origin is echoed when it
+ * is on the list, and the response varies by Origin so a cache never
+ * serves one origin's answer to another.
+ */
+export declare function cors(req: ServerRequest, res: ServerResponse, allowed: string | string[] | undefined): void;
+//# sourceMappingURL=access.d.ts.map

package/dist/server/api.d.ts

@@ -0,0 +1,126 @@
+import type { CallbackPolicy } from './callback-url.js';
+import { type RunStore } from '../coordinator/index.js';
+import type { AgentProfile } from '../agent/profiles.js';
+import type { AgentProvider } from '../agent/types.js';
+import type { THttpRoute } from '../ast/types.js';
+import type { RunResponse, WorkflowEndpoint } from './types.js';
+import { type ServerRequest, type ServerResponse } from './transport.js';
+export type { ServerRequest, ServerResponse } from './transport.js';
+export { HttpError, errorToHttp } from './http-error.js';
+export { isLoopback } from './access.js';
+export { RESERVED_PATHS, planRoutes } from './route-plan.js';
+export interface WorkflowApiOptions {
+    /** The project: its workflows, and its `.flowweaver/agents.yaml`. */
+    dir: string;
+    /** Bearer token every route but /health must carry. Unset means open. */
+    token?: string;
+    /** Answer agent gates from the project's agent profiles. Default true. */
+    agents?: boolean;
+    /** Keep a step trace per run and stream it. Default false. */
+    trace?: boolean;
+    /** Error stacks in responses; `mocks` accepted in a start body. */
+    dev?: boolean;
+    /** Where runs are stored. Default: the project's `.fw/runs` next to `dir`, the store `fw console` and `fw_run` use too. */
+    runsDir?: string;
+    /** A run store of your own -- a database, for several instances -- in place of the directory. */
+    store?: RunStore;
+    /** Re-discover workflows when files change. Default false; `fw serve` turns it on. */
+    watch?: boolean;
+    /** Also mount every workflow at `POST /workflows/<name>`, declared or not. Default true. */
+    legacyRoutes?: boolean;
+    /** CORS origin. Unset sends no CORS headers. */
+    cors?: string | string[];
+    /** The environment agent profiles read their keys from. Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Build the provider for a profile yourself -- an embedding's own client, or a test's fake. */
+    agentProvider?: (profile: AgentProfile, env: NodeJS.ProcessEnv) => AgentProvider;
+    /** How the run says where it came from; `fw serve` says `http`. */
+    origin?: string;
+    /** The largest request body read from the stream. Default 1 MiB. */
+    maxBodyBytes?: number;
+    /**
+     * Which callback URLs are delivered to. By default only public http(s)
+     * hosts. See `CallbackPolicy`. `sweepMs` is how often pending callbacks
+     * are retried and runs finished elsewhere are checked (default 3 s).
+     */
+    callbacks?: CallbackPolicy & {
+        sweepMs?: number;
+    };
+    /** Called on every state change of a run this API drives: started, waiting, completed, failed, cancelled. For your logs and metrics. */
+    onRun?: (run: RunResponse) => void;
+    /** Called after each callback delivery attempt. */
+    onCallback?: (outcome: {
+        runId: string;
+        url: string;
+        ok: boolean;
+        status?: number;
+        error?: string;
+        attempt: number;
+        gaveUp?: boolean;
+    }) => void;
+    /**
+     * How many segments started by requests may run at once. Past it a start
+     * or a resolve answers 503 with Retry-After. Default 32. Agent answers
+     * and callbacks are not counted.
+     */
+    maxInFlight?: number;
+    /**
+     * The longest a request waits for its segment before answering 202 with
+     * the run to follow, so a proxy never cuts a slow workflow's response.
+     * `Prefer: wait=<seconds>` asks for less. Default 60 s.
+     */
+    maxWaitMs?: number;
+    /** Serve Swagger UI at /docs and make it and /openapi.json readable without the token. Default false. */
+    docs?: boolean;
+}
+/** One declared route, as `routes()` reports it. */
+export interface RouteInfo {
+    method: THttpRoute['method'];
+    path: string;
+    workflow: string;
+    file: string;
+    mode: 'sync' | 'async';
+    auth: 'bearer' | 'none';
+    callback: boolean;
+    gates: number;
+}
+export interface WorkflowApi {
+    /** Discovery done, so it is safe to serve. Called for you by the adapters. */
+    ready(): Promise<void>;
+    /**
+     * Handle a request if it is ours. `basePath` is the mount prefix, for the
+     * links in responses; `body` is a body your framework already parsed
+     * (Fastify's `request.body`, say), used instead of reading the stream.
+     */
+    handle(req: ServerRequest, res: ServerResponse, opts?: {
+        basePath?: string;
+        body?: unknown;
+    }): Promise<boolean>;
+    /** Deliver every pending callback now, instead of waiting for the next sweep. Ticks the clock first. */
+    deliverCallbacks(): Promise<void>;
+    /** Let the clock act now: wake the runs whose sleep is over, time out the gates whose timeout has passed. */
+    tick(): Promise<void>;
+    /** A Node request listener that answers 404 for anything that is not ours. */
+    node(): (req: ServerRequest, res: ServerResponse) => void;
+    /** Express-style middleware: handles what is ours, calls `next()` for the rest. */
+    express(): (req: ServerRequest & {
+        baseUrl?: string;
+    }, res: ServerResponse, next: (err?: unknown) => void) => void;
+    /** A fetch-style handler for hosts that speak Request and Response. */
+    fetch(request: Request, opts?: {
+        basePath?: string;
+    }): Promise<Response>;
+    /** The OpenAPI document. */
+    openapi(serverUrl?: string): object;
+    /** The declared routes, and what was refused. */
+    routes(): {
+        routes: RouteInfo[];
+        problems: string[];
+    };
+    /** Every endpoint the registry found. */
+    endpoints(): WorkflowEndpoint[];
+    /** Stop watching, end streams, stop what is in flight. */
+    close(): Promise<void>;
+}
+export declare function createWorkflowApi(options: WorkflowApiOptions): WorkflowApi;
+//# sourceMappingURL=api.d.ts.map

package/dist/server/callback-delivery.d.ts

@@ -0,0 +1,62 @@
+import type { LocalCoordinator } from '../coordinator/index.js';
+import { type CallbackPolicy } from './callback-url.js';
+type Json = Record<string, unknown>;
+/** What a declared-route start remembers beside the run: the route, and the callback with its delivery state. */
+export interface HttpNote {
+    route: {
+        method: string;
+        path: string;
+    };
+    callbackUrl?: string;
+    /** When the callback was accepted. */
+    delivered?: string;
+    /** Attempts so far, and when the next may be made. */
+    attempts?: number;
+    nextAt?: string;
+    lastError?: string;
+    /** Set when every attempt failed; nothing more is tried. */
+    gaveUp?: string;
+}
+/** Delay before each retry of a callback. After the last, delivery gives up and records why. */
+export declare const CALLBACK_BACKOFF_MS: number[];
+export interface CallbackOutcome {
+    runId: string;
+    url: string;
+    ok: boolean;
+    status?: number;
+    error?: string;
+    attempt: number;
+    gaveUp?: boolean;
+}
+export interface CallbackDeliveryOptions {
+    coordinator: LocalCoordinator;
+    /** Which URLs may receive callbacks; checked again at every attempt. */
+    policy?: CallbackPolicy;
+    /** Signs each body with an HMAC when set. */
+    token?: string;
+    /** Whether this process is driving the run right now; its callback waits for the segment to end. */
+    inFlight: (runId: string) => boolean;
+    /** A completed run's output ports, without the control ports, and whether it took its failure path. */
+    outputs: (result: unknown) => {
+        data: Json;
+        failed: boolean;
+    };
+    /** Called after each attempt. */
+    onCallback?: (outcome: CallbackOutcome) => void;
+    /** The clock, for tests. */
+    now?: () => number;
+}
+export type CallbackDelivery = ReturnType<typeof createCallbackDelivery>;
+export declare function createCallbackDelivery(opts: CallbackDeliveryOptions): {
+    deliver: (id: string) => Promise<void>;
+    /** A run now owes a callback: remember it, and try at once. */
+    owe(id: string): void;
+    /** Find the runs of these workflows that still owe a callback, as when the API starts. */
+    scan(workflowNames: ReadonlySet<string>): Promise<void>;
+    /** Try every callback still owed. */
+    deliverPending(): Promise<void>;
+    /** The runs still owing a callback. */
+    pending: () => readonly string[];
+};
+export {};
+//# sourceMappingURL=callback-delivery.d.ts.map

package/dist/server/callback-url.d.ts

@@ -0,0 +1,44 @@
+export interface CallbackPolicy {
+    /** Allow loopback, private and link-local addresses. For development. */
+    allowPrivate?: boolean;
+    /** Hosts that may receive callbacks (`example.com`, `*.internal.example.com`). Anything else is refused. */
+    hosts?: string[];
+    /** Your own rule. A string is the reason for refusing. */
+    allow?: (url: URL) => boolean | string;
+}
+/** Whether an IP is one that should not be reached from a public server. */
+export declare function isPrivateAddress(ip: string): boolean;
+/** Resolves a host name to its addresses; the system resolver unless a test hands in its own. */
+export type Resolve = (host: string) => Promise<Array<{
+    address: string;
+    family: number;
+}>>;
+/** Where a callback is posted: the URL, and the one address it connects to. */
+export interface CallbackTarget {
+    url: URL;
+    address: string;
+    family: number;
+}
+/**
+ * The reason a callback URL is refused, or undefined when it may be used.
+ * Checked when a run is accepted; delivery checks again with
+ * `callbackTarget`. A host named by the policy is not looked up here.
+ */
+export declare function refuseCallbackUrl(raw: string, policy?: CallbackPolicy, resolve?: Resolve): Promise<string | undefined>;
+/**
+ * Where to deliver a callback now: the URL checked again, its host resolved
+ * once, and every address checked. The post then connects to the address
+ * returned here, so a name that has since been pointed at a private
+ * address (DNS rebinding) is refused rather than fetched.
+ */
+export declare function callbackTarget(raw: string, policy?: CallbackPolicy, resolve?: Resolve): Promise<CallbackTarget | {
+    refused: string;
+}>;
+/**
+ * POST a callback to the target's address, naming the URL's host in the
+ * Host header and, over https, in the certificate check. Redirects are not
+ * followed. Resolves with the status; rejects on a network error or when
+ * `timeoutMs` passes.
+ */
+export declare function postCallback(target: CallbackTarget, headers: Record<string, string>, body: string, timeoutMs: number): Promise<number>;
+//# sourceMappingURL=callback-url.d.ts.map

package/dist/server/context.d.ts

@@ -0,0 +1,35 @@
+/**
+ * What the API's route handlers share: the settings they read, the registry
+ * and the run store, the run driver, and the declared routes mounted now.
+ */
+import type { LocalCoordinator } from '../coordinator/index.js';
+import type { CallbackPolicy } from './callback-url.js';
+import type { CompiledRoute } from './route-plan.js';
+import type { RunDriver } from './run-driver.js';
+import type { WorkflowRegistry } from './workflow-registry.js';
+export interface ApiContext {
+    registry: WorkflowRegistry;
+    coordinator: LocalCoordinator;
+    runs: RunDriver;
+    /** Bearer token; unset means open. */
+    token?: string;
+    /** Error stacks in responses; `mocks` accepted in a start body. */
+    dev?: boolean;
+    /** Swagger UI at /docs, and /docs and /openapi.json readable without the token. */
+    docs?: boolean;
+    /** Every workflow also at `POST /workflows/<name>`. */
+    legacy: boolean;
+    /** Agent gates answered from the profiles. */
+    agents: boolean;
+    maxBody: number;
+    maxWait: number;
+    callbackPolicy?: CallbackPolicy;
+    /** The declared routes mounted now, and what was refused. Changes when the registry re-discovers. */
+    mounted(): {
+        compiled: CompiledRoute[];
+        problems: string[];
+    };
+    /** The OpenAPI document, with links under `base`. */
+    openapi(serverUrl: string | undefined, base: string): object;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/server/http-error.d.ts

@@ -0,0 +1,10 @@
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: unknown | undefined;
+    readonly headers?: Record<string, string> | undefined;
+    constructor(status: number, code: string, message: string, details?: unknown | undefined, headers?: Record<string, string> | undefined);
+}
+/** The status and code a coordinator refusal maps to. */
+export declare function errorToHttp(err: unknown): HttpError;
+//# sourceMappingURL=http-error.d.ts.map

package/dist/server/index.d.ts

@@ -2,6 +2,12 @@
  * Server module exports
  */
 export { WebhookServer } from './webhook-server.js';
+export { createWorkflowApi, planRoutes, RESERVED_PATHS, HttpError, errorToHttp, isLoopback } from './api.js';
+export type { WorkflowApi, WorkflowApiOptions, RouteInfo, ServerRequest, ServerResponse } from './api.js';
+export { refuseCallbackUrl, isPrivateAddress } from './callback-url.js';
+export type { CallbackPolicy } from './callback-url.js';
+export { buildOpenApi } from './openapi.js';
+export type { OpenApiInput } from './openapi.js';
 export { WorkflowRegistry } from './workflow-registry.js';
-export type { WebhookServerConfig, WorkflowEndpoint, ExecutionResult, HealthResponse, WorkflowListResponse, } from './types.js';
+export type { WebhookServerConfig, WorkflowEndpoint, ExecutionResult, HealthResponse, WorkflowListResponse, RunResponse, ErrorBody, ErrorDetail, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/server/index.js

@@ -1,6 +1,125 @@
-/**
- * Server module exports
- */
-export { WebhookServer } from './webhook-server.js';
-export { WorkflowRegistry } from './workflow-registry.js';
-//# sourceMappingURL=index.js.map
+import {
+  HttpError,
+  RESERVED_PATHS,
+  WorkflowRegistry,
+  buildOpenApi,
+  createWorkflowApi,
+  errorToHttp,
+  isLoopback,
+  isPrivateAddress,
+  planRoutes,
+  refuseCallbackUrl
+} from "../chunks/chunk-PEZCT37T.js";
+import "../chunks/chunk-OZQAW5ZG.js";
+import "../chunks/chunk-VO4QXG2X.js";
+import "../chunks/chunk-JQTF4R5L.js";
+import "../chunks/chunk-Q6MDDZMT.js";
+import "../chunks/chunk-OOQG7UPP.js";
+import "../chunks/chunk-6PNJORFL.js";
+import "../chunks/chunk-F3RTZV2A.js";
+import "../chunks/chunk-YSPBPZDV.js";
+import "../chunks/chunk-QJDAVSNY.js";
+import "../chunks/chunk-DCMGQP5V.js";
+import "../chunks/chunk-DIAA66GL.js";
+import "../chunks/chunk-6KMVP6AU.js";
+import "../chunks/chunk-TAIUWKZB.js";
+import "../chunks/chunk-INDEVYEC.js";
+import "../chunks/chunk-KU3CLJI2.js";
+import "../chunks/chunk-5Y3AIUWY.js";
+import "../chunks/chunk-CZBCCK4Y.js";
+import "../chunks/chunk-AXNQRVJB.js";
+import "../chunks/chunk-O2U2LO57.js";
+import "../chunks/chunk-QDE4Z7KW.js";
+import "../chunks/chunk-P2CVDGHR.js";
+import "../chunks/chunk-ZMGN6F3S.js";
+import "../chunks/chunk-REEYC73I.js";
+import "../chunks/chunk-4EUSHAY6.js";
+import "../chunks/chunk-4KDUEOFD.js";
+import "../chunks/chunk-DUO6H5PR.js";
+import "../chunks/chunk-VP2P3BPA.js";
+import "../chunks/chunk-B6HQ6YS5.js";
+import "../chunks/chunk-E5WN7IGO.js";
+import "../chunks/chunk-KMWCCOUJ.js";
+import "../chunks/chunk-QYPORSLO.js";
+import "../chunks/chunk-R4QGNK34.js";
+import "../chunks/chunk-SEWDMQ6Q.js";
+
+// src/server/webhook-server.ts
+import * as http from "node:http";
+var WebhookServer = class {
+  server = null;
+  api;
+  config;
+  /** Where the server is listening, once it is. */
+  url = "";
+  constructor(config) {
+    this.config = config;
+    this.api = createWorkflowApi({
+      dir: config.workflowDir,
+      token: config.token,
+      agents: config.agents,
+      trace: config.trace,
+      dev: config.dev,
+      runsDir: config.runsDir,
+      store: config.store,
+      watch: config.watchEnabled,
+      legacyRoutes: config.legacyRoutes,
+      cors: config.corsOrigin,
+      env: config.env,
+      agentProvider: config.agentProvider,
+      origin: "http",
+      callbacks: config.callbacks,
+      maxBodyBytes: config.maxBodyBytes,
+      maxInFlight: config.maxInFlight,
+      maxWaitMs: config.maxWaitMs,
+      docs: config.swaggerEnabled,
+      onRun: config.onRun,
+      onCallback: config.onCallback
+    });
+  }
+  /** Start listening. `port: 0` picks a free one; `url` says which. */
+  async start() {
+    await this.api.ready();
+    this.server = http.createServer(this.api.node());
+    await new Promise((resolve, reject) => {
+      this.server.once("error", reject);
+      this.server.listen(this.config.port, this.config.host, () => {
+        this.server.off("error", reject);
+        resolve();
+      });
+    });
+    const addr = this.server.address();
+    const port = typeof addr === "object" && addr ? addr.port : this.config.port;
+    const host = this.config.host === "0.0.0.0" || this.config.host === "::" ? "127.0.0.1" : this.config.host;
+    this.url = `http://${host.includes(":") ? `[${host}]` : host}:${port}`;
+  }
+  /** Stop listening, end every stream, and stop what is in flight. */
+  async stop() {
+    await this.api.close();
+    if (this.server) {
+      const s = this.server;
+      this.server = null;
+      s.closeAllConnections?.();
+      await new Promise((resolve) => s.close(() => resolve()));
+    }
+  }
+  getServerInfo() {
+    return { port: this.config.port, host: this.config.host, endpoints: this.api.endpoints().length, routes: this.api.routes().routes.length, url: this.url };
+  }
+  buildOpenApiSpec() {
+    return this.api.openapi(this.url || void 0);
+  }
+};
+export {
+  HttpError,
+  RESERVED_PATHS,
+  WebhookServer,
+  WorkflowRegistry,
+  buildOpenApi,
+  createWorkflowApi,
+  errorToHttp,
+  isLoopback,
+  isPrivateAddress,
+  planRoutes,
+  refuseCallbackUrl
+};

package/dist/server/openapi-document.d.ts

@@ -0,0 +1,33 @@
+export interface OpenApiDocumentOptions {
+    /** API title. Default "Flow Weaver API". */
+    title?: string;
+    /** API version. Default: the Flow Weaver version. */
+    version?: string;
+    /** API description. Default: a count of endpoints and workflows. */
+    description?: string;
+    /** The server's URL, when known. */
+    serverUrl?: string;
+    /** Describe the bearer scheme, as a server with a token has. Default true. */
+    auth?: boolean;
+    /** Include `POST /workflows/<name>` for every workflow. Default true. */
+    legacy?: boolean;
+}
+export interface OpenApiDocument {
+    /** The document, ready for `formatOpenApi` or `JSON.stringify`. */
+    doc: Record<string, unknown>;
+    /** Every workflow found in the directory. */
+    workflowCount: number;
+    /** The declared `@http` routes that were mounted. */
+    routeCount: number;
+    /** The declared routes that could not be mounted, and why. */
+    problems: string[];
+}
+/**
+ * Discover the workflows under `workflowDir` and build their OpenAPI
+ * document. A directory with no workflows gives a document with only the
+ * run and meta endpoints; the caller decides whether that is an error.
+ */
+export declare function openApiForDirectory(workflowDir: string, options?: OpenApiDocumentOptions): Promise<OpenApiDocument>;
+/** The document as text: YAML, or pretty-printed JSON. */
+export declare function formatOpenApi(doc: Record<string, unknown>, format: 'json' | 'yaml'): string;
+//# sourceMappingURL=openapi-document.d.ts.map

package/dist/server/openapi.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The OpenAPI document for a set of workflows: their declared `@http`
+ * routes, the run resource each has, and the run endpoints. `fw serve`
+ * publishes it at `/openapi.json`; `fw openapi` writes the same document
+ * to a file, so the two never disagree.
+ */
+import type { THttpRoute } from '../ast/types.js';
+import type { WorkflowEndpoint } from './types.js';
+export interface OpenApiInput {
+    /** Every workflow found. */
+    endpoints: WorkflowEndpoint[];
+    /** The declared routes that were mounted, with the parameters each path binds. */
+    mounted: Array<{
+        endpoint: WorkflowEndpoint;
+        route: THttpRoute;
+        keys: string[];
+    }>;
+    /** Whether `POST /workflows/<name>` exists for every workflow. */
+    legacy: boolean;
+    /** Whether a bearer token guards the API. */
+    secured: boolean;
+    /** The server's URL, when known; `base` is the mount path under it. */
+    serverUrl?: string;
+    base?: string;
+    info?: {
+        title?: string;
+        version?: string;
+        description?: string;
+    };
+}
+export declare function buildOpenApi(input: OpenApiInput): Record<string, unknown>;
+//# sourceMappingURL=openapi.d.ts.map

package/dist/server/respond.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Reading the API's requests and writing its answers: a request header, the
+ * body as an object (JSON or a form post, up to the size limit, or what a
+ * framework already parsed), a path segment decoded, whether the caller asked
+ * for an answer at once and how long it will wait, and JSON or HTML written
+ * back.
+ */
+import type { ServerRequest, ServerResponse } from './transport.js';
+export type Json = Record<string, unknown>;
+export declare function header(req: ServerRequest, name: string): string | undefined;
+export declare function json(res: ServerResponse, status: number, body: unknown, extra?: Record<string, string>): void;
+export declare function html(res: ServerResponse, body: string): void;
+/** A path segment decoded, or 400 when the percent-encoding is malformed. */
+export declare function decodeSegment(raw: string): string;
+/**
+ * The request body. A body the framework already parsed is used as is --
+ * the stream cannot be read twice, and `express.json()` will have read
+ * it. Otherwise the stream, up to the size limit. `form` says the values
+ * are strings from a form post, to be read by the parameters' types.
+ */
+export declare function readBody(req: ServerRequest, given: unknown, maxBody: number): Promise<{
+    body: Json;
+    form: boolean;
+}>;
+/** Whether the caller asked for 202 at once: `?async`, or `Prefer: respond-async`. */
+export declare function wantsAsync(req: ServerRequest, url: URL): boolean;
+/** How long this request is willing to wait: `Prefer: wait=<seconds>`, never more than the server's limit. */
+export declare function waitBudget(req: ServerRequest, maxWait: number): number;
+/**
+ * Wait for the segment, but not past the budget. True when it settled in
+ * time (a rejection is rethrown by the caller's own await); false when
+ * the request should answer 202 and let the run go on without it.
+ */
+export declare function settledWithin(segment: Promise<unknown>, ms: number): Promise<boolean>;
+//# sourceMappingURL=respond.d.ts.map

package/dist/server/route-params.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The parameters a declared route hands its workflow: the path segments,
+ * then the query string (GET, DELETE) or the body, each read as the type
+ * the workflow's params schema declares. A missing or mistyped parameter is
+ * refused with 400 and the field it was about. `callbackUrl` and, in dev,
+ * `mocks` are taken out of the body rather than passed on.
+ */
+import type { FwMockConfig } from '../built-in-nodes/mock-types.js';
+import { type Json } from './respond.js';
+import type { CompiledRoute } from './route-plan.js';
+/** Parameters for a declared route: the path, then the query or the body, coerced by the params schema. */
+export declare function paramsFor(c: CompiledRoute, m: RegExpMatchArray, url: URL, body: Json, form: boolean, dev: boolean | undefined): {
+    params: Json;
+    callbackUrl?: string;
+    mocks?: FwMockConfig;
+};
+//# sourceMappingURL=route-params.d.ts.map

package/dist/server/route-plan.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Which declared `@http` routes are mounted, and how a request path finds
+ * one. The API keeps a few paths for itself; a route under one of them, or
+ * a method and path two workflows both declare, is refused with a reason.
+ * What is mounted is compiled to a matcher that binds the `:name` segments.
+ */
+import type { THttpRoute } from '../ast/types.js';
+import type { WorkflowEndpoint } from './types.js';
+/** Paths the API keeps for itself. A declared route under one is refused. */
+export declare const RESERVED_PATHS: string[];
+/** Whether a path is one of the API's own, or under one. */
+export declare const isReserved: (p: string) => boolean;
+/**
+ * Which declared routes can be mounted together, and why the rest cannot:
+ * a route under a reserved path, or the same method and path declared by
+ * two workflows. The console asks this of the whole project. The API asks
+ * it of what the registry found.
+ */
+export declare function planRoutes<T extends {
+    name: string;
+    routes: THttpRoute[];
+}>(list: T[]): {
+    mounted: Array<{
+        owner: T;
+        route: THttpRoute;
+    }>;
+    problems: string[];
+};
+/** A mounted route: whose it is, what it declares, and the matcher for its path with the names it binds. */
+export interface CompiledRoute {
+    endpoint: WorkflowEndpoint;
+    route: THttpRoute;
+    regex: RegExp;
+    keys: string[];
+}
+/** The routes the registry's endpoints declare, planned and compiled, with what was refused. */
+export declare function mountRoutes(endpoints: WorkflowEndpoint[]): {
+    compiled: CompiledRoute[];
+    problems: string[];
+};
+//# sourceMappingURL=route-plan.d.ts.map

package/dist/server/routes-catalog.d.ts

@@ -0,0 +1,5 @@
+import type { ApiContext } from './context.js';
+import type { ServerRequest, ServerResponse } from './transport.js';
+/** Answer a request for the API's own description. False when the path is not one. */
+export declare function serveCatalog(ctx: ApiContext, req: ServerRequest, res: ServerResponse, method: string, p: string, url: URL, base: string, given?: unknown): Promise<boolean>;
+//# sourceMappingURL=routes-catalog.d.ts.map

package/dist/server/routes-declared.d.ts

@@ -0,0 +1,12 @@
+import type { ApiContext } from './context.js';
+import type { CompiledRoute } from './route-plan.js';
+import type { ServerRequest, ServerResponse } from './transport.js';
+/**
+ * Answer in the declared shape from the run's state: the data ports with
+ * 200 or 422, the error with 500, or 202 with the run and a Location to
+ * poll -- `/runs/:id/result`, which answers in this same shape, so a
+ * client sees one shape from its first request to the final answer.
+ */
+export declare function answerDeclared(ctx: ApiContext, res: ServerResponse, id: string, base: string, replayed: boolean, executionTime?: number): Promise<void>;
+export declare function declaredRoute(ctx: ApiContext, req: ServerRequest, res: ServerResponse, c: CompiledRoute, m: RegExpMatchArray, url: URL, base: string, given?: unknown): Promise<void>;
+//# sourceMappingURL=routes-declared.d.ts.map

package/dist/server/routes-runs.d.ts

@@ -0,0 +1,8 @@
+import type { ApiContext } from './context.js';
+import type { ServerRequest, ServerResponse } from './transport.js';
+import type { WorkflowEndpoint } from './types.js';
+/** `POST /workflows/:name`: the body is the params, or `{ params, mocks }`; the answer is the run resource. */
+export declare function legacyStart(ctx: ApiContext, req: ServerRequest, res: ServerResponse, endpoint: WorkflowEndpoint, url: URL, base: string, given?: unknown): Promise<void>;
+/** Answer a request under `/runs`. False when the path is not a run resource. */
+export declare function serveRuns(ctx: ApiContext, req: ServerRequest, res: ServerResponse, method: string, p: string, url: URL, base: string, given?: unknown): Promise<boolean>;
+//# sourceMappingURL=routes-runs.d.ts.map