@synergenius/flow-weaver 0.33.1 → 0.44.0

package/dist/coordinator/agent-gate.d.ts

@@ -0,0 +1,107 @@
+import type { LocalCoordinator, RunRecord, RunView, DriveOptions, AgentNote } from './run-store.js';
+import { type AgentProfile, type AgentProfiles } from '../agent/profiles.js';
+import { type AgentGateEvent, type FieldSchema, type GateOutcome, type GateUsage } from '../agent/gate.js';
+import type { AgentMessage, AgentProvider } from '../agent/types.js';
+export interface AgentGateOptions {
+    /** Where `.flowweaver/agents.yaml` is looked for, and the CLI provider's working directory. */
+    projectDir: string;
+    env?: NodeJS.ProcessEnv;
+    /** Already-loaded profiles, when the caller caches them. */
+    profiles?: AgentProfiles;
+    /** The shape of the gate's outputs, when the caller can derive it from the workflow's types. */
+    outputSchema?: (record: RunRecord) => Promise<{
+        schema: Record<string, FieldSchema> | null;
+        types?: Record<string, string>;
+    } | undefined> | {
+        schema: Record<string, FieldSchema> | null;
+        types?: Record<string, string>;
+    } | undefined;
+    /** The workflow's description, for the model's frame. */
+    workflowDescription?: (record: RunRecord) => string | undefined;
+    onEvent?: (event: AgentGateEvent) => void;
+    signal?: AbortSignal;
+    /** Build the provider yourself -- a test's fake, say -- instead of from the profile. */
+    provider?: (profile: AgentProfile, env: NodeJS.ProcessEnv) => AgentProvider;
+}
+export type AgentGateStep = {
+    kind: 'skip';
+    why: 'not-waiting' | 'not-agent' | 'manual' | 'no-profile' | 'already-answering';
+} | {
+    kind: 'not-ready';
+    profile: string;
+    reason: string;
+    note: AgentNote;
+} | {
+    kind: 'answer';
+    profile: string;
+    answer: unknown;
+    note: AgentNote;
+} | {
+    kind: 'reject';
+    profile: string;
+    reason: string;
+    note: AgentNote;
+} | {
+    kind: 'failed';
+    profile: string;
+    error: string;
+    note: AgentNote;
+};
+/** What is kept beside the run for one answered gate. */
+export interface AgentTranscript {
+    gateId: string;
+    node: string;
+    profile: string;
+    provider: string;
+    model?: string;
+    startedAt: string;
+    endedAt: string;
+    ms: number;
+    outcome: GateOutcome;
+    usage: GateUsage;
+    toolCalls: number;
+    text: string;
+    messages: AgentMessage[];
+}
+/** The document name a gate's transcript is kept under. */
+export declare function transcriptName(gateId: string): string;
+/**
+ * Whether the process that was answering is gone. On this host the pid is
+ * probed; a note from another host, or one written before owners were
+ * recorded, is trusted for an hour and then presumed abandoned.
+ */
+export declare function agentOwnerDead(note: AgentNote, now?: number): boolean;
+/** Whether a profile is answering this gate right now -- not a crashed process's leftover. */
+export declare function isAnswering(note: AgentNote | undefined, gateId: string): boolean;
+/**
+ * Mark as failed every answer in progress whose process is gone, so the
+ * gate is a person's or the next process's to answer instead of locked
+ * forever. Called when a driver starts. Returns the runs it reclaimed.
+ */
+export declare function reclaimStaleAgentAnswers(coordinator: LocalCoordinator): Promise<string[]>;
+/** Ask the matching profile to answer the run's current agent gate. Does not resume. */
+export declare function answerAgentGate(coordinator: LocalCoordinator, runId: string, opts: AgentGateOptions): Promise<AgentGateStep>;
+export interface AutoAgentResult {
+    /** Why the loop stopped: the run ended, or it needs a person. */
+    stop: 'completed' | 'failed' | 'cancelled' | 'waiting-human' | 'manual' | 'no-profile' | 'not-ready' | 'agent-failed' | 'chain-limit';
+    run: RunView;
+}
+/**
+ * After a resume with a profile's answer failed: when the answer did not
+ * fit the gate (outputs missing, or a value the gate cannot take), that is
+ * the model's failure, not the run's, so it is recorded on the agent note
+ * and the gate stays waiting for a person. Any other failure is left to the
+ * caller. True when the failure was a misfit and has been recorded.
+ */
+export declare function noteAnswerMisfit(coordinator: LocalCoordinator, runId: string, error: unknown): Promise<boolean>;
+/**
+ * Answer agent gates and resume, again and again, until the run ends or
+ * reaches something a person must do. A malformed answer -- the model
+ * returned the wrong outputs -- is the model's failure, not the run's: it is
+ * recorded on the note and the gate stays waiting.
+ */
+export declare function autoAnswerAgentGates(coordinator: LocalCoordinator, runId: string, opts: AgentGateOptions & {
+    drive?: DriveOptions;
+    maxChain?: number;
+}): Promise<AutoAgentResult>;
+//# sourceMappingURL=agent-gate.d.ts.map

