@synergenius/flow-weaver 0.33.1 → 0.44.0

package/dist/coordinator/run-store.d.ts

@@ -0,0 +1,275 @@
+import type { ContinuationEnvelope, DurableGateKind } from '../runtime/continuation.js';
+import type { FwMockConfig } from '../built-in-nodes/mock-types.js';
+import type { ExecutionTraceEvent } from '../mcp/workflow-executor.js';
+import type { ResolveInput } from './gate-resolution.js';
+import type { RunStore } from './store.js';
+import type { RunDue } from './time.js';
+export { ParseError, AmbiguousWorkflowError, RunNotFoundError, RunNotWaitingError, BundleChangedError } from './errors.js';
+export { resolveProjectRoot, defaultRunsDir } from './runs-dir.js';
+export { createStoreEffectAdapter, createFileEffectAdapter } from './effect-receipts.js';
+/**
+ * The local durable-run coordinator.
+ *
+ * The engine returns a terminal `yielded` outcome and keeps nothing
+ * (see `docs/adr/0001-durable-gate-continuation.md`). Somebody has to hold
+ * the continuation between the yield and the resume, own run identity, vouch
+ * for the bundle, and record effect receipts. This is that somebody, for a
+ * driver in the same process: an assistant over MCP sees `{ runId, gate }`
+ * instead of a multi-kilobyte envelope, the console sees each step, and
+ * `fw serve` answers a request with a run id.
+ *
+ * Everything it keeps goes through a `RunStore` (`store.ts`): a directory
+ * under `~/.fw/runs` by default, memory in tests, a database of yours in
+ * production. While a segment runs, the run is claimed in the store, so two
+ * processes on one store never drive the same run at once.
+ *
+ * This module holds the public shapes and puts the coordinator together.
+ * What each operation decides lives beside it: `run-context.ts` (the store
+ * and the claim), `workflow-selection.ts` (which workflow a run is of),
+ * `run-start.ts` and `run-resume.ts` (driving a segment), `run-outcome.ts`
+ * (writing down how it ended), `run-trace.ts` (the kept step trace),
+ * `run-ending.ts` (cancel and remove), `run-annotations.ts` (agent notes
+ * and kept documents), `clock-tick.ts` (the clock), `run-views.ts` (what a
+ * driver is shown), `effect-receipts.ts`, `runs-dir.ts` and `errors.ts`.
+ */
+export interface StartRequest {
+    filePath: string;
+    workflowName?: string;
+    params?: Record<string, unknown>;
+    /**
+     * Answers for the built-in gates and calls (`waitForEvent`, `waitForAgent`,
+     * `invokeWorkflow`, `delay`), so a run can go through them unattended.
+     * Kept with the record, so a later segment is mocked the same way.
+     */
+    mocks?: FwMockConfig;
+    /** Where the file stood when the run started -- a commit, and whether it had uncommitted changes -- as the driver knows it. */
+    source?: {
+        commit?: string;
+        dirty?: boolean;
+    };
+    /**
+     * The run's identity, when the driver needs it before the run ends. The
+     * console answers `POST /api/runs` with the id while the run goes on in
+     * the background. An assistant over MCP waits and is told afterwards.
+     */
+    runId?: string;
+    /**
+     * Whether an agent gate may be answered by a configured agent profile
+     * (`auto`, the default) or must wait for a person (`manual`). Kept with
+     * the record so every later gate of the run is treated the same way.
+     */
+    agents?: 'auto' | 'manual';
+    /** Who started the run -- `console`, `http`, `mcp`, or a name of the driver's own -- for a list to say so. */
+    origin?: string;
+}
+/**
+ * What an agent profile did about the run's latest agent gate. Written by
+ * the driver before the model is called and again when it is done, so a
+ * reader opening the run sees an answer in progress, one that was given, or
+ * why one was not.
+ */
+export interface AgentNote {
+    gateId: string;
+    node: string;
+    profile: string;
+    provider: string;
+    model?: string;
+    status: 'answering' | 'answered' | 'rejected' | 'failed';
+    startedAt: string;
+    endedAt?: string;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        costUsd?: number;
+    };
+    toolCalls?: number;
+    /** Why it failed, or the reason it gave for rejecting. */
+    error?: string;
+    /** The process doing the answering, so a crash mid-answer can be told from an answer in progress. */
+    owner?: {
+        pid: number;
+        host: string;
+    };
+}
+/** One entry of a kept step trace: the event and when it happened. */
+export interface TraceEntry {
+    t: number;
+    e: unknown;
+}
+/**
+ * How a driver watches a run it is driving.
+ *
+ * An assistant over MCP wants none of this: fewer tokens is the point. A
+ * person at the console wants all of it: each step as it runs, and the
+ * same trace again when the run is opened tomorrow.
+ */
+export interface DriveOptions {
+    /** Every trace event as it happens. Implies `trace`. */
+    onEvent?: (event: ExecutionTraceEvent) => void;
+    /** Keep the step trace beside the record, so a later reader has it too. */
+    trace?: boolean;
+    /** Cooperative cancellation. A run stopped this way is recorded as `cancelled`. */
+    abortSignal?: AbortSignal;
+}
+export interface ResumeRequest {
+    runId: string;
+    input: ResolveInput;
+}
+/** What a driver is shown. Deliberately the minimum. */
+export interface RunView {
+    status: 'waiting' | 'completed' | 'failed' | 'cancelled';
+    runId: string;
+    workflowName: string;
+    gate?: {
+        kind: DurableGateKind;
+        node: string;
+        inputs: Record<string, unknown>;
+        absent: string[];
+    };
+    /** When the clock will move the run, while it waits: a sleep wakes, a gate with a timeout times out. */
+    due?: RunDue;
+    result?: unknown;
+    error?: string;
+}
+export interface RunSummary {
+    status: RunView['status'];
+    runId: string;
+    workflowName: string;
+    filePath: string;
+    gate?: {
+        kind: DurableGateKind;
+        node: string;
+    };
+    due?: RunDue;
+    /** What the run was given, so a list can tell two runs apart. */
+    params: Record<string, unknown>;
+    failedNode?: string;
+    mocks?: FwMockConfig;
+    source?: {
+        commit?: string;
+        dirty?: boolean;
+    };
+    agents?: 'auto' | 'manual';
+    /** The latest agent activity, enough for a list row. */
+    agent?: Pick<AgentNote, 'status' | 'profile' | 'node'>;
+    origin?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface LocalCoordinator {
+    start(request: StartRequest, options?: DriveOptions): Promise<RunView>;
+    resume(request: ResumeRequest, options?: DriveOptions): Promise<RunView>;
+    /**
+     * Whether `resume` would refuse this request before running anything:
+     * throws the same error it would (no such run, not waiting, the workflow
+     * changed, an answer the gate cannot take), and changes nothing. For a
+     * driver that resumes in the background and answers the caller first.
+     */
+    checkResume(request: ResumeRequest): Promise<void>;
+    /** Give up on a run waiting at a gate: the continuation is dropped and the run recorded as cancelled. */
+    cancel(runId: string): Promise<RunView>;
+    get(runId: string): Promise<RunView | undefined>;
+    list(filter?: {
+        filePath?: string;
+    }): Promise<RunSummary[]>;
+    /** Everything persisted about a run, for a driver that shows more than the minimum. */
+    record(runId: string): Promise<RunRecord | undefined>;
+    /** The kept step trace, in order across every segment. Empty when none was kept. */
+    trace(runId: string): Promise<TraceEntry[]>;
+    /** Forget a finished run: its record, trace and receipts. A waiting run must be cancelled first. */
+    remove(runId: string): Promise<void>;
+    /**
+     * Record what an agent profile is doing, or did, about the run's current
+     * gate. Takes the run's claim for the write, so it throws `RunBusyError`
+     * while a segment of the run is being driven.
+     */
+    setAgent(runId: string, note: AgentNote | undefined): Promise<RunRecord>;
+    /** Keep a named JSON document beside the run -- an agent transcript, say. The name is a plain slug. */
+    keep(runId: string, name: string, data: unknown): Promise<void>;
+    /** Read a document kept with `keep`, or undefined. */
+    kept<T = unknown>(runId: string, name: string): Promise<T | undefined>;
+    /**
+     * Let the clock act: every waiting run whose `due` time has passed is
+     * resumed -- a sleeping run woken along its success path, a gate with a
+     * timeout sent along its failure path. Safe to call from several
+     * processes at once: a run another process is driving, or already moved,
+     * is skipped. `fw serve` and the console call it every few seconds.
+     */
+    tick(now?: number): Promise<TickResult>;
+    /** The store behind it. */
+    readonly store: RunStore;
+}
+/** What one tick did. A run that could not be moved says why, in a word. */
+export interface TickResult {
+    woke: RunView[];
+    timedOut: RunView[];
+    skipped: {
+        runId: string;
+        reason: 'busy' | 'not-waiting' | 'bundle-changed' | 'failed';
+        message?: string;
+    }[];
+}
+/** Everything persisted about one run. */
+export interface RunRecord {
+    formatVersion: 1;
+    runId: string;
+    filePath: string;
+    workflowName: string;
+    params: Record<string, unknown>;
+    bundleDigest: string;
+    status: RunView['status'];
+    gate?: {
+        id: string;
+        kind: DurableGateKind;
+        node: string;
+        nodeType: string;
+        inputs: Record<string, unknown>;
+        absent: string[];
+        outputs: string[];
+        hasSuccessPort: boolean;
+        hasFailurePort: boolean;
+    };
+    /**
+     * What the run resumes from, while it waits. Kept in the record, not in a
+     * document beside it, so the single `put` that moves the run to a gate
+     * commits the gate and its continuation together. Cleared with the gate.
+     */
+    continuation?: ContinuationEnvelope;
+    /** When the clock will move the run, while it waits. Set with the gate, cleared with it. */
+    due?: RunDue;
+    result?: unknown;
+    error?: string;
+    /** The step that threw, when the trace said which. A failed run is opened there. */
+    failedNode?: string;
+    /** True when every segment kept its step trace, false when any did not. */
+    traced?: boolean;
+    /** The mocks the run was started with. Every segment uses the same. */
+    mocks?: FwMockConfig;
+    /** Where the file stood when the run started, when the driver said. */
+    source?: {
+        commit?: string;
+        dirty?: boolean;
+    };
+    /** Whether agent gates may be answered by a profile. Absent means `auto`. */
+    agents?: 'auto' | 'manual';
+    /** What an agent profile did about the latest agent gate, if one was asked. */
+    agent?: AgentNote;
+    /** Who started the run, when the driver said. */
+    origin?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface LocalCoordinatorOptions {
+    /** The store runs live in. Default: the file store under `rootDir`. */
+    store?: RunStore;
+    /** The file store's directory when no `store` is given. Default `~/.fw/runs`, or `FW_RUNS_DIR`. */
+    rootDir?: string;
+    /**
+     * How long a claim on a run lasts while a segment is driven. A segment
+     * that runs longer than this may be taken over by another process; a
+     * process that dies leaves its claim to lapse after it. Default one hour.
+     */
+    claimTtlMs?: number;
+}
+export declare function createLocalCoordinator(options?: LocalCoordinatorOptions): LocalCoordinator;
+//# sourceMappingURL=run-store.d.ts.map

package/dist/coordinator/run-trace.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The step trace a run keeps beside its record.
+ *
+ * Decides whether a segment is traced at all (only when its driver asks,
+ * since tracing needs the debug build), how its events are kept, whether
+ * the run is still traced end to end once the segment is added, and which
+ * step a failed run is opened at.
+ */
+import type { ExecutionTraceEvent } from '../mcp/workflow-executor.js';
+import type { DriveOptions, RunRecord, TraceEntry } from './run-store.js';
+import type { RunStore } from './store.js';
+/**
+ * What one segment of execution is given: the driver's observer wrapped so
+ * the events are also kept, when asked. Tracing needs the debug build of
+ * the workflow, which is where the events come from.
+ */
+export declare function observe(options: DriveOptions | undefined): {
+    kept: undefined;
+    request: {
+        includeTrace: false;
+        production: boolean;
+        onEvent?: undefined;
+    };
+} | {
+    kept: TraceEntry[];
+    request: {
+        includeTrace: true;
+        production: boolean;
+        onEvent: (event: ExecutionTraceEvent) => void;
+    };
+};
+/**
+ * Add a segment's events to the kept trace. Returns whether the run is
+ * traced end to end: one segment driven without a trace -- resumed by an
+ * assistant, say -- leaves a gap, and a reader must not fill it in.
+ */
+export declare function appendTrace(store: RunStore, record: RunRecord, kept: TraceEntry[] | undefined): Promise<boolean>;
+export declare function readTrace(store: RunStore, runId: string): Promise<TraceEntry[]>;
+/** The step whose error the trace recorded last, if it recorded one. */
+export declare function failedNodeIn(kept: TraceEntry[] | undefined): string | undefined;
+//# sourceMappingURL=run-trace.d.ts.map

package/dist/coordinator/run-views.d.ts

@@ -0,0 +1,12 @@
+/**
+ * What a driver is shown of a run.
+ *
+ * Decides how much of a record leaves the coordinator: the minimum a
+ * driver acts on (`RunView`: the gate while it waits, the result once
+ * completed, the error once failed) and the row a list shows
+ * (`RunSummary`: enough to tell two runs apart).
+ */
+import type { RunRecord, RunSummary, RunView } from './run-store.js';
+export declare function toView(record: RunRecord): RunView;
+export declare function toSummary(record: RunRecord): RunSummary;
+//# sourceMappingURL=run-views.d.ts.map

package/dist/coordinator/runs-dir.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The project a workflow file belongs to: the nearest ancestor directory with
+ * a `package.json` or an existing `.fw/` folder, or — when neither is found —
+ * the file's own directory. `anchor` may be a file or a directory.
+ *
+ * This is what makes a run store follow the file rather than the process: two
+ * processes launched from different working directories (a console, and an MCP
+ * server a tool spawned elsewhere) resolve the SAME project for the SAME file,
+ * so they share one store. The walk is case- and separator-tolerant because
+ * `path` is already platform-native; the containment the store relies on is the
+ * resolved root, not the raw string.
+ */
+export declare function resolveProjectRoot(anchor: string): string;
+/**
+ * Where a run store lives. Precedence:
+ *   1. `FW_RUNS_DIR` — an explicit override for operators pointing every
+ *      process at one store.
+ *   2. `<projectRoot>/.fw/runs` — when an anchor (a workflow file or its
+ *      directory) is given, so the store follows the file across processes.
+ *   3. `~/.fw/runs` — the legacy global fallback when there is no anchor.
+ *
+ * Passing no anchor keeps the old global behaviour, so existing callers and
+ * runs are unaffected; nothing migrates.
+ */
+export declare function defaultRunsDir(anchor?: string): string;
+//# sourceMappingURL=runs-dir.d.ts.map

package/dist/coordinator/store.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Where runs live.
+ *
+ * The coordinator keeps three kinds of thing per run: the record (what the
+ * run is, where it stands, and the continuation it resumes from while it
+ * waits), named documents beside it (its step trace, effect receipts, an
+ * agent's transcript, a callback's state), and a claim while a process is
+ * driving it. A store
+ * is anything that can hold those. The file store under `~/.fw/runs` is the
+ * default, the memory store serves tests, and a database store is yours to
+ * write against this interface, with `checkRunStore` from
+ * `@synergenius/flow-weaver/testing` says whether it holds up.
+ *
+ * Every method is asynchronous, because a real store is remote. The
+ * contract each must keep:
+ *
+ * - `put` is all or nothing: a concurrent `get` sees the old record or the
+ *   new one, never a mix. `get` returns a copy the caller may mutate.
+ * - `list` is newest first by `updatedAt`, optionally one workflow file's.
+ * - Documents are JSON values under a slug name, per run. `remove` takes
+ *   the record and every document with it.
+ * - `claim` is atomic: of two callers claiming the same run at once, one
+ *   gets `true`. The same owner may claim again. A claim lapses after its
+ *   `ttlMs`, or when `release`d by its owner. A store that can tell its
+ *   owner's process is gone may lapse it sooner.
+ */
+import type { RunRecord } from './run-store.js';
+export interface RunStore {
+    /** The record, or undefined when there is no such run. */
+    get(runId: string): Promise<RunRecord | undefined>;
+    /** Write the whole record, atomically from a reader's point of view. */
+    put(record: RunRecord): Promise<void>;
+    /** Every run's record, newest first, or only one file's when asked. */
+    list(filter?: {
+        filePath?: string;
+    }): Promise<RunRecord[]>;
+    /** Forget the run: its record, its documents, its claim. */
+    remove(runId: string): Promise<void>;
+    /** A document kept beside the run, or undefined. */
+    getDoc(runId: string, name: string): Promise<unknown | undefined>;
+    /** Write a document, atomically. A run need not have a record yet. */
+    putDoc(runId: string, name: string, data: unknown): Promise<void>;
+    /** Drop a document. Nothing happens when it is not there. */
+    deleteDoc(runId: string, name: string): Promise<void>;
+    /** Take the run for `owner` for up to `ttlMs`. False when another owner holds it. */
+    claim(runId: string, owner: string, ttlMs: number): Promise<boolean>;
+    /** Give the run back. Nothing happens when `owner` does not hold it. */
+    release(runId: string, owner: string): Promise<void>;
+}
+/** A document name: a plain slug, so a file store can use it as a file name as it is. */
+export declare const DOC_NAME: RegExp;
+/**
+ * The documents the coordinator itself keeps; `keep()` refuses these names.
+ * `continuation` is where an older version kept a waiting run's envelope;
+ * such a run still resumes from it.
+ */
+export declare const RESERVED_DOCS: readonly ["continuation", "trace", "claim", "run"];
+/** Effect receipts are documents named `effect-<sha256 of the operation key>`. */
+export declare const EFFECT_DOC_PREFIX = "effect-";
+export declare function checkDocName(name: string): void;
+/** Another process is driving this run right now. */
+export declare class RunBusyError extends Error {
+    readonly runId: string;
+    readonly name = "RunBusyError";
+    constructor(runId: string);
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/coordinator/time.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The clock, as the coordinator keeps it.
+ *
+ * The engine never runs a timer: a gate yields and the process is free to
+ * go. Two things a run may wait for are a matter of time all the same: a
+ * `sleep` node wakes when its duration has passed, and a gate given a
+ * `timeout` stops waiting and takes its failure path. The coordinator
+ * records when that is (`RunRecord.due`) and `tick()` acts on it; `fw serve`
+ * and the console tick every few seconds, `fw_runs` before it lists.
+ */
+import type { DurableGateKind } from '../runtime/continuation.js';
+import { parseDuration } from '../built-in-nodes/delay.js';
+export interface RunDue {
+    /** When the clock acts, ISO 8601. */
+    at: string;
+    /** `wake`: a sleeping run goes on. `timeout`: the gate takes its failure path. */
+    action: 'wake' | 'timeout';
+}
+/**
+ * `<number><unit>` with unit `ms`, `s`, `m`, `h` or `d`; `undefined` for
+ * anything else. The function is the `delay` node's own, so the clock reads
+ * a `sleep` duration or a gate `timeout` exactly as a compiled `delay` reads
+ * its input.
+ */
+export { parseDuration };
+/**
+ * When the clock will move a run that just paused at `gate`, if ever.
+ *
+ * A `timer` gate wakes after its `duration`. An unreadable duration wakes at
+ * once rather than never. Any other gate with a readable `timeout` input and
+ * a failure port times out along that port. A timeout on a gate with no
+ * failure port is not a deadline: there is nowhere for the run to go.
+ */
+export declare function dueFor(gate: {
+    kind: DurableGateKind;
+    inputs: Record<string, unknown>;
+    hasFailurePort: boolean;
+}, now?: number): RunDue | undefined;
+//# sourceMappingURL=time.d.ts.map

package/dist/coordinator/workflow-selection.d.ts

@@ -0,0 +1,6 @@
+import type { TWorkflowAST } from '../ast/types.js';
+export declare function parseSelected(filePath: string, requested: string | undefined): Promise<{
+    ast: TWorkflowAST;
+    workflowName: string;
+}>;
+//# sourceMappingURL=workflow-selection.d.ts.map

package/dist/deployment/index.d.ts

@@ -1,31 +1,26 @@
 /**
- * Flow Weaver Deployment System
+ * Flow Weaver Export Targets
  *
- * Unified abstractions for deploying workflows across CLI, HTTP, and serverless contexts.
+ * The base class every export target extends, the registry that holds
+ * them, and the discovery of targets from installed marketplace packs.
  *
  * @module deployment
  */
-export type { ExecutionSource, Environment, ExecutionContext, WorkflowRequest, WorkflowResponse, WorkflowError, WorkflowErrorCode, ValidationResult, ValidationError, CliInput, HttpInput, AdapterInput, } from './types.js';
-export { UnifiedWorkflowExecutor, createExecutor, type ExecutorOptions } from './core/executor.js';
-export { type RequestAdapter, CliRequestAdapter, HttpRequestAdapter, createAdapter, } from './core/adapters.js';
-export { formatCliResponse, formatHttpResponse, formatError, type CliOutputOptions, } from './core/formatters.js';
-export type { DeploymentConfig, ServerConfig, ExecutionConfig, SecretsConfig, CorsConfig, RetryConfig, PartialDeploymentConfig, CliConfigOverrides, } from './config/types.js';
-export { DEFAULT_CONFIG, DEFAULT_SERVER_CONFIG, DEFAULT_EXECUTION_CONFIG, getDefaultConfig, } from './config/defaults.js';
-export { loadConfig, loadConfigSync, getConfigValue } from './config/loader.js';
-export { OpenAPIGenerator, generateOpenAPIJson, generateOpenAPIYaml, type OpenAPIDocument, type OpenAPIInfo, type OpenAPIServer, type GeneratorOptions, } from './openapi/generator.js';
-export { SchemaConverter, schemaConverter, type OpenAPISchema, } from './openapi/schema-converter.js';
 export { type ExportTarget, type ExportOptions, type ExportArtifacts, type GeneratedFile, type DeployInstructions, type DeploySchema, type DeploySchemaField, type CompiledWorkflow, type MultiWorkflowArtifacts, type NodeTypeInfo, type NodeTypeExportOptions, type NodeTypeArtifacts, type BundleWorkflow, type BundleNodeType, type BundleArtifacts, BaseExportTarget, ExportTargetRegistry, } from './targets/base.js';
-export { generateStandaloneRuntimeModule } from '../api/inline-runtime.js';
 import { ExportTargetRegistry } from './targets/base.js';
 /**
  * Create an export target registry via marketplace discovery.
  *
- * Scans `node_modules/` for installed `flow-weaver-pack-*` packages that
- * declare `exportTargets` in their `flowweaver.manifest.json`.
+ * Scans `node_modules/` for installed packs -- any package with a
+ * `flowweaver.manifest.json` -- that declare `exportTargets` in it.
  * Each target class is eagerly imported (to resolve the async import) but
- * lazily instantiated — the constructor only runs when `registry.get()` is called.
+ * lazily instantiated. The constructor only runs when `registry.get()` is called.
  *
- * @param projectDir — project root to scan for installed packs.
+ * A target whose module does not export the declared class is skipped with
+ * a warning naming the pack and file, so one broken pack does not take the
+ * others down.
+ *
+ * @param projectDir project root to scan for installed packs.
  *   When omitted, returns an empty registry (useful for tests).
  */
 export declare function createTargetRegistry(projectDir?: string): Promise<ExportTargetRegistry>;