agentfootprint 7.8.0 → 7.10.0

package/README.md

@@ -171,7 +171,7 @@ const pipeline = Sequence.create()
 await pipeline.run({ message: 'URGENT: refund dispute on order #4411' });
 ```
 
-The fourth primitive is `Loop` — `Loop.repeat(agent).until(guard).times(5)`, with a mandatory budget guard. And the named patterns from the research literature ship pre-composed from the same four: `selfConsistency` · `reflection` · `debate` · `mapReduce` · `tot` · `swarm`. Because every composition is a flowchart, the structure you wrote is the structure you see in the UI — and the trace spans the whole pipeline, not one agent at a time. [Designing systems of agents ↓](#-build--design-your-agent-or-system-of-agents)
+The fourth primitive is `Loop` — `Loop.repeat(agent).until(guard).times(5)`, with a mandatory budget guard. And the named patterns from the research literature ship pre-composed from the same four: `selfConsistency` · `reflection` · `debate` · `mapReduce` · `tot` · `swarm` · `llmSwarm` (a swarm whose hand-offs an LLM decides). Because every composition is a flowchart, the structure you wrote is the structure you see in the UI — and the trace spans the whole pipeline, not one agent at a time. [Designing systems of agents ↓](#-build--design-your-agent-or-system-of-agents)
 
 ---
 
@@ -753,7 +753,7 @@ The flowchart, recorders, and tests don't change between dev and prod.
 
 **Core**
 - 2 primitives — `LLMCall`, `Agent` (the ReAct loop)
-- 4 control flows — `Sequence`, `Parallel`, `Conditional`, `Loop`
+- 4 control flows — `Sequence`, `Parallel`, `Conditional`, `Loop` (plus `workflow()`, the same sequence with every hand-off type-checked by the compiler)
 - 1 Injection primitive — `defineSkill` / `defineSteering` / `defineInstruction` / `defineFact`
 - 1 reliability gate — `.reliability({ preCheck, postDecide, providers, circuitBreaker, fallback })`
 - 1 tool dispatch primitive — `ToolProvider` (sync OR async) — `staticTools` · `gatedTools` · `skillScopedTools` · or a custom `ToolProvider` that discovers over hubs / MCP / per-tenant catalogs

package/dist/core-flow/Workflow.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * workflow() — sequential steps whose hand-offs are checked by the compiler.
+ *
+ * WHY this exists: `Sequence` is the workhorse for "A, then B, then C",
+ * and every step it accepts has the same shape — takes `{ message }`,
+ * returns `string`. That is exactly right for chaining LLM calls, and
+ * exactly wrong the moment a step wants to hand the next one something
+ * structured: `Sequence` coerces any non-string step output to `''`
+ * (Sequence.ts, the step `outputMapper`), so a step that returns a parsed
+ * ticket silently hands the next step nothing at all. The mistake shows up
+ * as an empty prompt three steps later, at runtime, in production.
+ *
+ * `workflow()` closes that gap from both ends:
+ *
+ *   - **At compile time** — step N's OUTPUT type must be what step N+1
+ *     accepts. A `Runner<{ message: string }, Ticket>` followed by a
+ *     `Runner<{ orderId: string }, string>` does not compile. The chain is
+ *     proven before you run it, not debugged after.
+ *   - **At run time** — a step's value is handed to the next step
+ *     UNCHANGED. Objects stay objects. The one convenience is the house
+ *     convention: a step that returns a `string` feeds the next step's
+ *     `{ message }`, because that is what every LLM runner here wants.
+ *
+ * Pattern: Adapter over footprintjs's `addSubFlowChartNext`, with the
+ *          type-level handoff proof carried by overloads (1–8 steps).
+ * Role:    core-flow/ layer, alongside Sequence/Parallel/Conditional/Loop.
+ *          Pure control flow — no LLM dependency.
+ * Emits:   agentfootprint.composition.enter / exit, reported as kind
+ *          `'Sequence'` — a workflow IS a sequential composition, and
+ *          widening the public `CompositionKind` union would break
+ *          exhaustive switches in consumer code for no behavioural gain.
+ *
+ * THREE HONEST LIMITS, all inherited from the engine and all verified in
+ * `test/core-flow/scenario/Workflow.test.ts` — worth knowing before you
+ * put rich objects on the wire:
+ *
+ *   1. Only PLAIN DATA crosses a step boundary. A value with a prototype
+ *      (Date, Map, Set, a class instance) arrives as `{}`, and `undefined`
+ *      fields are dropped. Send strings, numbers, arrays and plain
+ *      objects; send a timestamp as an ISO string, not a `Date`.
+ *   2. A step must RETURN its output — the value handed forward is the
+ *      step chart's traversal result. A step whose last stage returns
+ *      nothing hands its whole scope forward instead.
+ *   3. The workflow's own input keys stay visible to LATER steps too
+ *      (footprintjs's `getArgs()` inherits the run's arguments). A key the
+ *      previous step actually produced always wins; a key it did NOT
+ *      produce can still be read from the original input rather than
+ *      coming back `undefined`.
+ *
+ * @example  a typed three-step chain
+ * ```ts
+ * interface Ticket { orderId: string; angry: boolean }
+ *
+ * const parse: Runner<{ message: string }, Ticket> = …;
+ * const lookup: Runner<Ticket, { refundUsd: number }> = …;
+ * const reply: Runner<{ refundUsd: number }, string> = …;
+ *
+ * const intake = workflow(parse, lookup, reply);
+ * const answer = await intake.run({ message: 'where is my refund?' });
+ * //    ^? string — the chain's last output type
+ *
+ * workflow(parse, reply); // ✗ compile error: Ticket is not { refundUsd }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.workflow = exports.Workflow = void 0;
+const footprintjs_1 = require("footprintjs");
+const RunnerBase_js_1 = require("../core/RunnerBase.js");
+const AgentRecorder_js_1 = require("../recorders/core/AgentRecorder.js");
+const CompositionRecorder_js_1 = require("../recorders/core/CompositionRecorder.js");
+const ContextRecorder_js_1 = require("../recorders/core/ContextRecorder.js");
+const StreamRecorder_js_1 = require("../recorders/core/StreamRecorder.js");
+const typedEmit_js_1 = require("../recorders/core/typedEmit.js");
+/**
+ * Hand the previous step's value to the next step as its input args.
+ *
+ * `string` → `{ message }` (the house convention). Plain object → itself.
+ * Anything else is a broken hand-off and says so loudly: the alternative
+ * is an empty input three steps downstream with nothing pointing back
+ * here.
+ */
+function toStepArgs(value, stepNumber) {
+    if (typeof value === 'string')
+        return { message: value };
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        return { ...value };
+    }
+    const got = value === null ? 'null' : Array.isArray(value) ? 'an array' : typeof value;
+    throw new Error(`workflow: step ${stepNumber - 1} handed forward ${got}, but step ${stepNumber} needs an ` +
+        'object (or a string, which arrives as { message }). Make each step return its output.');
+}
+/**
+ * A sequential composition that passes values through untouched. Build one
+ * with {@link workflow} — that factory carries the type-level chain proof.
+ */
+class Workflow extends RunnerBase_js_1.RunnerBase {
+    name;
+    id;
+    steps;
+    opts;
+    currentRunContext = {
+        runStartMs: 0,
+        runId: 'pending',
+        compositionPath: [],
+    };
+    constructor(steps, opts = {}) {
+        super();
+        if (steps.length === 0) {
+            throw new Error('Workflow: must have at least one step');
+        }
+        this.opts = opts;
+        this.name = opts.name ?? 'Workflow';
+        this.id = opts.id ?? 'workflow';
+        this.steps = steps;
+        // Eager chart construction — see `RunnerBase.initChart` JSDoc.
+        this.initChart(() => this.buildChart());
+    }
+    async run(input, options) {
+        const executor = this.createExecutor();
+        this.lastExecutor = executor;
+        const result = await executor.run({ input: { ...input }, ...(options ?? {}) });
+        return this.finalizeResult(executor, result);
+    }
+    async resume(checkpoint, input, options) {
+        this.emitPauseResume(checkpoint, input);
+        const executor = this.createExecutor();
+        this.lastExecutor = executor;
+        const result = await executor.resume(checkpoint, input, options);
+        return this.finalizeResult(executor, result);
+    }
+    createExecutor() {
+        this.currentRunContext = {
+            runStartMs: Date.now(),
+            runId: (0, RunnerBase_js_1.makeRunId)(),
+            compositionPath: [`Workflow:${this.id}`],
+        };
+        const executor = new footprintjs_1.FlowChartExecutor(this.getSpec());
+        const dispatcher = this.getDispatcher();
+        const getRunCtx = () => this.currentRunContext;
+        executor.attachCombinedRecorder(new ContextRecorder_js_1.ContextRecorder({ dispatcher, getRunContext: getRunCtx }));
+        executor.attachCombinedRecorder((0, StreamRecorder_js_1.streamRecorder)({ dispatcher, getRunContext: getRunCtx }));
+        executor.attachCombinedRecorder((0, AgentRecorder_js_1.agentRecorder)({ dispatcher, getRunContext: getRunCtx }));
+        executor.attachCombinedRecorder((0, CompositionRecorder_js_1.compositionRecorder)({ dispatcher, getRunContext: getRunCtx }));
+        for (const r of this.attachedRecorders)
+            executor.attachCombinedRecorder(r);
+        return executor;
+    }
+    finalizeResult(executor, result) {
+        const paused = this.detectPause(executor, result);
+        if (paused)
+            return paused;
+        if (result instanceof Error)
+            throw result;
+        return result;
+    }
+    buildChart() {
+        const steps = this.steps;
+        const compositionId = this.id;
+        const compositionName = this.name;
+        const seed = (scope) => {
+            // The workflow's own input IS step 1's input — no unwrapping, no
+            // re-wrapping; that is the whole point of the typed chain.
+            scope.current = scope.$getArgs();
+            (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.composition.enter', {
+                kind: 'Sequence',
+                id: compositionId,
+                name: compositionName,
+                childCount: steps.length,
+            });
+        };
+        // Root description prefix `Sequence:` is the taxonomy marker every
+        // consumer (Lens, FlowchartRecorder.mapTopologyToSteps) already reads.
+        let builder = (0, footprintjs_1.flowChart)('Seed', seed, 'seed', {
+            ...(this.opts.structureRecorders !== undefined && {
+                structureRecorders: [...this.opts.structureRecorders],
+            }),
+            description: `Sequence: ${steps.length}-step typed workflow`,
+        });
+        steps.forEach((step, index) => {
+            const stepNumber = index + 1;
+            builder = builder.addSubFlowChartNext(`step-${stepNumber}`, step.getSpec(), `Step ${stepNumber}`, {
+                inputMapper: (parent) => toStepArgs(parent.current, stepNumber),
+                // Untouched: whatever the step's chart returned is what the next
+                // step (or the caller) receives. No string coercion.
+                outputMapper: (sfOutput) => ({ current: sfOutput }),
+            });
+        });
+        builder = builder.addFunction('Finalize', (scope) => {
+            (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.composition.exit', {
+                kind: 'Sequence',
+                id: compositionId,
+                name: compositionName,
+                status: 'ok',
+                durationMs: Date.now() - this.currentRunContext.runStartMs,
+            });
+            return scope.current;
+        }, 'finalize', 'Workflow finalize');
+        return builder.build();
+    }
+}
+exports.Workflow = Workflow;
+function workflow(...steps) {
+    if (steps.length === 0) {
+        throw new Error('workflow(): needs at least one step');
+    }
+    return new Workflow(steps);
+}
+exports.workflow = workflow;
+//# sourceMappingURL=Workflow.js.map

