@memberjunction/ai-agents 5.38.0 → 5.40.0

package/dist/pipeline/pipeline-executor.js

@@ -0,0 +1,326 @@
+import { GetOperator, CONTROL_VERBS } from './operators.js';
+import { resolveParams } from './template.js';
+import { sizeOf, previewOf, describeEmptyMatch } from './coerce.js';
+export const MAX_PIPELINE_STAGES = 20;
+export const MAX_MAP_ELEMENTS = 1000;
+export const MAP_CONCURRENCY = 8;
+/** Default wall-clock budget for an entire pipeline (incl. all map/let sub-pipelines). */
+export const DEFAULT_PIPELINE_DEADLINE_MS = 120_000;
+export class PipelineExecutor {
+    constructor(registry, maxStages = MAX_PIPELINE_STAGES, opts = {}) {
+        this.registry = registry;
+        this.maxStages = maxStages;
+        /**
+         * Total bytes produced by every stage anywhere in the tree (incl. map/let sub-pipelines).
+         * INSTANCE state, not shared: a fresh executor is created per pipeline run (see
+         * `base-agent.executePipelineAsStep`), so concurrent agent turns each get their own counter —
+         * this is never read/written across parallel runs. Do NOT make PipelineExecutor a singleton.
+         */
+        this.producedBytes = 0;
+        /** Absolute wall-clock deadline (epoch ms) for this run; set at the start of {@link Execute}. */
+        this.deadlineAt = Number.POSITIVE_INFINITY;
+        this.deadlineMs = opts.deadlineMs ?? DEFAULT_PIPELINE_DEADLINE_MS;
+        this.signal = opts.signal;
+    }
+    /**
+     * Throw if the run has been cancelled or has blown its wall-clock budget. Checked between
+     * top-level stages, before each `map` batch, and before each sub-pipeline stage — so a long
+     * `map` over many elements (or a chain of slow Actions) can't run unbounded. NOTE: this bounds
+     * wall-clock *between* stage invocations; it does not interrupt a single in-flight Action mid-call
+     * (that needs Action-level cancellation — a follow-up once the Action layer accepts an AbortSignal).
+     */
+    checkAbort() {
+        if (this.signal?.aborted) {
+            throw new Error('Pipeline cancelled.');
+        }
+        if (Date.now() >= this.deadlineAt) {
+            throw new Error(`Pipeline exceeded its ${this.deadlineMs}ms time budget. Narrow the work (fewer map elements, smaller fetches) or split across turns.`);
+        }
+    }
+    /** Validate + run a pipeline. Returns a structured result; never throws on stage failure. */
+    async Execute(stages) {
+        const shapeError = this.validateShape(stages);
+        if (shapeError) {
+            return { success: false, finalOutput: null, steps: [], error: shapeError, contextBytesSaved: 0 };
+        }
+        const records = [];
+        const scope = {};
+        let current = null;
+        this.producedBytes = 0;
+        this.deadlineAt = Date.now() + this.deadlineMs;
+        let firstDiagnostic;
+        for (let i = 0; i < stages.length; i++) {
+            const inputValue = current;
+            const inputSize = sizeOf(current);
+            const startedAt = Date.now();
+            const outcome = await this.runStage(stages[i], current, scope);
+            const durationMs = Date.now() - startedAt;
+            // A stage that turns a non-empty array into nothing useful — empty, or all-null
+            // elements (the classic `map` clobber: `map` REPLACES the stream with each iteration's
+            // final value, so a throwaway last sub-stage nulls every row) — is almost always a logic
+            // error. Capture a self-correction hint so the agent fixes it next turn instead of
+            // blindly retrying. Purely informational: it NEVER fails or alters the pipeline.
+            const diagnostic = outcome.success
+                ? stageDegenerationHint(stages[i], inputValue, outcome.output, outcome.toolName, i + 1)
+                : undefined;
+            if (diagnostic && !firstDiagnostic) {
+                firstDiagnostic = diagnostic;
+            }
+            records.push({
+                index: i,
+                toolName: outcome.toolName,
+                providerKind: outcome.providerKind,
+                inputSize,
+                outputSize: sizeOf(outcome.output),
+                durationMs,
+                success: outcome.success,
+                error: outcome.error,
+                diagnostic,
+                logRef: {
+                    providerKind: outcome.providerKind,
+                    actionExecutionLogId: outcome.actionExecutionLogId,
+                    preview: outcome.preview ?? previewOf(outcome.output),
+                },
+            });
+            this.producedBytes += records[records.length - 1].outputSize;
+            if (!outcome.success) {
+                return this.failure(records, i, outcome.toolName, inputSize, outcome.error);
+            }
+            current = outcome.output;
+            scope['$'] = current;
+        }
+        return {
+            success: true,
+            finalOutput: current,
+            steps: records,
+            contextBytesSaved: this.computeSaved(current),
+            // Surface the hint only when the FINAL result is itself degenerate (empty, or all-null
+            // elements); a deliberate empty result mid-pipeline that's later repopulated shouldn't nag.
+            diagnostic: looksDegenerate(current) ? firstDiagnostic : undefined,
+        };
+    }
+    validateShape(stages) {
+        if (!Array.isArray(stages) || stages.length < 1) {
+            return 'A pipeline needs at least 1 stage.';
+        }
+        if (stages.length > this.maxStages) {
+            return `A pipeline may have at most ${this.maxStages} stages (got ${stages.length}).`;
+        }
+        return null;
+    }
+    /** Dispatch one stage. Never throws — converts errors into a failed outcome. */
+    async runStage(stage, current, scope) {
+        try {
+            this.checkAbort(); // deadline/cancellation → failed outcome (caught below), never an uncaught throw
+            if ('tool' in stage) {
+                return await this.runToolStage(stage, current, scope);
+            }
+            if ('map' in stage) {
+                return await this.runMapStage(stage, current, scope);
+            }
+            if ('let' in stage) {
+                return await this.runLetStage(stage, current, scope);
+            }
+            return this.runOperatorStage(stage, current);
+        }
+        catch (e) {
+            return { output: null, success: false, error: e.message, providerKind: 'Transform', toolName: stageVerb(stage) };
+        }
+    }
+    runOperatorStage(stage, current) {
+        const verbs = Object.keys(stage).filter((k) => GetOperator(k));
+        if (verbs.length === 0) {
+            throw new Error(`Stage has no known verb. Keys: ${Object.keys(stage).join(', ')}.`);
+        }
+        if (verbs.length > 1) {
+            throw new Error(`A stage must have exactly one verb, but found: ${verbs.join(', ')}.`);
+        }
+        const op = GetOperator(verbs[0]);
+        const output = op.apply(current, stage[verbs[0]]);
+        return { output, success: true, providerKind: 'Transform', toolName: op.name };
+    }
+    async runToolStage(stage, current, scope) {
+        const toolName = String(stage.tool);
+        const invocable = this.registry.Resolve(toolName);
+        if (!invocable) {
+            throw new Error(`Unknown pipeline tool "${toolName}". Available tools: ${this.registry.ToolNames().join(', ')}.`);
+        }
+        const params = resolveParams(stage.with ?? {}, { ...scope, $: current });
+        if (typeof stage.pipeInto === 'string') {
+            params[stage.pipeInto] = current;
+        }
+        const result = await invocable.invoke(current, params);
+        return {
+            output: result.output,
+            success: result.success,
+            error: result.error,
+            providerKind: invocable.providerKind,
+            toolName,
+            actionExecutionLogId: result.logRef.actionExecutionLogId,
+            preview: result.logRef.preview,
+        };
+    }
+    async runMapStage(stage, current, scope) {
+        const cfg = (stage.map ?? {});
+        const asName = cfg.as ?? 'item';
+        const subStages = cfg.do ?? [];
+        if (!Array.isArray(subStages) || subStages.length === 0) {
+            throw new Error('"map" requires a non-empty "do" sub-pipeline.');
+        }
+        if (!Array.isArray(current)) {
+            throw new Error(`"map" expects an array to iterate, but the upstream value is ${Array.isArray(current) ? 'an array' : typeof current}.`);
+        }
+        if (current.length > MAX_MAP_ELEMENTS) {
+            throw new Error(`"map" capped at ${MAX_MAP_ELEMENTS} elements (got ${current.length}). Narrow upstream with where/first.`);
+        }
+        const failFast = cfg.continueOnError === false;
+        // KNOWN LIMITATION: every element's final value is buffered here before returning. With
+        // MAX_MAP_ELEMENTS=1000 and large per-element outputs this is real memory pressure — keep each
+        // element's final sub-stage SMALL (select/count/grep), not whole fetched pages. A streaming /
+        // chunked map that doesn't materialize the full array is a v2 candidate.
+        const results = new Array(current.length).fill(null);
+        let failures = 0;
+        let firstError;
+        for (let start = 0; start < current.length; start += MAP_CONCURRENCY) {
+            this.checkAbort();
+            const batch = current.slice(start, start + MAP_CONCURRENCY);
+            await Promise.all(batch.map(async (element, j) => {
+                const idx = start + j;
+                const childScope = { ...scope, [asName]: element };
+                const sub = await this.runStages(subStages, element, childScope);
+                if (sub.success) {
+                    results[idx] = sub.value;
+                }
+                else {
+                    failures++;
+                    firstError = firstError ?? sub.error;
+                    results[idx] = null;
+                }
+            }));
+            if (failFast && failures > 0) {
+                throw new Error(`"map" failed on an element: ${firstError}`);
+            }
+        }
+        const summary = failures > 0 ? `${failures} of ${current.length} elements failed (first: ${firstError})` : undefined;
+        return {
+            output: results,
+            success: true,
+            error: summary,
+            providerKind: 'Transform',
+            toolName: `map(${current.length})`,
+            preview: previewOf(results),
+        };
+    }
+    async runLetStage(stage, current, scope) {
+        const cfg = (stage.let ?? {});
+        if (!cfg.name || !Array.isArray(cfg.value) || cfg.value.length === 0) {
+            throw new Error('"let" requires { "name": string, "value": [ sub-stages ] }.');
+        }
+        const sub = await this.runStages(cfg.value, current, { ...scope });
+        if (!sub.success) {
+            throw new Error(`"let ${cfg.name}" failed: ${sub.error}`);
+        }
+        scope[cfg.name] = sub.value; // bind for downstream {{name}}; stream passes through unchanged
+        return { output: current, success: true, providerKind: 'Transform', toolName: `let ${cfg.name}` };
+    }
+    /** Run a sub-pipeline (map/let) with no top-level record-keeping; fails fast internally. */
+    async runStages(stages, initialValue, scope) {
+        let current = initialValue;
+        scope['$'] = current;
+        for (const stage of stages) {
+            const outcome = await this.runStage(stage, current, scope);
+            // Every sub-pipeline stage output is processed server-side and never surfaces to the
+            // LLM directly (only the top-level final value does) — count it toward bytes saved.
+            this.producedBytes += sizeOf(outcome.output);
+            if (!outcome.success) {
+                return { value: null, success: false, error: outcome.error };
+            }
+            current = outcome.output;
+            scope['$'] = current;
+        }
+        return { value: current, success: true };
+    }
+    failure(records, zeroBasedIndex, toolName, inputSize, error) {
+        const message = `Pipeline failed at stage ${zeroBasedIndex + 1} (${toolName}).\n` +
+            `Upstream value size: ${inputSize} bytes\n` +
+            `Error: ${error ?? 'unknown error'}`;
+        return {
+            success: false,
+            finalOutput: null,
+            steps: records,
+            error: message,
+            // 0-based to index straight into `steps` (steps[failedStepIndex] is the failing record).
+            // The human-facing `message` above uses 1-based "stage N" since people count from 1.
+            failedStepIndex: zeroBasedIndex,
+            contextBytesSaved: this.computeSaved(null),
+        };
+    }
+    /**
+     * Bytes the LLM never saw: everything produced anywhere in the tree (top-level + every map/let
+     * sub-pipeline stage) minus the single final value that is returned. Map/let internal fetches
+     * (e.g. full pages fetched per element) are counted here, not just top-level stages.
+     */
+    computeSaved(finalOutput) {
+        return Math.max(0, this.producedBytes - sizeOf(finalOutput));
+    }
+}
+/** Whether a value is "no result" — empty array, empty string, or null. */
+function isEmpty(v) {
+    if (v == null)
+        return true;
+    if (Array.isArray(v))
+        return v.length === 0;
+    if (typeof v === 'string')
+        return v.length === 0;
+    return false;
+}
+/** An object with keys whose values are ALL null — a hollow row (e.g. `select`-ing absent fields). */
+function isAllNullObject(v) {
+    return (v !== null &&
+        typeof v === 'object' &&
+        !Array.isArray(v) &&
+        Object.keys(v).length > 0 &&
+        Object.values(v).every((x) => x == null));
+}
+/** Degenerate = empty, OR a non-empty array whose every element is null / a hollow all-null object. */
+function looksDegenerate(v) {
+    if (isEmpty(v))
+        return true;
+    if (Array.isArray(v) && v.length > 0) {
+        return v.every((el) => el == null || isAllNullObject(el));
+    }
+    return false;
+}
+/**
+ * Self-correction hint for a stage that took a non-empty array and produced nothing useful — purely
+ * informational, never alters execution. Two cases: (1) filtered down to empty (likely a wrong field
+ * name / value casing → list the values present); (2) turned every element into null, the classic
+ * `map` misuse (map REPLACES the stream with each iteration's final value — it does not add a field).
+ */
+function stageDegenerationHint(stage, inputValue, output, toolName, oneBasedIndex) {
+    if (!Array.isArray(inputValue) || inputValue.length === 0) {
+        return undefined;
+    }
+    if (isEmpty(output)) {
+        return `Stage ${oneBasedIndex} ("${toolName}") ${describeEmptyMatch(inputValue)}`;
+    }
+    if (Array.isArray(output) && output.length > 0 && output.every((el) => el == null || isAllNullObject(el))) {
+        const why = 'map' in stage
+            ? ' "map" REPLACES the array with each iteration\'s FINAL sub-stage value — it does NOT add a field to existing rows. Its last sub-stage returned null for every element. To add/keep fields, use select/groupBy directly; use map only for per-element actions.'
+            : ' Check the field name/path — it resolved to null for every element (case-sensitive).';
+        return `Stage ${oneBasedIndex} ("${toolName}") turned ${inputValue.length} item(s) into all-null.${why}`;
+    }
+    return undefined;
+}
+/** Best-effort verb label for a stage (for error messages). */
+function stageVerb(stage) {
+    if ('tool' in stage)
+        return String(stage.tool);
+    if ('map' in stage)
+        return 'map';
+    if ('let' in stage)
+        return 'let';
+    const verbs = Object.keys(stage).filter((k) => !CONTROL_VERBS.has(k));
+    return verbs[0] ?? 'unknown';
+}
+//# sourceMappingURL=pipeline-executor.js.map