package/dist/coordinator/bundle-digest.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The bundle identity a local coordinator can honestly vouch for.
+ *
+ * The engine refuses a gated run without a `bundleDigest` and only checks
+ * its shape (`workflow-executor.ts:181-183, 237-244`). Producing it is the
+ * coordinator's job. ADR 0001 forbids hashing the workflow *source*, because
+ * imports can change underneath it. The compiled artifact is what actually
+ * executes for this module, so it is hashed instead.
+ *
+ * Known limitation: node types imported from other files remain imports in
+ * the artifact, so a change in one of them is not reflected here. That is
+ * acceptable for a single-machine development coordinator. The engine's own
+ * `graphFingerprint` and `engineVersion` checks still apply on resume, and a
+ * distributed coordinator supplies stronger evidence.
+ *
+ * Results are cached by file identity so listing and repeated resumes do not
+ * recompile.
+ */
+export declare function computeBundleDigest(filePath: string, workflowName: string): Promise<string>;
+//# sourceMappingURL=bundle-digest.d.ts.map

package/dist/coordinator/clock-tick.d.ts

@@ -0,0 +1,4 @@
+import type { ResumeRequest, RunView, TickResult } from './run-store.js';
+import type { RunStore } from './store.js';
+export declare function tickDue(store: RunStore, resume: (request: ResumeRequest) => Promise<RunView>, now: number): Promise<TickResult>;
+//# sourceMappingURL=clock-tick.d.ts.map

package/dist/coordinator/effect-receipts.d.ts

@@ -0,0 +1,10 @@
+import type { EffectAdapter } from '../runtime/durable-execution.js';
+import { type RunStore } from './store.js';
+/**
+ * Effect receipts as documents of the run, one per operation key, so a
+ * resume can prove an effect already committed instead of running it again.
+ */
+export declare function createStoreEffectAdapter(store: RunStore, runId: string): EffectAdapter;
+/** Effect receipts under `<runDir>/effects/`, as the file store keeps them. Kept for callers of the old name. */
+export declare function createFileEffectAdapter(runDir: string): EffectAdapter;
+//# sourceMappingURL=effect-receipts.d.ts.map