package/dist/core-flow/Workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Workflow.js","sourceRoot":"","sources":["../../src/core-flow/Workflow.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;;;AAEH,6CAQqB;AAIrB,yDAA8D;AAC9D,yEAAmE;AACnE,qFAA+E;AAC/E,6EAAuE;AACvE,2EAAqE;AACrE,iEAA2D;AAoC3D;;;;;;;GAOG;AACH,SAAS,UAAU,CAAC,KAAc,EAAE,UAAkB;IACpD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACzD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzE,OAAO,EAAE,GAAI,KAAiC,EAAE,CAAC;IACnD,CAAC;IACD,MAAM,GAAG,GAAG,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC;IACvF,MAAM,IAAI,KAAK,CACb,kBAAkB,UAAU,GAAG,CAAC,mBAAmB,GAAG,cAAc,UAAU,YAAY;QACxF,uFAAuF,CAC1F,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAa,QAAsD,SAAQ,0BAAqB;IACrF,IAAI,CAAS;IACb,EAAE,CAAS;IACH,KAAK,CAAqB;IAC1B,IAAI,CAAkB;IAE/B,iBAAiB,GAAe;QACtC,UAAU,EAAE,CAAC;QACb,KAAK,EAAE,SAAS;QAChB,eAAe,EAAE,EAAE;KACpB,CAAC;IAEF,YAAY,KAAyB,EAAE,OAAwB,EAAE;QAC/D,KAAK,EAAE,CAAC;QACR,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;QAC3D,CAAC;QACD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,UAAU,CAAC;QACpC,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,EAAE,IAAI,UAAU,CAAC;QAChC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,+DAA+D;QAC/D,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,KAAU,EAAE,OAAoB;QACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;QACvC,IAAI,CAAC,YAAY,GAAG,QAAQ,CAAC;QAC7B,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,EAAE,GAAG,KAAK,EAAE,EAAE,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;QAC/E,OAAO,IAAI,CAAC,cAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC/C,CAAC;IAED,KAAK,CAAC,MAAM,CACV,UAA+B,EAC/B,KAAe,EACf,OAAoB;QAEpB,IAAI,CAAC,eAAe,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;QACvC,IAAI,CAAC,YAAY,GAAG,QAAQ,CAAC;QAC7B,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;QACjE,OAAO,IAAI,CAAC,cAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC/C,CAAC;IAEO,cAAc;QACpB,IAAI,CAAC,iBAAiB,GAAG;YACvB,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE;YACtB,KAAK,EAAE,IAAA,yBAAS,GAAE;YAClB,eAAe,EAAE,CAAC,YAAY,IAAI,CAAC,EAAE,EAAE,CAAC;SACzC,CAAC;QAEF,MAAM,QAAQ,GAAG,IAAI,+BAAiB,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QACvD,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;QACxC,MAAM,SAAS,GAAG,GAAe,EAAE,CAAC,IAAI,CAAC,iBAAiB,CAAC;QAE3D,QAAQ,CAAC,sBAAsB,CAAC,IAAI,oCAAe,CAAC,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;QAC/F,QAAQ,CAAC,sBAAsB,CAAC,IAAA,kCAAc,EAAC,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;QAC1F,QAAQ,CAAC,sBAAsB,CAAC,IAAA,gCAAa,EAAC,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;QACzF,QAAQ,CAAC,sBAAsB,CAAC,IAAA,4CAAmB,EAAC,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;QAC/F,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,iBAAiB;YAAE,QAAQ,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC;QAC3E,OAAO,QAAQ,CAAC;IAClB,CAAC;IAEO,cAAc,CAAC,QAA2B,EAAE,MAAe;QACjE,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAClD,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;QAC1B,IAAI,MAAM,YAAY,KAAK;YAAE,MAAM,MAAM,CAAC;QAC1C,OAAO,MAAc,CAAC;IACxB,CAAC;IAEO,UAAU;QAChB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACzB,MAAM,aAAa,GAAG,IAAI,CAAC,EAAE,CAAC;QAC9B,MAAM,eAAe,GAAG,IAAI,CAAC,IAAI,CAAC;QAElC,MAAM,IAAI,GAAG,CAAC,KAAgC,EAAE,EAAE;YAChD,iEAAiE;YACjE,2DAA2D;YAC3D,KAAK,CAAC,OAAO,GAAG,KAAK,CAAC,QAAQ,EAA2B,CAAC;YAC1D,IAAA,wBAAS,EAAC,KAAK,EAAE,kCAAkC,EAAE;gBACnD,IAAI,EAAE,UAAU;gBAChB,EAAE,EAAE,aAAa;gBACjB,IAAI,EAAE,eAAe;gBACrB,UAAU,EAAE,KAAK,CAAC,MAAM;aACzB,CAAC,CAAC;QACL,CAAC,CAAC;QAEF,mEAAmE;QACnE,uEAAuE;QACvE,IAAI,OAAO,GAAG,IAAA,uBAAS,EAAgB,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE;YAC3D,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,kBAAkB,KAAK,SAAS,IAAI;gBAChD,kBAAkB,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC;aACtD,CAAC;YACF,WAAW,EAAE,aAAa,KAAK,CAAC,MAAM,sBAAsB;SAC7D,CAAC,CAAC;QAEH,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;YAC5B,MAAM,UAAU,GAAG,KAAK,GAAG,CAAC,CAAC;YAC7B,OAAO,GAAG,OAAO,CAAC,mBAAmB,CACnC,QAAQ,UAAU,EAAE,EACpB,IAAI,CAAC,OAAO,EAAE,EACd,QAAQ,UAAU,EAAE,EACpB;gBACE,WAAW,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC;gBAC/D,iEAAiE;gBACjE,qDAAqD;gBACrD,YAAY,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;aACpD,CACF,CAAC;QACJ,CAAC,CAAC,CAAC;QAEH,OAAO,GAAG,OAAO,CAAC,WAAW,CAC3B,UAAU,EACV,CAAC,KAAgC,EAAE,EAAE;YACnC,IAAA,wBAAS,EAAC,KAAK,EAAE,iCAAiC,EAAE;gBAClD,IAAI,EAAE,UAAU;gBAChB,EAAE,EAAE,aAAa;gBACjB,IAAI,EAAE,eAAe;gBACrB,MAAM,EAAE,IAAI;gBACZ,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,iBAAiB,CAAC,UAAU;aAC3D,CAAC,CAAC;YACH,OAAO,KAAK,CAAC,OAAO,CAAC;QACvB,CAAC,EACD,UAAU,EACV,mBAAmB,CACpB,CAAC;QAEF,OAAO,OAAO,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;CACF;AAjID,4BAiIC;AA+ED,SAAgB,QAAQ,CAAC,GAAG,KAAyB;IACnD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,IAAI,QAAQ,CAAC,KAAK,CAA2B,CAAC;AACvD,CAAC;AALD,4BAKC"}