package/dist/pipeline/pipeline-executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-executor.js","sourceRoot":"","sources":["../../src/pipeline/pipeline-executor.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,aAAa,EAAiB,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEjE,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AACtC,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;AACrC,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC;AACjC,0FAA0F;AAC1F,MAAM,CAAC,MAAM,4BAA4B,GAAG,OAAO,CAAC;AAqBpD,MAAM,OAAO,gBAAgB;IAazB,YACqB,QAA8B,EAC9B,YAAoB,mBAAmB,EACxD,OAAgC,EAAE;QAFjB,aAAQ,GAAR,QAAQ,CAAsB;QAC9B,cAAS,GAAT,SAAS,CAA8B;QAd5D;;;;;WAKG;QACK,kBAAa,GAAG,CAAC,CAAC;QAC1B,iGAAiG;QACzF,eAAU,GAAG,MAAM,CAAC,iBAAiB,CAAC;QAS1C,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,4BAA4B,CAAC;QAClE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC9B,CAAC;IAED;;;;;;OAMG;IACK,UAAU;QACd,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;QAC3C,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CACX,yBAAyB,IAAI,CAAC,UAAU,8FAA8F,CACzI,CAAC;QACN,CAAC;IACL,CAAC;IAED,6FAA6F;IACtF,KAAK,CAAC,OAAO,CAAC,MAAuB;QACxC,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;QAC9C,IAAI,UAAU,EAAE,CAAC;YACb,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,CAAC,EAAE,CAAC;QACrG,CAAC;QAED,MAAM,OAAO,GAAyB,EAAE,CAAC;QACzC,MAAM,KAAK,GAAkB,EAAE,CAAC;QAChC,IAAI,OAAO,GAAc,IAAI,CAAC;QAC9B,IAAI,CAAC,aAAa,GAAG,CAAC,CAAC;QACvB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC;QAC/C,IAAI,eAAmC,CAAC;QAExC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACrC,MAAM,UAAU,GAAG,OAAO,CAAC;YAC3B,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;YAClC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAC7B,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;YAC/D,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;YAC1C,gFAAgF;YAChF,uFAAuF;YACvF,yFAAyF;YACzF,mFAAmF;YACnF,iFAAiF;YACjF,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO;gBAC9B,CAAC,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC;gBACvF,CAAC,CAAC,SAAS,CAAC;YAChB,IAAI,UAAU,IAAI,CAAC,eAAe,EAAE,CAAC;gBACjC,eAAe,GAAG,UAAU,CAAC;YACjC,CAAC;YACD,OAAO,CAAC,IAAI,CAAC;gBACT,KAAK,EAAE,CAAC;gBACR,QAAQ,EAAE,OAAO,CAAC,QAAQ;gBAC1B,YAAY,EAAE,OAAO,CAAC,YAAY;gBAClC,SAAS;gBACT,UAAU,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;gBAClC,UAAU;gBACV,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,UAAU;gBACV,MAAM,EAAE;oBACJ,YAAY,EAAE,OAAO,CAAC,YAAY;oBAClC,oBAAoB,EAAE,OAAO,CAAC,oBAAoB;oBAClD,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC;iBACxD;aACJ,CAAC,CAAC;YACH,IAAI,CAAC,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC;YAC7D,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;gBACnB,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,EAAE,OAAO,CAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;YAChF,CAAC;YACD,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;YACzB,KAAK,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC;QACzB,CAAC;QAED,OAAO;YACH,OAAO,EAAE,IAAI;YACb,WAAW,EAAE,OAAO;YACpB,KAAK,EAAE,OAAO;YACd,iBAAiB,EAAE,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC;YAC7C,uFAAuF;YACvF,4FAA4F;YAC5F,UAAU,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS;SACrE,CAAC;IACN,CAAC;IAEO,aAAa,CAAC,MAAuB;QACzC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC9C,OAAO,oCAAoC,CAAC;QAChD,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;YACjC,OAAO,+BAA+B,IAAI,CAAC,SAAS,gBAAgB,MAAM,CAAC,MAAM,IAAI,CAAC;QAC1F,CAAC;QACD,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,gFAAgF;IACxE,KAAK,CAAC,QAAQ,CAAC,KAAoB,EAAE,OAAkB,EAAE,KAAoB;QACjF,IAAI,CAAC;YACD,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,iFAAiF;YACpG,IAAI,MAAM,IAAI,KAAK,EAAE,CAAC;gBAClB,OAAO,MAAM,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;YAC1D,CAAC;YACD,IAAI,KAAK,IAAI,KAAK,EAAE,CAAC;gBACjB,OAAO,MAAM,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;YACzD,CAAC;YACD,IAAI,KAAK,IAAI,KAAK,EAAE,CAAC;gBACjB,OAAO,MAAM,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;YACzD,CAAC;YACD,OAAO,IAAI,CAAC,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACjD,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACT,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAG,CAAW,CAAC,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;QAChI,CAAC;IACL,CAAC;IAEO,gBAAgB,CAAC,KAAoB,EAAE,OAAkB;QAC7D,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/D,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,kCAAkC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACxF,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CAAC,kDAAkD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC3F,CAAC;QACD,MAAM,EAAE,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAE,CAAC;QAClC,MAAM,MAAM,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAClD,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC;IACnF,CAAC;IAEO,KAAK,CAAC,YAAY,CAAC,KAAoB,EAAE,OAAkB,EAAE,KAAoB;QACrF,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACpC,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAClD,IAAI,CAAC,SAAS,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,0BAA0B,QAAQ,uBAAuB,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACtH,CAAC;QACD,MAAM,MAAM,GAAG,aAAa,CAAE,KAAK,CAAC,IAAgC,IAAI,EAAE,EAAE,EAAE,GAAG,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;QACtG,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACrC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC;QACrC,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACvD,OAAO;YACH,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,YAAY,EAAE,SAAS,CAAC,YAAY;YACpC,QAAQ;YACR,oBAAoB,EAAE,MAAM,CAAC,MAAM,CAAC,oBAAoB;YACxD,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO;SACjC,CAAC;IACN,CAAC;IAEO,KAAK,CAAC,WAAW,CAAC,KAAoB,EAAE,OAAkB,EAAE,KAAoB;QACpF,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,IAAI,EAAE,CAAqE,CAAC;QAClG,MAAM,MAAM,GAAG,GAAG,CAAC,EAAE,IAAI,MAAM,CAAC;QAChC,MAAM,SAAS,GAAG,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC;QAC/B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtD,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;QACrE,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,gEAAgE,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,OAAO,GAAG,CAAC,CAAC;QAC7I,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,GAAG,gBAAgB,EAAE,CAAC;YACpC,MAAM,IAAI,KAAK,CAAC,mBAAmB,gBAAgB,kBAAkB,OAAO,CAAC,MAAM,sCAAsC,CAAC,CAAC;QAC/H,CAAC;QAED,MAAM,QAAQ,GAAG,GAAG,CAAC,eAAe,KAAK,KAAK,CAAC;QAC/C,wFAAwF;QACxF,+FAA+F;QAC/F,8FAA8F;QAC9F,yEAAyE;QACzE,MAAM,OAAO,GAAgB,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAClE,IAAI,QAAQ,GAAG,CAAC,CAAC;QACjB,IAAI,UAA8B,CAAC;QAEnC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,EAAE,KAAK,IAAI,eAAe,EAAE,CAAC;YACnE,IAAI,CAAC,UAAU,EAAE,CAAC;YAClB,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,eAAe,CAAC,CAAC;YAC5D,MAAM,OAAO,CAAC,GAAG,CACb,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE;gBAC3B,MAAM,GAAG,GAAG,KAAK,GAAG,CAAC,CAAC;gBACtB,MAAM,UAAU,GAAkB,EAAE,GAAG,KAAK,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;gBAClE,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;gBACjE,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;oBACd,OAAO,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC;gBAC7B,CAAC;qBAAM,CAAC;oBACJ,QAAQ,EAAE,CAAC;oBACX,UAAU,GAAG,UAAU,IAAI,GAAG,CAAC,KAAK,CAAC;oBACrC,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;gBACxB,CAAC;YACL,CAAC,CAAC,CACL,CAAC;YACF,IAAI,QAAQ,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;gBAC3B,MAAM,IAAI,KAAK,CAAC,+BAA+B,UAAU,EAAE,CAAC,CAAC;YACjE,CAAC;QACL,CAAC;QAED,MAAM,OAAO,GAAG,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,QAAQ,OAAO,OAAO,CAAC,MAAM,4BAA4B,UAAU,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;QACrH,OAAO;YACH,MAAM,EAAE,OAAO;YACf,OAAO,EAAE,IAAI;YACb,KAAK,EAAE,OAAO;YACd,YAAY,EAAE,WAAW;YACzB,QAAQ,EAAE,OAAO,OAAO,CAAC,MAAM,GAAG;YAClC,OAAO,EAAE,SAAS,CAAC,OAAO,CAAC;SAC9B,CAAC;IACN,CAAC;IAEO,KAAK,CAAC,WAAW,CAAC,KAAoB,EAAE,OAAkB,EAAE,KAAoB;QACpF,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,IAAI,EAAE,CAA+C,CAAC;QAC5E,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACnE,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;QACnF,CAAC;QACD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;QACnE,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,QAAQ,GAAG,CAAC,IAAI,aAAa,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;QAC9D,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,gEAAgE;QAC7F,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;IACtG,CAAC;IAED,4FAA4F;IACpF,KAAK,CAAC,SAAS,CACnB,MAAuB,EACvB,YAAuB,EACvB,KAAoB;QAEpB,IAAI,OAAO,GAAG,YAAY,CAAC;QAC3B,KAAK,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC;QACrB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YACzB,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;YAC3D,qFAAqF;YACrF,oFAAoF;YACpF,IAAI,CAAC,aAAa,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAC7C,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;gBACnB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;YACjE,CAAC;YACD,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;YACzB,KAAK,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC;QACzB,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC7C,CAAC;IAEO,OAAO,CACX,OAA6B,EAC7B,cAAsB,EACtB,QAAgB,EAChB,SAAiB,EACjB,KAAyB;QAEzB,MAAM,OAAO,GACT,4BAA4B,cAAc,GAAG,CAAC,KAAK,QAAQ,MAAM;YACjE,wBAAwB,SAAS,UAAU;YAC3C,UAAU,KAAK,IAAI,eAAe,EAAE,CAAC;QACzC,OAAO;YACH,OAAO,EAAE,KAAK;YACd,WAAW,EAAE,IAAI;YACjB,KAAK,EAAE,OAAO;YACd,KAAK,EAAE,OAAO;YACd,yFAAyF;YACzF,qFAAqF;YACrF,eAAe,EAAE,cAAc;YAC/B,iBAAiB,EAAE,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC;SAC7C,CAAC;IACN,CAAC;IAED;;;;OAIG;IACK,YAAY,CAAC,WAAsB;QACvC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC;IACjE,CAAC;CACJ;AAED,2EAA2E;AAC3E,SAAS,OAAO,CAAC,CAAY;IACzB,IAAI,CAAC,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IAC3B,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC;IAC5C,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC;IACjD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED,sGAAsG;AACtG,SAAS,eAAe,CAAC,CAAY;IACjC,OAAO,CACH,CAAC,KAAK,IAAI;QACV,OAAO,CAAC,KAAK,QAAQ;QACrB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QACjB,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC;QACzB,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,CAC3C,CAAC;AACN,CAAC;AAED,uGAAuG;AACvG,SAAS,eAAe,CAAC,CAAY;IACjC,IAAI,OAAO,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5B,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,IAAI,IAAI,IAAI,eAAe,CAAC,EAAE,CAAC,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;;;GAKG;AACH,SAAS,qBAAqB,CAC1B,KAAoB,EACpB,UAAqB,EACrB,MAAiB,EACjB,QAAgB,EAChB,aAAqB;IAErB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxD,OAAO,SAAS,CAAC;IACrB,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClB,OAAO,SAAS,aAAa,MAAM,QAAQ,MAAM,kBAAkB,CAAC,UAAU,CAAC,EAAE,CAAC;IACtF,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,IAAI,IAAI,IAAI,eAAe,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;QACxG,MAAM,GAAG,GACL,KAAK,IAAI,KAAK;YACV,CAAC,CAAC,+PAA+P;YACjQ,CAAC,CAAC,sFAAsF,CAAC;QACjG,OAAO,SAAS,aAAa,MAAM,QAAQ,aAAa,UAAU,CAAC,MAAM,0BAA0B,GAAG,EAAE,CAAC;IAC7G,CAAC;IACD,OAAO,SAAS,CAAC;AACrB,CAAC;AAED,+DAA+D;AAC/D,SAAS,SAAS,CAAC,KAAoB;IACnC,IAAI,MAAM,IAAI,KAAK;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/C,IAAI,KAAK,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC;IACjC,IAAI,KAAK,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC;IACjC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACtE,OAAO,KAAK,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC;AACjC,CAAC"}