package/dist/coordinator/errors.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The refusals the coordinator throws.
+ *
+ * Each one decides what a driver is told when a run cannot be started or
+ * moved: the file did not parse or names several workflows, there is no
+ * such run, the run is not waiting at a gate, or the workflow changed since
+ * the run paused. A driver tells them apart by `name`, as `tick` does.
+ */
+import type { RunView } from './run-store.js';
+export declare class ParseError extends Error {
+    readonly name = "ParseError";
+}
+export declare class AmbiguousWorkflowError extends Error {
+    readonly names: readonly string[];
+    readonly name = "AmbiguousWorkflowError";
+    constructor(names: readonly string[]);
+}
+export declare class RunNotFoundError extends Error {
+    readonly name = "RunNotFoundError";
+    constructor(runId: string);
+}
+export declare class RunNotWaitingError extends Error {
+    readonly status: RunView['status'];
+    readonly name = "RunNotWaitingError";
+    constructor(status: RunView['status']);
+}
+export declare class BundleChangedError extends Error {
+    readonly name = "BundleChangedError";
+    constructor();
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1,3 @@
+import { type RunStore } from './store.js';
+export declare function createFileRunStore(rootDir: string): RunStore;
+//# sourceMappingURL=file-store.d.ts.map

package/dist/coordinator/gate-labeling.d.ts

@@ -0,0 +1,33 @@
+import type { DurableGate } from '../runtime/continuation.js';
+import type { TWorkflowAST } from '../ast/types.js';
+/**
+ * A gate's inputs keyed by port name, plus what a resolver needs to know to
+ * build the node's output envelope later.
+ */
+export interface LabeledGate {
+    /** Declared inputs by name. An omitted optional input is `null`. */
+    inputs: Record<string, unknown>;
+    /** Input names that arrived as `{ absent: true }`. */
+    absent: string[];
+    /** Data output port names, in declared order. Control ports excluded. */
+    outputs: string[];
+    hasSuccessPort: boolean;
+    hasFailurePort: boolean;
+}
+/**
+ * Turn the engine's positional gate payload into named inputs.
+ *
+ * The generator emits `{ arguments: [ {value}|{absent}, ... ] }` in declared
+ * input order, skipping `execute` and any trailing runtime arguments
+ * (buildDurableGatePayload in `src/generator/node-invocation.ts`). An
+ * assistant reading `{"arguments":[{"value":"review"},...]}` would have to
+ * open the workflow to learn which position is which. The names come from
+ * the parsed node type instead, so the tool result is self-describing.
+ *
+ * Names are taken in `@input` tag order. If an author declared tags in a
+ * different order from the function parameters, labels would be wrong. The
+ * positional payload is the source of truth and a length mismatch is
+ * refused rather than zipped. The built-in gate nodes are covered by tests.
+ */
+export declare function labelGate(gate: DurableGate, ast: TWorkflowAST): LabeledGate;
+//# sourceMappingURL=gate-labeling.d.ts.map

package/dist/coordinator/gate-resolution.d.ts

@@ -0,0 +1,28 @@
+import type { GateResolution } from '../runtime/durable-execution.js';
+import type { LabeledGate } from './gate-labeling.js';
+/** What a driver sends back for a paused gate: a result, or a refusal. */
+export type ResolveInput = {
+    answer: unknown;
+} | {
+    reject: string;
+};
+export declare class MissingOutputsError extends Error {
+    readonly missing: readonly string[];
+    readonly name = "MissingOutputsError";
+    constructor(missing: readonly string[]);
+}
+export declare class InvalidAnswerError extends Error {
+    readonly name = "InvalidAnswerError";
+}
+/**
+ * Build the resolution the engine expects from what a driver actually knows.
+ *
+ * The engine takes the resolution value as the gate node's *entire* output
+ * envelope, control ports included (`resolveGate` in `durable-execution.ts`). Sending
+ * only the data port is accepted and then quietly wrong: `onSuccess` is never
+ * set, the successor never fires, and the run reports `completed` with
+ * `onSuccess: false`. A driver should never have to know that, so the
+ * control ports are filled in here.
+ */
+export declare function buildGateResolution(gate: Pick<LabeledGate, 'outputs' | 'hasSuccessPort' | 'hasFailurePort'>, gateId: string, input: ResolveInput): GateResolution;
+//# sourceMappingURL=gate-resolution.d.ts.map

package/dist/coordinator/index.d.ts

@@ -0,0 +1,12 @@
+export { createLocalCoordinator, createFileEffectAdapter, createStoreEffectAdapter, defaultRunsDir, resolveProjectRoot, ParseError, AmbiguousWorkflowError, RunNotFoundError, RunNotWaitingError, BundleChangedError, type LocalCoordinator, type LocalCoordinatorOptions, type StartRequest, type ResumeRequest, type DriveOptions, type TraceEntry, type RunRecord, type RunView, type RunSummary, type AgentNote, type TickResult, } from './run-store.js';
+export { parseDuration, dueFor, type RunDue } from './time.js';
+export { answerAgentGate, autoAnswerAgentGates, isAnswering, noteAnswerMisfit, agentOwnerDead, reclaimStaleAgentAnswers, transcriptName, type AgentGateOptions, type AgentGateStep, type AutoAgentResult, type AgentTranscript, } from './agent-gate.js';
+export { labelGate, type LabeledGate } from './gate-labeling.js';
+export { buildGateResolution, MissingOutputsError, InvalidAnswerError, type ResolveInput, } from './gate-resolution.js';
+export { computeBundleDigest } from './bundle-digest.js';
+export { RunBusyError, DOC_NAME, RESERVED_DOCS, EFFECT_DOC_PREFIX, checkDocName, type RunStore } from './store.js';
+export { missingParams, MissingParamsError } from './params.js';
+export { createFileRunStore } from './file-store.js';
+export { createMemoryRunStore } from './memory-store.js';
+export { executeWorkflow, ContinuationRefusalError, type WorkflowExecutionRequest, type WorkflowExecutionOutcome, type CompletedExecutionOutcome, type YieldedExecutionOutcome, type ExecutionTraceEvent, } from '../mcp/workflow-executor.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/coordinator/index.js

@@ -0,0 +1,107 @@
+import {
+  AmbiguousWorkflowError,
+  BundleChangedError,
+  DOC_NAME,
+  EFFECT_DOC_PREFIX,
+  InvalidAnswerError,
+  MissingOutputsError,
+  MissingParamsError,
+  ParseError,
+  RESERVED_DOCS,
+  RunBusyError,
+  RunNotFoundError,
+  RunNotWaitingError,
+  agentOwnerDead,
+  answerAgentGate,
+  autoAnswerAgentGates,
+  buildGateResolution,
+  checkDocName,
+  computeBundleDigest,
+  createFileEffectAdapter,
+  createFileRunStore,
+  createLocalCoordinator,
+  createMemoryRunStore,
+  createStoreEffectAdapter,
+  defaultRunsDir,
+  dueFor,
+  isAnswering,
+  labelGate,
+  missingParams,
+  noteAnswerMisfit,
+  reclaimStaleAgentAnswers,
+  resolveProjectRoot,
+  transcriptName
+} from "../chunks/chunk-VO4QXG2X.js";
+import {
+  ContinuationRefusalError,
+  executeWorkflow
+} from "../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 {
+  parseDuration
+} from "../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";
+export {
+  AmbiguousWorkflowError,
+  BundleChangedError,
+  ContinuationRefusalError,
+  DOC_NAME,
+  EFFECT_DOC_PREFIX,
+  InvalidAnswerError,
+  MissingOutputsError,
+  MissingParamsError,
+  ParseError,
+  RESERVED_DOCS,
+  RunBusyError,
+  RunNotFoundError,
+  RunNotWaitingError,
+  agentOwnerDead,
+  answerAgentGate,
+  autoAnswerAgentGates,
+  buildGateResolution,
+  checkDocName,
+  computeBundleDigest,
+  createFileEffectAdapter,
+  createFileRunStore,
+  createLocalCoordinator,
+  createMemoryRunStore,
+  createStoreEffectAdapter,
+  defaultRunsDir,
+  dueFor,
+  executeWorkflow,
+  isAnswering,
+  labelGate,
+  missingParams,
+  noteAnswerMisfit,
+  parseDuration,
+  reclaimStaleAgentAnswers,
+  resolveProjectRoot,
+  transcriptName
+};

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

