@synergenius/flow-weaver 0.33.2 → 0.44.0

package/dist/marketplace/index.js

@@ -1,10 +1,62 @@
-/**
- * @module marketplace
- *
- * Flow Weaver Marketplace — discover, install, and publish reusable
- * node types, workflows, and patterns via npm.
- */
-export { generateManifest, writeManifest, readManifest, } from './manifest.js';
-export { validatePackage } from './validator.js';
-export { searchPackages, listInstalledPackages, getInstalledPackageManifest, discoverTagHandlers, discoverValidationRuleSets, discoverDocTopics, discoverInitContributions, discoverDeviceHandlers, } from './registry.js';
-//# sourceMappingURL=index.js.map
+import {
+  generateManifest,
+  readManifest,
+  writeManifest
+} from "../chunks/chunk-PKWSAW6O.js";
+import {
+  validatePackage
+} from "../chunks/chunk-EFGFXXQF.js";
+import "../chunks/chunk-P44RIZ7C.js";
+import {
+  PUBLIC_REGISTRY,
+  discoverDocTopics,
+  discoverInitContributions,
+  discoverTagHandlers,
+  discoverValidationRuleSets,
+  getInstalledPackageManifest,
+  listInstalledPackages,
+  nerfDart,
+  parseNpmrc,
+  readNpmConfig,
+  resolveRegistries,
+  searchAllRegistries,
+  searchPackages
+} from "../chunks/chunk-ZKEGXO73.js";
+import "../chunks/chunk-A5MBOFVY.js";
+import "../chunks/chunk-VQ7H33J4.js";
+import "../chunks/chunk-NQNLUAPO.js";
+import "../chunks/chunk-INDEVYEC.js";
+import "../chunks/chunk-KU3CLJI2.js";
+import "../chunks/chunk-XAV22WD7.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 {
+  PUBLIC_REGISTRY,
+  discoverDocTopics,
+  discoverInitContributions,
+  discoverTagHandlers,
+  discoverValidationRuleSets,
+  generateManifest,
+  getInstalledPackageManifest,
+  listInstalledPackages,
+  nerfDart,
+  parseNpmrc,
+  readManifest,
+  readNpmConfig,
+  resolveRegistries,
+  searchAllRegistries,
+  searchPackages,
+  validatePackage,
+  writeManifest
+};

package/dist/marketplace/install.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Running npm for the marketplace: install, uninstall and publish a pack.
+ *
+ * npm runs through execFile with an argument list, never through a shell, and
+ * the package spec is checked against the shapes npm accepts before npm sees
+ * it. The spec reaches here from the command line, from the console and from
+ * an MCP client, so it is untrusted input.
+ */
+import { type StdioOptions } from 'node:child_process';
+/** Whether `spec` is something `npm install` takes as a single package argument. */
+export declare function isPackageSpec(spec: string): boolean;
+export interface NpmOptions {
+    cwd?: string;
+    stdio?: StdioOptions;
+}
+/** Run npm with these arguments, without a shell. */
+export declare function runNpm(args: string[], options?: NpmOptions): void;
+/** `npm install <spec>`, refusing a spec that is not a package name, version or local path. */
+export declare function npmInstall(spec: string, options?: NpmOptions): void;
+/** `npm uninstall <name>`, refusing anything but a package name. */
+export declare function npmUninstall(name: string, options?: NpmOptions): void;
+/** `npm publish`, with a dist-tag when one is given, refusing a tag that is not a plain word. */
+export declare function npmPublish(tag: string | undefined, options?: NpmOptions): void;
+//# sourceMappingURL=install.d.ts.map

package/dist/marketplace/manifest.d.ts