package/dist/pipeline/pipeline-registry.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Per-execution registry that resolves a pipeline step's tool name to a
+ * {@link PipelineInvocable}. Built fresh for each pipeline run by the agent, which knows
+ * the available Actions, artifact tools, and built-in transforms.
+ *
+ * Lookup is case-insensitive. Names share one namespace across all three substrates, so
+ * a collision (e.g. an Action named the same as a transform) is a registration-time error
+ * rather than a silent ambiguity at resolve time.
+ *
+ * @module @memberjunction/ai-agents
+ */
+import { PipelineInvocable } from './pipeline.types.js';
+export declare class PipelineToolRegistry {
+    private byName;
+    /** Register an invocable. Throws if its name collides with an already-registered tool. */
+    Register(invocable: PipelineInvocable): void;
+    /** Register many invocables (e.g. all built-in transforms). */
+    RegisterAll(invocables: readonly PipelineInvocable[]): void;
+    /** Resolve a tool name (case-insensitive), or undefined if unknown. */
+    Resolve(name: string): PipelineInvocable | undefined;
+    /** All registered tool names, in registration order — for error messages / tool docs. */
+    ToolNames(): string[];
+}
+//# sourceMappingURL=pipeline-registry.d.ts.map

package/dist/pipeline/pipeline-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-registry.d.ts","sourceRoot":"","sources":["../../src/pipeline/pipeline-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,qBAAa,oBAAoB;IAC7B,OAAO,CAAC,MAAM,CAAwC;IAEtD,0FAA0F;IACnF,QAAQ,CAAC,SAAS,EAAE,iBAAiB,GAAG,IAAI;IAYnD,+DAA+D;IACxD,WAAW,CAAC,UAAU,EAAE,SAAS,iBAAiB,EAAE,GAAG,IAAI;IAIlE,uEAAuE;IAChE,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAI3D,yFAAyF;IAClF,SAAS,IAAI,MAAM,EAAE;CAG/B"}