@@ -0,0 +1,3 @@
+import { type RunStore } from './store.js';
+export declare function createMemoryRunStore(): RunStore;
+//# sourceMappingURL=memory-store.d.ts.map

package/dist/coordinator/params.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The parameters a workflow needs before it can start.
+ *
+ * A run started without a required parameter used to run anyway and return
+ * nothing for it, which reads as success. Every driver -- the CLI, the MCP
+ * tools, the console, the API -- refuses it here instead, naming what is
+ * missing.
+ */
+import type { TWorkflowAST } from '../ast/types.js';
+/** The `@param` names the workflow requires that `params` does not provide. */
+export declare function missingParams(ast: TWorkflowAST, params: Record<string, unknown> | undefined): string[];
+export declare class MissingParamsError extends Error {
+    readonly workflowName: string;
+    readonly missing: string[];
+    readonly name = "MissingParamsError";
+    constructor(workflowName: string, missing: string[]);
+}
+//# sourceMappingURL=params.d.ts.map

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

@@ -0,0 +1,6 @@
+import type { RunContext } from './run-context.js';
+import type { AgentNote, RunRecord } from './run-store.js';
+export declare function setAgentNote(ctx: RunContext, runId: string, note: AgentNote | undefined): Promise<RunRecord>;
+export declare function keepDoc(ctx: RunContext, runId: string, name: string, data: unknown): Promise<void>;
+export declare function keptDoc<T>(ctx: RunContext, runId: string, name: string): Promise<T | undefined>;
+//# sourceMappingURL=run-annotations.d.ts.map

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