@@ -1,5 +1,5 @@
 /**
- * Manifest generation — converts parsed ASTs into a flowweaver.manifest.json file.
+ * Manifest generation: converts parsed ASTs into a flowweaver.manifest.json file.
  *
  * The manifest mirrors AST types so the editor can consume it directly
  * without re-parsing source files.

package/dist/marketplace/npmrc.d.ts

@@ -0,0 +1,24 @@
+export declare const PUBLIC_REGISTRY = "https://registry.npmjs.org/";
+export interface Registry {
+    /** Base URL, with a trailing slash. */
+    url: string;
+    /** Scopes routed here (`@synergenius`), empty for the default registry. */
+    scopes: string[];
+    /** Whether this is the unscoped default. */
+    isDefault: boolean;
+    /** The `Authorization` header value, when `.npmrc` has credentials for this host. */
+    authorization?: string;
+}
+/** Parse `.npmrc` text into key/value pairs, expanding `${VAR}` from the environment as npm does. */
+export declare function parseNpmrc(text: string, env?: NodeJS.ProcessEnv): Map<string, string>;
+/** npm's "nerf dart": the part of a registry URL an auth key is written against. */
+export declare function nerfDart(url: string): string;
+/**
+ * Merge the config files npm would read for a project: user first, then the
+ * project's, so the project's lines win. `npm_config_registry` in the
+ * environment wins over both for the default registry.
+ */
+export declare function readNpmConfig(projectDir: string, env?: NodeJS.ProcessEnv, home?: string): Map<string, string>;
+/** Every registry a project's npm would talk to, the default first. */
+export declare function resolveRegistries(projectDir: string, config?: Map<string, string>): Registry[];
+//# sourceMappingURL=npmrc.d.ts.map

package/dist/marketplace/registry.d.ts

@@ -1,11 +1,16 @@
 /**
- * Registry integration — npm search API + local package scanning.
+ * Registry integration: npm search API plus local package scanning.
+ *
+ * A pack is a package carrying a `flowweaver.manifest.json` (installed) or
+ * the marketplace keyword (on a registry). `flow-weaver-pack-*` is the
+ * naming convention, not the test.
  *
  * Uses the npm registry search endpoint filtered by the
  * `flow-weaver-marketplace-pack` keyword for discovery, and scans
  * `node_modules/` for locally installed packages.
  */
 import type { TMarketplaceManifest, TMarketplacePackageInfo, TInstalledPackage, TManifestTagHandler, TManifestValidationRuleSet, TManifestDocTopic, TManifestInitContribution } from './types.js';