package/dist/pipeline/pipeline-registry.js

@@ -0,0 +1,28 @@
+export class PipelineToolRegistry {
+    constructor() {
+        this.byName = new Map();
+    }
+    /** Register an invocable. Throws if its name collides with an already-registered tool. */
+    Register(invocable) {
+        const key = invocable.toolName.trim().toLowerCase();
+        const existing = this.byName.get(key);
+        if (existing) {
+            throw new Error(`Pipeline tool name collision: "${invocable.toolName}" is registered by both the ` +
+                `${existing.providerKind} and ${invocable.providerKind} providers.`);
+        }
+        this.byName.set(key, invocable);
+    }
+    /** Register many invocables (e.g. all built-in transforms). */
+    RegisterAll(invocables) {
+        invocables.forEach((i) => this.Register(i));
+    }
+    /** Resolve a tool name (case-insensitive), or undefined if unknown. */
+    Resolve(name) {
+        return this.byName.get(name.trim().toLowerCase());
+    }
+    /** All registered tool names, in registration order — for error messages / tool docs. */
+    ToolNames() {
+        return [...this.byName.values()].map((i) => i.toolName);
+    }
+}
+//# sourceMappingURL=pipeline-registry.js.map

package/dist/pipeline/pipeline-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-registry.js","sourceRoot":"","sources":["../../src/pipeline/pipeline-registry.ts"],"names":[],"mappings":"AAaA,MAAM,OAAO,oBAAoB;IAAjC;QACY,WAAM,GAAG,IAAI,GAAG,EAA6B,CAAC;IA6B1D,CAAC;IA3BG,0FAA0F;IACnF,QAAQ,CAAC,SAA4B;QACxC,MAAM,GAAG,GAAG,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACpD,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACtC,IAAI,QAAQ,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CACX,kCAAkC,SAAS,CAAC,QAAQ,8BAA8B;gBAC9E,GAAG,QAAQ,CAAC,YAAY,QAAQ,SAAS,CAAC,YAAY,aAAa,CAC1E,CAAC;QACN,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IACpC,CAAC;IAED,+DAA+D;IACxD,WAAW,CAAC,UAAwC;QACvD,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,CAAC;IAED,uEAAuE;IAChE,OAAO,CAAC,IAAY;QACvB,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;IACtD,CAAC;IAED,yFAAyF;IAClF,SAAS;QACZ,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IAC5D,CAAC;CACJ"}