package/dist/embedders/index.js

@@ -24,6 +24,35 @@ var __importStar = (this && this.__importStar) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.staticEmbedder = exports.localEmbedder = exports.openaiEmbedder = void 0;
+/**
+ * Native output size of every OpenAI embedding model, so `.dimensions` reports
+ * the truth instead of one hard-coded guess.
+ *
+ * Sources: OpenAI embeddings guide — text-embedding-3-small "By default, the
+ * length of the embedding vector is 1536", text-embedding-3-large "3072"
+ * (https://developers.openai.com/api/docs/guides/embeddings); Microsoft Learn's
+ * Azure OpenAI model table, "Output Dimensions" column, for ada-002 = 1,536
+ * (https://learn.microsoft.com/en-us/azure/ai-foundry/openai/concepts/models).
+ */
+const NATIVE_DIMENSIONS = {
+    'text-embedding-3-small': 1536,
+    'text-embedding-3-large': 3072,
+    'text-embedding-ada-002': 1536,
+};
+/**
+ * OpenAI's hosted embeddings endpoint.
+ *
+ * `.dimensions` is the length callers WILL get back, never an assumption:
+ * an explicit `{ dimensions }` is sent to the API and reported; otherwise the
+ * model's documented native size is reported. A model outside
+ * {@link NATIVE_DIMENSIONS} (a gateway, a self-hosted model behind `baseURL`,
+ * an Azure deployment name, a future OpenAI model) has no size this library can
+ * know, so it is a construction-time error rather than a guess that a vector
+ * store would silently trust.
+ *
+ * @throws if there is no API key, or if `model` is unknown and `dimensions`
+ *         was not supplied.
+ */
 function openaiEmbedder(options = {}) {
     const apiKey = options.apiKey ??
         (typeof process !== 'undefined' ? process.env?.['OPENAI_API_KEY'] : undefined);
@@ -31,13 +60,22 @@ function openaiEmbedder(options = {}) {
         throw new Error('openaiEmbedder: no API key — set OPENAI_API_KEY or pass { apiKey }.');
     }
     const model = options.model ?? 'text-embedding-3-small';
-    const dimensions = options.dimensions ?? 1536;
+    // Only an EXPLICIT request is sent. Defaulting it and sending that would
+    // break ada-002 (which rejects the parameter) for callers who asked for
+    // nothing — the request body stays byte-identical unless you opt in.
+    const requested = options.dimensions;
+    const dimensions = requested ?? NATIVE_DIMENSIONS[model];
+    if (dimensions === undefined) {
+        throw new Error(`openaiEmbedder: unknown model '${model}' — its vector length is not something this ` +
+            `library can know, and reporting a wrong .dimensions silently corrupts a vector store. ` +
+            `Pass { dimensions } with the length that model returns.`);
+    }
     const url = `${options.baseURL ?? 'https://api.openai.com/v1'}/embeddings`;
     async function call(input, signal) {
         const res = await fetch(url, {
             method: 'POST',
             headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` },
-            body: JSON.stringify({ model, input }),
+            body: JSON.stringify(requested === undefined ? { model, input } : { model, input, dimensions: requested }),
             ...(signal ? { signal } : {}),
         });
         if (!res.ok)
@@ -61,17 +99,22 @@ function localEmbedder(options = {}) {
     const dimensions = options.dimensions ?? 384;
     const dtype = options.dtype ?? 'q8';
     let pipe;
+    const build = (m) => {
+        if (options.cacheDir && m.env && typeof m.env === 'object') {
+            m.env['cacheDir'] = options.cacheDir;
+        }
+        return m.pipeline('feature-extraction', model, { dtype });
+    };
     const getPipe = () => {
+        const injected = options.backend;
+        if (injected)
+            return (pipe ??= build(injected));
         // Variable specifier so the compiler/bundler does NOT resolve the module at
         // build time — @huggingface/transformers stays an optional peer dep, loaded
-        // only when localEmbedder is actually used.
+        // only when localEmbedder is actually used. A bundler cannot see through
+        // this; bundled apps pass { backend } instead.
         const spec = '@huggingface/transformers';
-        return (pipe ??= Promise.resolve(`${spec}`).then(s => __importStar(require(s))).then((mod) => {
-            const m = mod;
-            if (options.cacheDir)
-                m.env['cacheDir'] = options.cacheDir;
-            return m.pipeline('feature-extraction', model, { dtype });
-        }));
+        return (pipe ??= Promise.resolve(`${spec}`).then(s => __importStar(require(s))).then((mod) => build(mod)));
     };
     return {
         dimensions,
@@ -92,24 +135,29 @@ function staticEmbedder(options = {}) {
     const dimensions = options.dimensions ?? 256;
     const spec = options.module ?? '@yarflam/potion-base-8m';
     let embedFn;
+    // potion-base-8m exports `embed(texts) => Promise<Float32Array[]>` (a batch
+    // async fn, also on its default export). Accept a small set of shapes so
+    // other Model2Vec builds slot in: a named `embed`/`encode` on the module or
+    // its default, or a default export that IS the fn.
+    const pick = (mod, source) => {
+        const m = mod;
+        const d = (m.default ?? {});
+        const fn = m['embed'] ??
+            d['embed'] ??
+            m['encode'] ??
+            d['encode'] ??
+            (typeof m.default === 'function' ? m.default : undefined);
+        if (!fn) {
+            throw new Error(`staticEmbedder: no embed()/encode() export on ${source}. Pass { module } or wrap it in your own Embedder.`);
+        }
+        return fn;
+    };
     const getEmbed = () => {
-        return (embedFn ??= Promise.resolve(`${spec}`).then(s => __importStar(require(s))).then((mod) => {
-            // potion-base-8m exports `embed(texts) => Promise<Float32Array[]>` (a batch
-            // async fn, also on its default export). Accept a small set of shapes so
-            // other Model2Vec builds slot in: a named `embed`/`encode` on the module or
-            // its default, or a default export that IS the fn.
-            const m = mod;
-            const d = (m.default ?? {});
-            const fn = m['embed'] ??
-                d['embed'] ??
-                m['encode'] ??
-                d['encode'] ??
-                (typeof m.default === 'function' ? m.default : undefined);
-            if (!fn) {
-                throw new Error(`staticEmbedder: no embed()/encode() export on '${spec}'. Pass { module } or wrap it in your own Embedder.`);
-            }
-            return fn;
-        }));
+        const injected = options.backend;
+        if (injected) {
+            return (embedFn ??= Promise.resolve(pick(injected, 'the module passed as { backend }')));
+        }
+        return (embedFn ??= Promise.resolve(`${spec}`).then(s => __importStar(require(s))).then((mod) => pick(mod, `'${spec}'`)));
     };
     // Normalize a batch result into number[][] (one row per input). Handles
     // Float32Array[] (potion), number[][], and a single flat vector for the call.

package/dist/embedders/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/embedders/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/embedders/index.ts"],"names":[],"mappings":"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"}

package/dist/esm/core-flow/Workflow.d.ts

@@ -0,0 +1,146 @@
+/**
+ * workflow() — sequential steps whose hand-offs are checked by the compiler.
+ *
+ * WHY this exists: `Sequence` is the workhorse for "A, then B, then C",
+ * and every step it accepts has the same shape — takes `{ message }`,
+ * returns `string`. That is exactly right for chaining LLM calls, and
+ * exactly wrong the moment a step wants to hand the next one something
+ * structured: `Sequence` coerces any non-string step output to `''`
+ * (Sequence.ts, the step `outputMapper`), so a step that returns a parsed
+ * ticket silently hands the next step nothing at all. The mistake shows up
+ * as an empty prompt three steps later, at runtime, in production.
+ *
+ * `workflow()` closes that gap from both ends:
+ *
+ *   - **At compile time** — step N's OUTPUT type must be what step N+1
+ *     accepts. A `Runner<{ message: string }, Ticket>` followed by a
+ *     `Runner<{ orderId: string }, string>` does not compile. The chain is
+ *     proven before you run it, not debugged after.
+ *   - **At run time** — a step's value is handed to the next step
+ *     UNCHANGED. Objects stay objects. The one convenience is the house
+ *     convention: a step that returns a `string` feeds the next step's
+ *     `{ message }`, because that is what every LLM runner here wants.
+ *
+ * Pattern: Adapter over footprintjs's `addSubFlowChartNext`, with the
+ *          type-level handoff proof carried by overloads (1–8 steps).
+ * Role:    core-flow/ layer, alongside Sequence/Parallel/Conditional/Loop.
+ *          Pure control flow — no LLM dependency.
+ * Emits:   agentfootprint.composition.enter / exit, reported as kind
+ *          `'Sequence'` — a workflow IS a sequential composition, and
+ *          widening the public `CompositionKind` union would break
+ *          exhaustive switches in consumer code for no behavioural gain.
+ *
+ * THREE HONEST LIMITS, all inherited from the engine and all verified in
+ * `test/core-flow/scenario/Workflow.test.ts` — worth knowing before you
+ * put rich objects on the wire:
+ *
+ *   1. Only PLAIN DATA crosses a step boundary. A value with a prototype
+ *      (Date, Map, Set, a class instance) arrives as `{}`, and `undefined`
+ *      fields are dropped. Send strings, numbers, arrays and plain
+ *      objects; send a timestamp as an ISO string, not a `Date`.
+ *   2. A step must RETURN its output — the value handed forward is the
+ *      step chart's traversal result. A step whose last stage returns
+ *      nothing hands its whole scope forward instead.
+ *   3. The workflow's own input keys stay visible to LATER steps too
+ *      (footprintjs's `getArgs()` inherits the run's arguments). A key the
+ *      previous step actually produced always wins; a key it did NOT
+ *      produce can still be read from the original input rather than
+ *      coming back `undefined`.
+ *
+ * @example  a typed three-step chain
+ * ```ts
+ * interface Ticket { orderId: string; angry: boolean }
+ *
+ * const parse: Runner<{ message: string }, Ticket> = …;
+ * const lookup: Runner<Ticket, { refundUsd: number }> = …;
+ * const reply: Runner<{ refundUsd: number }, string> = …;
+ *
+ * const intake = workflow(parse, lookup, reply);
+ * const answer = await intake.run({ message: 'where is my refund?' });
+ * //    ^? string — the chain's last output type
+ *
+ * workflow(parse, reply); // ✗ compile error: Ticket is not { refundUsd }
+ * ```
+ */
+import { type FlowchartCheckpoint, type RunOptions, type StructureRecorder } from 'footprintjs';
+import type { RunnerPauseOutcome } from '../core/pause.js';
+import type { Runner } from '../core/runner.js';
+import { RunnerBase } from '../core/RunnerBase.js';
+/**
+ * What the NEXT step must accept, given what the previous one returns.
+ *
+ * A `string` output feeds `{ message }` — the convention every runner in
+ * this library already speaks (LLMCall, Agent, Sequence, Swarm). Anything
+ * else is handed over as-is, so the next step's input type must be that
+ * same type.
+ */
+export type NextStepInput<TPreviousOutput> = TPreviousOutput extends string ? {
+    message: string;
+} : TPreviousOutput;
+/** Any runner, viewed only as "a thing with a chart" — the workflow never
+ *  needs a step's own input/output types at run time. */
+type AnyStep = Runner<never, unknown>;
+export interface WorkflowOptions {
+    /** Human-friendly name for events + topology. Default `'Workflow'`. */
+    readonly name?: string;
+    /** Stable id used for topology + events. Default `'workflow'`. */
+    readonly id?: string;
+    /**
+     * Optional build-time recorders passed through to footprintjs's
+     * `flowChart()` factory — they observe this workflow's own nodes (Seed +
+     * one mount per step + Finalize). Not propagated into the mounted step
+     * charts; attach them to each step runner for full coverage.
+     */
+    readonly structureRecorders?: readonly StructureRecorder[];
+}
+/**
+ * A sequential composition that passes values through untouched. Build one
+ * with {@link workflow} — that factory carries the type-level chain proof.
+ */
+export declare class Workflow<TIn extends object = object, TOut = unknown> extends RunnerBase<TIn, TOut> {
+    readonly name: string;
+    readonly id: string;
+    private readonly steps;
+    private readonly opts;
+    private currentRunContext;
+    constructor(steps: readonly AnyStep[], opts?: WorkflowOptions);
+    run(input: TIn, options?: RunOptions): Promise<TOut | RunnerPauseOutcome>;
+    resume(checkpoint: FlowchartCheckpoint, input?: unknown, options?: RunOptions): Promise<TOut | RunnerPauseOutcome>;
+    private createExecutor;
+    private finalizeResult;
+    private buildChart;
+}
+/**
+ * Chain 1–8 runners into one, with every hand-off checked by the compiler.
+ *
+ * Step N's output type must be what step N+1 accepts — a `string` output
+ * feeds the next step's `{ message }` (the house convention), anything
+ * else is handed over as-is. A chain that does not line up is a COMPILE
+ * error, not a silent empty value at run time.
+ *
+ * @example  LLM steps chain as they always have
+ * ```ts
+ * const draft = LLMCall.create({ provider, model }).system('Draft it.').build();
+ * const edit = LLMCall.create({ provider, model }).system('Tighten it.').build();
+ *
+ * const pipeline = workflow(draft, edit);
+ * const text = await pipeline.run({ message: 'a note about refunds' });
+ * ```
+ *
+ * @example  structured hand-offs survive
+ * ```ts
+ * const classify: Runner<{ message: string }, { topic: string }> = …;
+ * const answer: Runner<{ topic: string }, string> = …;
+ *
+ * await workflow(classify, answer).run({ message: 'my card was declined' });
+ * ```
+ */
+export declare function workflow<A extends object, B>(s1: Runner<A, B>): Workflow<A, B>;
+export declare function workflow<A extends object, B, C>(s1: Runner<A, B>, s2: Runner<NextStepInput<B>, C>): Workflow<A, C>;
+export declare function workflow<A extends object, B, C, D>(s1: Runner<A, B>, s2: Runner<NextStepInput<B>, C>, s3: Runner<NextStepInput<C>, D>): Workflow<A, D>;
+export declare function workflow<A extends object, B, C, D, E>(s1: Runner<A, B>, s2: Runner<NextStepInput<B>, C>, s3: Runner<NextStepInput<C>, D>, s4: Runner<NextStepInput<D>, E>): Workflow<A, E>;
+export declare function workflow<A extends object, B, C, D, E, F>(s1: Runner<A, B>, s2: Runner<NextStepInput<B>, C>, s3: Runner<NextStepInput<C>, D>, s4: Runner<NextStepInput<D>, E>, s5: Runner<NextStepInput<E>, F>): Workflow<A, F>;
+export declare function workflow<A extends object, B, C, D, E, F, G>(s1: Runner<A, B>, s2: Runner<NextStepInput<B>, C>, s3: Runner<NextStepInput<C>, D>, s4: Runner<NextStepInput<D>, E>, s5: Runner<NextStepInput<E>, F>, s6: Runner<NextStepInput<F>, G>): Workflow<A, G>;
+export declare function workflow<A extends object, B, C, D, E, F, G, H>(s1: Runner<A, B>, s2: Runner<NextStepInput<B>, C>, s3: Runner<NextStepInput<C>, D>, s4: Runner<NextStepInput<D>, E>, s5: Runner<NextStepInput<E>, F>, s6: Runner<NextStepInput<F>, G>, s7: Runner<NextStepInput<G>, H>): Workflow<A, H>;
+export declare function workflow<A extends object, B, C, D, E, F, G, H, I>(s1: Runner<A, B>, s2: Runner<NextStepInput<B>, C>, s3: Runner<NextStepInput<C>, D>, s4: Runner<NextStepInput<D>, E>, s5: Runner<NextStepInput<E>, F>, s6: Runner<NextStepInput<F>, G>, s7: Runner<NextStepInput<G>, H>, s8: Runner<NextStepInput<H>, I>): Workflow<A, I>;
+export {};