@@ -0,0 +1,11 @@
+import type { LocalCoordinatorOptions, RunRecord } from './run-store.js';
+import { type RunStore } from './store.js';
+export interface RunContext {
+    readonly store: RunStore;
+    /** Do `work` holding the run's claim; `RunBusyError` when another owner holds it. */
+    claimed<T>(runId: string, work: () => Promise<T>): Promise<T>;
+    /** The run's record as the store has it now, or undefined. */
+    readRecord(runId: string): Promise<RunRecord | undefined>;
+}
+export declare function createRunContext(options: LocalCoordinatorOptions): RunContext;
+//# sourceMappingURL=run-context.d.ts.map

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

@@ -0,0 +1,5 @@
+import type { RunContext } from './run-context.js';
+import type { RunView } from './run-store.js';
+export declare function cancelRun(ctx: RunContext, runId: string): Promise<RunView>;
+export declare function removeRun(ctx: RunContext, runId: string): Promise<void>;
+//# sourceMappingURL=run-ending.d.ts.map

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

@@ -0,0 +1,31 @@
+/**
+ * How the end of a segment is written down.
+ *
+ * Decides what the record says after a segment: waiting at the gate it
+ * yielded at, with the continuation and the clock's due time in the same
+ * write; completed with its result; or, when the segment threw, cancelled
+ * (its driver stopped it) or failed with the error and the step that threw.
+ * A terminal outcome drops the `continuation` document an older version
+ * kept.
+ */
+import type { TWorkflowAST } from '../ast/types.js';
+import type { WorkflowExecutionOutcome } from '../mcp/workflow-executor.js';
+import type { DriveOptions, RunRecord, TraceEntry } from './run-store.js';
+import type { RunStore } from './store.js';
+/**
+ * Commit an outcome with one `put`: the gate and the continuation it
+ * resumes from are in the same record, so a process that dies before the
+ * write leaves the run at its previous gate with that gate's continuation,
+ * and a resume with that gate's answer moves it on again. A run with
+ * documents and no record is an unacknowledged yield and is ignored
+ * everywhere. Runs paused by an older version keep the envelope in a
+ * `continuation` document instead; a terminal outcome drops it.
+ */
+export declare function commit(store: RunStore, record: RunRecord, outcome: WorkflowExecutionOutcome, ast: TWorkflowAST, kept?: TraceEntry[]): Promise<RunRecord>;
+/**
+ * A run that did not reach an outcome. Stopped by its driver's signal it
+ * is `cancelled`, which is not a failure and is not shown as one; anything
+ * else is `failed` with the error.
+ */
+export declare function fail(store: RunStore, record: RunRecord, error: unknown, options: DriveOptions | undefined, kept?: TraceEntry[]): Promise<void>;
+//# sourceMappingURL=run-outcome.d.ts.map

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

@@ -0,0 +1,6 @@
+import type { RunContext } from './run-context.js';
+import type { DriveOptions, ResumeRequest, RunRecord, RunView } from './run-store.js';
+/** The waiting record a resume would act on, or the refusal it would meet before taking the run. */
+export declare function resumable(ctx: RunContext, request: ResumeRequest): Promise<RunRecord>;
+export declare function resumeRun(ctx: RunContext, request: ResumeRequest, options: DriveOptions | undefined): Promise<RunView>;
+//# sourceMappingURL=run-resume.d.ts.map

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

@@ -0,0 +1,4 @@
+import type { RunContext } from './run-context.js';
+import type { DriveOptions, RunView, StartRequest } from './run-store.js';
+export declare function startRun(ctx: RunContext, request: StartRequest, options: DriveOptions | undefined): Promise<RunView>;
+//# sourceMappingURL=run-start.d.ts.map