package/dist/pipeline/pipeline.types.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @fileoverview Core contract for Agent Pipelines — a server-side dataflow the agent authors and
+ * the server runs, so intermediate values never enter the LLM context window.
+ *
+ * The pipe carries a {@link PipeValue} (a JSON value), PowerShell-style, NOT a string: stages bind
+ * to object properties instead of re-parsing text. Capabilities (Actions / artifact tools) are
+ * effectful async stages behind {@link PipelineInvocable}; pure operators (where/select/sort/…) are
+ * synchronous value→value functions; `map`/`let` are control constructs handled by the executor.
+ *
+ * @module @memberjunction/ai-agents
+ */
+/** A JSON value — the medium that flows between pipeline stages. */
+export type PipeValue = null | boolean | number | string | PipeValue[] | {
+    [key: string]: PipeValue;
+};
+/** Which substrate produced a step. DB persistence collapses operator/map/let to 'Transform'. */
+export type PipelineProviderKind = 'Action' | 'ArtifactTool' | 'Transform';
+/** Pointer from a step back to its underlying log (polymorphic by substrate). */
+export interface PipelineStepLogRef {
+    providerKind: PipelineProviderKind;
+    /** ActionExecutionLog row ID for Action steps; undefined otherwise. */
+    actionExecutionLogId?: string;
+    /** Truncated text preview of the step's output, for steps with no DB log. */
+    preview?: string;
+}
+/** Result of invoking a single capability stage. */
+export interface PipelineStepResult {
+    output: PipeValue;
+    success: boolean;
+    error?: string;
+    logRef: PipelineStepLogRef;
+}
+/**
+ * A capability stage — an Action or artifact tool. Effectful + async. The executor resolves
+ * templating and `pipeInto` into `params` before calling `invoke`; the raw upstream `input` is
+ * passed too for providers that want it.
+ */
+export interface PipelineInvocable {
+    readonly toolName: string;
+    readonly providerKind: PipelineProviderKind;
+    /** Whether this can be a pipeline's first stage (produces data without upstream). */
+    readonly isSource: boolean;
+    invoke(input: PipeValue, params: Record<string, unknown>): Promise<PipelineStepResult>;
+}
+/** A pure operator — value in, value out. May throw (executor catches and reports the stage). */
+export interface PipelineOperator {
+    readonly name: string;
+    readonly description: string;
+    /** JSON-schema-ish arg description for the tool docs. */
+    readonly argsHint: string;
+    apply(input: PipeValue, args: unknown): PipeValue;
+}
+/**
+ * One stage of a pipeline, exactly one verb key + its args, e.g. `{ "where": "Balance > 0" }`,
+ * `{ "tool": "Run View", "with": {...}, "pipeInto": "Body" }`, `{ "map": { "as": "row", "do": [...] } }`.
+ */
+export interface PipelineStage {
+    [verb: string]: unknown;
+}
+/** Per-stage record emitted by the executor; persisted in the pipeline `Tool` run-step's `OutputData`. */
+export interface PipelineStepRecord {
+    index: number;
+    toolName: string;
+    providerKind: PipelineProviderKind;
+    inputSize: number;
+    outputSize: number;
+    durationMs: number;
+    success: boolean;
+    error?: string;
+    logRef: PipelineStepLogRef;
+    /** Non-fatal hint surfaced to the agent (e.g. a stage that filtered a non-empty array to empty). */
+    diagnostic?: string;
+}
+/** Outcome of executing a whole pipeline. */
+export interface PipelineExecutionResult {
+    success: boolean;
+    /** The final stage's value — the ONLY thing returned to the LLM. Null when the pipeline failed. */
+    finalOutput: PipeValue | null;
+    steps: PipelineStepRecord[];
+    /** Agent-facing error message when the pipeline failed (never includes a piped value). */
+    error?: string;
+    /** 0-based index of the failing top-level stage; `steps[failedStepIndex]` is its record. */
+    failedStepIndex?: number;
+    /** Sum of intermediate output byte sizes that never reached the LLM. */
+    contextBytesSaved: number;
+    /** Self-correction hint when the pipeline succeeded but a stage zeroed out a non-empty array. */
+    diagnostic?: string;
+}
+//# sourceMappingURL=pipeline.types.d.ts.map