+import { type Registry } from './npmrc.js';
 export interface SearchOptions {
     /** Search query text */
     query?: string;
@@ -15,12 +20,49 @@ export interface SearchOptions {
     registryUrl?: string;
 }
 /**
- * Search the npm registry for marketplace packages.
+ * Search one registry for marketplace packages: the public one, or the
+ * search URL given. For every registry a project's npm would use, see
+ * {@link searchAllRegistries}.
  */
 export declare function searchPackages(options?: SearchOptions): Promise<TMarketplacePackageInfo[]>;
+export interface RegistrySearched {
+    url: string;
+    scopes: string[];
+    /** Whether `.npmrc` had credentials for it. */
+    authenticated: boolean;
+    ok: boolean;
+    error?: string;
+    count: number;
+}
+export interface MultiRegistrySearch {
+    /** Merged, a package once, the first registry that had it winning. */
+    results: Array<TMarketplacePackageInfo & {
+        registry: string;
+    }>;
+    searched: RegistrySearched[];
+}
 /**
- * Scan node_modules for installed marketplace packages by looking for
- * `flowweaver.manifest.json` files in matching package directories.
+ * Search every registry the project's npm would talk to -- the default and
+ * each scoped one from `.npmrc`, with its credentials -- and say which were
+ * asked and which answered. One registry failing does not fail the search;
+ * it is reported beside the results.
+ */
+export declare function searchAllRegistries(options?: {
+    query?: string;
+    limit?: number;
+    projectDir?: string;
+    registries?: Registry[];
+}): Promise<MultiRegistrySearch>;
+/**
+ * The packs installed in a project: every package under `node_modules`,
+ * scoped or not, that carries a `flowweaver.manifest.json`.
+ *
+ * The manifest is the identity. A name like `flow-weaver-pack-*` is the
+ * convention and helps a pack be found on a registry, but a package an
+ * organisation had to call something else is no less a pack once it is
+ * installed, and everything that loads packs -- the parser's tag handlers
+ * and rule sets, export targets, docs, CLI and MCP extensions -- goes
+ * through here.
  */
 export declare function listInstalledPackages(projectDir: string): Promise<TInstalledPackage[]>;
 /**
@@ -74,11 +116,4 @@ export declare function discoverDocTopics(projectDir: string): Promise<TDiscover
  * Discover all init contributions from installed pack manifests.
  */
 export declare function discoverInitContributions(projectDir: string): Promise<TDiscoveredInitContribution[]>;
-/**
- * Discover all device handler entry points from installed pack manifests.
- *
- * Returns packs that declare a `deviceHandlers` field in their manifest,
- * resolved to an absolute entrypoint path.
- */
-export declare function discoverDeviceHandlers(projectDir: string): Promise<TDiscoveredDeviceHandler[]>;
 //# sourceMappingURL=registry.d.ts.map

package/dist/marketplace/types.d.ts

@@ -1,8 +1,8 @@
 /**
  * Marketplace types for Flow Weaver package distribution.
  *
- * Packages follow the naming convention `flow-weaver-pack-*` and use
- * npm as the distribution backbone. The manifest is auto-generated
+ * A pack is a package carrying a `flowweaver.manifest.json`. By convention
+ * it is named `flow-weaver-pack-*`. npm is the distribution backbone. The manifest is auto-generated
  * from source annotations via the parser.
  */
 import type { TDataType } from '../ast/types.js';
@@ -24,8 +24,6 @@ export type TMarketplaceManifest = {
     nodeTypes: TManifestNodeType[];
     /** Workflows included in this package */
     workflows: TManifestWorkflow[];
-    /** Patterns included in this package */
-    patterns: TManifestPattern[];
     /** Export targets provided by this package */
     exportTargets?: TManifestExportTarget[];
     /** Tag handlers contributed by this pack (v2) */
@@ -44,8 +42,6 @@ export type TMarketplaceManifest = {
     mcpEntrypoint?: string;
     /** MCP tools contributed by this pack */
     mcpTools?: TManifestMcpTool[];
-    /** Entry point for device connection handler registration */
-    deviceHandlers?: string;
     /** External dependency information */
     dependencies?: {
         /** Flow Weaver peer dependency constraints */
@@ -113,20 +109,6 @@ export type TManifestWorkflow = {
     /** Number of connections */
     connectionCount: number;
 };
-export type TManifestPattern = {
-    /** Pattern name */
-    name: string;
-    /** Human-readable description */
-    description?: string;
-    /** Relative path to source file */
-    file: string;
-    /** Input ports (IN pseudo-node connections) */
-    inputPorts: Record<string, TManifestPort>;
-    /** Output ports (OUT pseudo-node connections) */
-    outputPorts: Record<string, TManifestPort>;
-    /** Number of internal nodes */
-    nodeCount: number;
-};
 export type TValidationSeverity = 'error' | 'warning';
 export type TValidationIssue = {
     /** Unique rule identifier (e.g., PKG-001, UNIT-002) */
@@ -156,7 +138,7 @@ export type TMarketplacePackageInfo = {
     publisher?: string;
     /** Package keywords */
     keywords?: string[];
-    /** Whether this is an official @synergenius package */
+    /** Published under the maintainers' `@synergenius/` npm scope. Any other scope is a third-party pack. */
     official: boolean;
 };
 /** An installed marketplace package with its resolved manifest. */
@@ -177,7 +159,7 @@ export type TInstalledPackage = {
 export type TManifestTagHandler = {
     /** Tag name(s) this handler processes (e.g., "secret", "runner") */
     tags: string[];
-    /** Deploy namespace for storing parsed data (e.g., "cicd") */
+    /** Deploy namespace for storing parsed data (e.g., a pack name) */
     namespace: string;
     /** Applicable scope: workflow-level tags, nodeType-level tags, or both */
     scope: 'workflow' | 'nodeType' | 'both';
@@ -185,6 +167,14 @@ export type TManifestTagHandler = {
     file: string;
     /** Named export from the file (default: "default") */
     exportName?: string;
+    /**
+     * Named export of a serializer (TTagSerializerFn) that emits this
+     * namespace's JSDoc annotations from its deploy data, the inverse of the
+     * handler. Keeps annotation regeneration symmetric with parsing so no tags
+     * are dropped. Resolved from the same `file`. When omitted, core emits
+     * nothing for the namespace (legacy behavior on packs without a serializer).
+     */
+    serializerExport?: string;
 };
 /**
  * A validation rule set contributed by a pack. Declares a detect function
@@ -193,7 +183,7 @@ export type TManifestTagHandler = {
 export type TManifestValidationRuleSet = {
     /** Human-readable name for this rule set */
     name: string;
-    /** Deploy namespace this rule set applies to (e.g., "cicd") */
+    /** Deploy namespace this rule set applies to (e.g., a pack name) */
     namespace: string;
     /** Relative path to the compiled JS file exporting detect and getRules */
     file: string;
@@ -241,8 +231,14 @@ export type TManifestCliCommand = {
     name: string;
     /** Human-readable description */
     description: string;
-    /** Usage string for positional args (e.g., "<file>", "[id]") */
+    /**
+     * Legacy whitespace-separated Commander argument syntax.
+     * Prefer `arguments`, which preserves descriptions and does not collapse
+     * multiple positional arguments into one token.
+     */
     usage?: string;
+    /** Ordered positional arguments contributed by this command. */
+    arguments?: TManifestCliArgument[];
     /** Command options */
     options?: Array<{
         flags: string;
@@ -250,6 +246,27 @@ export type TManifestCliCommand = {
         default?: string | number | boolean;
     }>;
 };
+export type TManifestCliArgument = {
+    /** Commander argument syntax, for example `<recording>` or `[files...]`. */
+    syntax: string;
+    /** Human-readable help for this argument. */
+    description?: string;
+    /** Default used for an optional argument. */
+    default?: string;
+};
+/** JSON-safe values Commander may produce for a declared pack option. */
+export type TPackCliOptionValue = string | number | boolean | readonly string[];
+/**
+ * Stable command context passed to a pack's `handleCommandV2` export.
+ *
+ * Flow Weaver owns parsing. Packs must not recover their options from
+ * `process.argv`, which is ambiguous under embedding and tests.
+ */
+export type TPackCliCommandContext = Readonly<{
+    args: readonly string[];
+    options: Readonly<Record<string, TPackCliOptionValue>>;
+    cwd: string;
+}>;
 /** An MCP tool contributed by a pack. */
 export type TManifestMcpTool = {
     /** Tool name (e.g., "fw_weaver_run") */

package/dist/marketplace/validator.d.ts

@@ -1,5 +1,5 @@
 /**
- * Package validation — checks that a marketplace package meets
+ * Package validation: checks that a marketplace package meets
  * all requirements before publishing.
  */
 import type { TMarketplaceManifest } from './types.js';

package/dist/mcp/debug-session.d.ts

@@ -1,7 +1,6 @@
 /**
  * In-memory registry for active debug sessions.
- * Mirrors the pattern of run-registry.ts but tracks DebugController state
- * instead of AgentChannel state.
+ * Tracks execution-scoped DebugController state for live developer sessions.
  */
 import type { DebugController, DebugPauseState } from '../runtime/debug-controller.js';
 export interface DebugSession {
@@ -11,9 +10,8 @@ export interface DebugSession {
     controller: DebugController;
     /** The still-pending execution promise. Resolves when workflow completes. */
     executionPromise: Promise<unknown>;
+    /** When the session started. One older than `DEBUG_SESSION_MAX_AGE_MS` is dropped. */
     createdAt: number;
-    /** Temp files to clean up when the session ends. */
-    tmpFiles: string[];
     /** Most recent pause state (updated on each pause) */
     lastPauseState?: DebugPauseState;
 }

package/dist/mcp/dist-imports.d.ts

@@ -0,0 +1,12 @@
+import * as nodePath from 'node:path';
+/**
+ * Rewrite the relative imports of transpiled code that sits in `srcDir`.
+ * Only a directory under a `src` segment is touched, and only an import
+ * whose src file is missing while its dist file exists. The specifier is
+ * written with forward slashes, which ESM requires on every platform.
+ *
+ * @param fileExists The file system check; tests pass their own.
+ * @param path The path module; tests pass `path.win32` for Windows paths.
+ */
+export declare function rewriteSrcImportsToDist(code: string, srcDir: string, fileExists?: (p: string) => boolean, path?: typeof nodePath): string;
+//# sourceMappingURL=dist-imports.d.ts.map

package/dist/mcp/response-utils.d.ts

@@ -28,11 +28,17 @@ export declare function makeErrorResult(code: string, message: string): {
  */
 export declare const ERROR_HINTS: Record<string, string>;
 /**
- * Enriches validation items with actionable hints from {@link ERROR_HINTS} and optional
- * friendly error explanations. Replaces `<nodeId>` placeholders in hints with actual node IDs.
+ * Enriches validation items with one actionable next step. Replaces `<nodeId>`
+ * placeholders in hints with actual node IDs.
+ *
+ * Each item carries at most one of `hint` (a tool-oriented next step from
+ * {@link ERROR_HINTS}) or `fix` (the friendly-error fix text). The friendly
+ * title and explanation are deliberately not included: they restate `message`
+ * and only add tokens to every validation result.
+ *
  * @param items - Array of validation errors/warnings, each with a message, severity, and optional code.
- * @param friendlyErrorFn - Optional function that produces user-friendly error explanations.
- * @returns A new array with `hint` and `friendly` fields added where applicable.
+ * @param friendlyErrorFn - Optional function that produces the friendly fix text.
+ * @returns A new array with `hint` or `fix` added where applicable.
  */
 export declare function addHintsToItems(items: Array<{
     message: string;
@@ -54,10 +60,6 @@ export declare function addHintsToItems(items: Array<{
     nodeId?: string;
     code?: string;
     hint?: string;
-    friendly?: {
-        title: string;
-        explanation: string;
-        fix: string;
-    };
+    fix?: string;
 }>;
 //# sourceMappingURL=response-utils.d.ts.map

package/dist/mcp/server.d.ts

@@ -1,4 +1,3 @@
-import '../extensions/index.js';
 import type { McpServerOptions } from './types.js';
 export declare function startMcpServer(options: McpServerOptions): Promise<void>;
 export declare function mcpServerCommand(options: McpServerOptions): Promise<void>;

package/dist/mcp/tools-context.d.ts

@@ -1,3 +1,14 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * fw_context is the first call an assistant makes in a session, so it is
+ * shaped for progressive loading: the default `core` preset is one short
+ * orientation topic, and every result ends with the list of topics it did
+ * not include and their sizes. The larger presets remain for callers that
+ * want a self-contained dump and know the cost.
+ *
+ * The result is the bundle itself as markdown text, not a JSON envelope. The
+ * bundle is a document to read, and the envelope used to repeat the closing
+ * topic list as a JSON array and add counters nobody acted on.
+ */
 export declare function registerContextTools(mcp: McpServer): void;
 //# sourceMappingURL=tools-context.d.ts.map

package/dist/mcp/tools-diagram.d.ts

@@ -1,8 +1,7 @@
 /**
  * MCP Diagram Tool - fw_diagram
  *
- * Generates diagrams from workflow files or inline source code.
- * Supports SVG, interactive HTML, and ASCII text formats.
+ * The workflow as an SVG of its spine, or as text for a chat.
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export declare function registerDiagramTools(mcp: McpServer): void;

package/dist/mcp/tools-export.d.ts

@@ -1,8 +1,8 @@
 /**
  * MCP Export Tool - fw_export
  *
- * Allows Claude Code to export workflows as serverless deployments
- * without the GUI. Generates handler code, platform config, and deploy instructions.
+ * Exports a workflow through a target an installed pack provides: handler
+ * code, the target's config files, and deploy instructions.
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export declare function registerExportTools(mcp: McpServer): void;

package/dist/mcp/tools-marketplace.d.ts

@@ -1,5 +1,5 @@
 /**
- * MCP Marketplace Tools — fw_market_search, fw_market_install, fw_market_list
+ * MCP Marketplace Tools: fw_market_search, fw_market_install, fw_market_list
  *
  * Allows Claude Code to discover, install, and inspect marketplace packages
  * during vibe coding sessions.

package/dist/mcp/tools-run.d.ts

@@ -0,0 +1,17 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type LocalCoordinator } from '../coordinator/index.js';
+/**
+ * Coordinated workflow runs for an AI assistant.
+ *
+ * The engine's own run and resume (`executeWorkflow`) hand the caller the
+ * whole continuation envelope and expect it back. That is right for a
+ * coordinator and hopeless for a language model, which would carry ~800
+ * tokens of addresses and variables per gate in each direction. These three
+ * tools put a local coordinator in between so the assistant only ever sees
+ * `{ runId, gate }` and answers with `{ runId, answer }`.
+ *
+ * Nothing here returns trace events, progress, or the envelope. Fewer tokens
+ * is the point.
+ */
+export declare function registerRunTools(mcp: McpServer, injectedCoordinator?: LocalCoordinator): void;
+//# sourceMappingURL=tools-run.d.ts.map

package/dist/mcp/tools-workflow.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerWorkflowTools(mcp: McpServer): void;
+//# sourceMappingURL=tools-workflow.d.ts.map

package/dist/mcp/types.d.ts

@@ -2,19 +2,9 @@
 export interface McpServerOptions {
     /** Whether to use stdio transport instead of SSE. */
     stdio?: boolean;
-}
-/** Dependencies injected into tool registration functions for CLI interaction and logging. */
-export interface RegistrationDeps {
-    /** Execute a shell command and return its stdout and exit code. */
-    execCommand: (cmd: string) => Promise<{
-        stdout: string;
-        exitCode: number;
-    }>;
-    /** Prompt the user for interactive input. */
-    prompt: (question: string) => Promise<string>;
-    /** Log a message to the console. */
-    log: (msg: string) => void;
-    /** Resolve the path to the Flow Weaver CLI executable. */
-    resolveCliPath: () => string;
+    /** Called with the tool's name on every call. This is how the server reports what it is doing. */
+    onToolCall?: (name: string) => void;
+    /** Called once the client has introduced itself, with its name and version. */
+    onClient?: (client: string) => void;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/mcp/workflow-executor.d.ts

@@ -3,8 +3,10 @@
  * Copies source to a temp file, compiles all workflows in-place, then dynamically imports and executes.
  */
 import type { FwMockConfig } from '../built-in-nodes/mock-types.js';
-import type { AgentChannel } from './agent-channel.js';
+import type { TExternalNodeType } from '../parser/annotation-parser.js';
 import type { DebugController } from '../runtime/debug-controller.js';
+import { type ContinuationEnvelope, type ContinuationRefusal, type DurableGate } from '../runtime/continuation.js';
+import { type EffectAdapter, type GateResolution } from '../runtime/durable-execution.js';
 /** A single trace event captured during workflow execution. */
 export interface ExecutionTraceEvent {
     /** The event type (e.g. "NODE_STARTED", "NODE_COMPLETED"). */
@@ -36,8 +38,43 @@ export interface TraceSummary {
     /** Wall-clock duration from first to last trace event, in milliseconds. */
     totalDurationMs: number;
 }
-/** Result returned after executing a workflow from a file. */
-export interface ExecuteWorkflowResult {
+/** One execution-scoped request accepted by the public workflow executor. */
+export interface WorkflowExecutionRequest {
+    /** Stable coordinator-owned identity for the complete durable run. */
+    runId: string;
+    /**
+     * Coordinator-verified identity of the complete executable artifact closure.
+     * Required for durable yield or resume; Flow Weaver never substitutes a
+     * workflow-source hash for whole-bundle evidence.
+     */
+    bundleDigest?: string;
+    filePath: string;
+    params?: Record<string, unknown>;
+    workflowName?: string;
+    production?: boolean;
+    includeTrace?: boolean;
+    mocks?: FwMockConfig;
+    debugController?: DebugController;
+    onEvent?: (event: ExecutionTraceEvent) => void;
+    externalNodeTypes?: TExternalNodeType[];
+    /** Strict continuation input from a previously committed yielded outcome. */
+    continuation?: string | unknown;
+    /** Single durable resolution for the continuation's exact gate. */
+    resolution?: GateResolution;
+    /** Recovery contract for explicitly declared effect nodes. */
+    effectAdapter?: EffectAdapter;
+    /**
+     * Parent-owned cooperative cancellation signal for this execution.
+     *
+     * Flow Weaver observes cancellation at generated node boundaries, nested
+     * scopes and engine-owned waits. A node that ignores cancellation is not
+     * preempted. A hard stop requires a parent-owned process boundary.
+     */
+    abortSignal?: AbortSignal;
+}
+/** Result returned after executing a workflow request. */
+export interface CompletedExecutionOutcome {
+    readonly kind: 'completed';
     /** The return value of the executed workflow function. */
     result: unknown;
     /** The name of the exported function that was executed. */
@@ -49,30 +86,31 @@ export interface ExecuteWorkflowResult {
     /** Summary of trace events, included when `includeTrace` is enabled. */
     summary?: TraceSummary;
 }
+export interface YieldedExecutionOutcome {
+    readonly kind: 'yielded';
+    readonly gate: DurableGate;
+    readonly continuation: ContinuationEnvelope;
+    readonly functionName: string;
+    readonly executionTime: number;
+    readonly trace?: ExecutionTraceEvent[];
+    readonly summary?: TraceSummary;
+}
+export type WorkflowExecutionOutcome = CompletedExecutionOutcome | YieldedExecutionOutcome;
+export declare class ContinuationRefusalError extends Error {
+    readonly refusal: ContinuationRefusal;
+    readonly name = "ContinuationRefusalError";
+    constructor(refusal: ContinuationRefusal);
+}
 /**
  * Compiles and executes a workflow from a TypeScript source file.
  * Copies the source to a temp file, compiles all workflows in-place (preserving sibling
  * functions for workflow composition), injects a trace-capturing debugger, and dynamically
  * imports and runs the target workflow function.
- * @param filePath - Path to the workflow `.ts` source file.
- * @param params - Parameters to pass to the workflow function.
- * @param options - Execution options.
- * @param options.workflowName - Name of a specific exported workflow function to execute.
- *   If omitted, the first exported function is used.
- * @param options.production - Enable production mode (no debug events). Defaults to `!includeTrace`.
- * @param options.includeTrace - Whether to capture and return execution trace events. Defaults to `true`.
+ * @param request - File, parameters, execution options, and parent-owned signal.
  * @returns The workflow result, function name, execution time, and optional trace.
  * @throws If no exported workflow function is found in the compiled module.
  */
-export declare function executeWorkflowFromFile(filePath: string, params?: Record<string, unknown>, options?: {
-    workflowName?: string;
-    production?: boolean;
-    includeTrace?: boolean;
-    mocks?: FwMockConfig;
-    agentChannel?: AgentChannel;
-    debugController?: DebugController;
-    onEvent?: (event: ExecutionTraceEvent) => void;
-}): Promise<ExecuteWorkflowResult>;
+export declare function executeWorkflow(request: WorkflowExecutionRequest): Promise<WorkflowExecutionOutcome>;
 /** Compute a concise summary from raw trace events. */
 export declare function computeTraceSummary(trace: ExecutionTraceEvent[]): TraceSummary;
 //# sourceMappingURL=workflow-executor.d.ts.map

package/dist/npm-packages.d.ts

@@ -4,7 +4,7 @@
  * Functions for discovering and extracting type information from npm packages
  * that have TypeScript declaration files (.d.ts).
  */
-import type { TDataType } from './ast/types.js';
+import type { TDataType } from './ast/types';
 /**
  * Port definition compatible with TNodeType.ports
  */