package/dist/pipeline/pipeline.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.types.d.ts","sourceRoot":"","sources":["../../src/pipeline/pipeline.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,oEAAoE;AACpE,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEtG,iGAAiG;AACjG,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,cAAc,GAAG,WAAW,CAAC;AAE3E,iFAAiF;AACjF,MAAM,WAAW,kBAAkB;IAC/B,YAAY,EAAE,oBAAoB,CAAC;IACnC,uEAAuE;IACvE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,oDAAoD;AACpD,MAAM,WAAW,kBAAkB;IAC/B,MAAM,EAAE,SAAS,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,kBAAkB,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAAC;IAC5C,qFAAqF;IACrF,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAC1F;AAED,iGAAiG;AACjG,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,GAAG,SAAS,CAAC;CACrD;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC1B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAED,0GAA0G;AAC1G,MAAM,WAAW,kBAAkB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,oBAAoB,CAAC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,kBAAkB,CAAC;IAC3B,oGAAoG;IACpG,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,6CAA6C;AAC7C,MAAM,WAAW,uBAAuB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,mGAAmG;IACnG,WAAW,EAAE,SAAS,GAAG,IAAI,CAAC;IAC9B,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,0FAA0F;IAC1F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4FAA4F;IAC5F,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iGAAiG;IACjG,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB"}

package/dist/pipeline/pipeline.types.js

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Core contract for Agent Pipelines — a server-side dataflow the agent authors and
+ * the server runs, so intermediate values never enter the LLM context window.
+ *
+ * The pipe carries a {@link PipeValue} (a JSON value), PowerShell-style, NOT a string: stages bind
+ * to object properties instead of re-parsing text. Capabilities (Actions / artifact tools) are
+ * effectful async stages behind {@link PipelineInvocable}; pure operators (where/select/sort/…) are
+ * synchronous value→value functions; `map`/`let` are control constructs handled by the executor.
+ *
+ * @module @memberjunction/ai-agents
+ */
+export {};
+//# sourceMappingURL=pipeline.types.js.map

package/dist/pipeline/pipeline.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.types.js","sourceRoot":"","sources":["../../src/pipeline/pipeline.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/pipeline/predicate.d.ts

@@ -0,0 +1,23 @@
+import { PipeValue } from './pipeline.types.js';
+type Comparison = {
+    kind: 'cmp';
+    path: string;
+    op: string;
+    value: PipeValue | PipeValue[];
+};
+type PredicateNode = Comparison | {
+    kind: 'and';
+    nodes: PredicateNode[];
+} | {
+    kind: 'or';
+    nodes: PredicateNode[];
+} | {
+    kind: 'not';
+    node: PredicateNode;
+};
+/** Parse a predicate string into an AST. Throws with a clear message on malformed input. */
+export declare function parsePredicate(src: string): PredicateNode;
+/** Evaluate a parsed predicate against one element. */
+export declare function evaluatePredicate(ast: PredicateNode, element: PipeValue): boolean;
+export {};
+//# sourceMappingURL=predicate.d.ts.map

package/dist/pipeline/predicate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"predicate.d.ts","sourceRoot":"","sources":["../../src/pipeline/predicate.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAS7C,KAAK,UAAU,GAAG;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,GAAG,SAAS,EAAE,CAAA;CAAE,CAAC;AAC5F,KAAK,aAAa,GACZ,UAAU,GACV;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,aAAa,EAAE,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,aAAa,EAAE,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC;AAM3C,4FAA4F;AAC5F,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAKzD;AAED,uDAAuD;AACvD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,aAAa,EAAE,OAAO,EAAE,SAAS,GAAG,OAAO,CAWjF"}