@memberjunction/ai-agents 5.38.0 → 5.40.0

package/dist/pipeline/operators.js

@@ -0,0 +1,332 @@
+import { getValue, getValues } from './path.js';
+import { parsePredicate, evaluatePredicate } from './predicate.js';
+import { valueToText } from './coerce.js';
+// ─── helpers ───
+function requireArray(input, op) {
+    if (!Array.isArray(input)) {
+        throw new Error(`"${op}" expects an array but received ${describe(input)}.${nonArrayHint(input)}`);
+    }
+    return input;
+}
+/**
+ * Guard for the text-only operators (`head`/`tail`): reject arrays and point the agent at the
+ * array equivalent. Keeps the verb choice unambiguous — `head`/`tail` operate on text LINES,
+ * `first`/`last` operate on array ELEMENTS — instead of both silently slicing arrays.
+ */
+function rejectArray(input, op, arrayOp) {
+    if (Array.isArray(input)) {
+        throw new Error(`"${op}" operates on text only; for the ${input.length}-element array use "${arrayOp}" instead.`);
+    }
+}
+function describe(v) {
+    if (Array.isArray(v))
+        return 'an array';
+    if (v === null)
+        return 'null';
+    return `a ${typeof v}`;
+}
+/**
+ * When an array operator gets a non-array OBJECT, it's almost always because the upstream value is an
+ * envelope wrapping the real collection (e.g. `{ Results: [...] }`). List the keys and, if one holds
+ * an array, suggest the exact `jsonpath` to extract it — so the agent self-corrects next turn from
+ * the message alone (the data isn't in its context). Returns '' for non-objects.
+ */
+function nonArrayHint(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        return '';
+    }
+    const keys = Object.keys(input);
+    const arrayKey = keys.find((k) => Array.isArray(input[k]));
+    const path = arrayKey ? `$.${arrayKey}[*]` : '$.<field>[*]';
+    return (` Got an object with keys [${keys.join(', ')}].` +
+        ` If the array is nested under a field, extract it first with a {"jsonpath":"${path}"} stage.`);
+}
+function asString(args, op) {
+    if (typeof args !== 'string' || args.trim() === '') {
+        throw new Error(`"${op}" requires a non-empty string argument.`);
+    }
+    return args;
+}
+function asInt(args, op) {
+    const n = typeof args === 'number' ? args : parseInt(String(args), 10);
+    if (!Number.isFinite(n)) {
+        throw new Error(`"${op}" requires a numeric argument.`);
+    }
+    return Math.trunc(n);
+}
+function lastSegment(path) {
+    return (path.split('.').pop() ?? path).replace(/\[.*\]$/, '');
+}
+/** Numeric when both sides are numeric; else lexicographic on string forms. */
+function compareValues(a, b) {
+    const na = Number(a);
+    const nb = Number(b);
+    if (Number.isFinite(na) && Number.isFinite(nb)) {
+        return na - nb;
+    }
+    const sa = a == null ? '' : String(a);
+    const sb = b == null ? '' : String(b);
+    return sa < sb ? -1 : sa > sb ? 1 : 0;
+}
+function toLines(input) {
+    return valueToText(input).split('\n');
+}
+/** Reduce a list of numbers by an aggregation op. Empty → null (no numeric values in the group). */
+function applyAggregate(op, nums) {
+    if (nums.length === 0)
+        return null;
+    if (op === 'sum')
+        return nums.reduce((a, b) => a + b, 0);
+    if (op === 'avg')
+        return nums.reduce((a, b) => a + b, 0) / nums.length;
+    if (op === 'min')
+        return Math.min(...nums);
+    return Math.max(...nums);
+}
+// ─── object operators ───
+const Where = {
+    name: 'where',
+    description: 'Keep array elements matching a predicate, e.g. "Balance > 0 and Status == \'Open\'".',
+    argsHint: 'predicate string (==, !=, <, >, <=, >=, contains, startsWith, endsWith, matches, in; and/or/not)',
+    apply(input, args) {
+        const arr = requireArray(input, 'where');
+        const ast = parsePredicate(asString(args, 'where'));
+        return arr.filter((el) => evaluatePredicate(ast, el));
+    },
+};
+const Select = {
+    name: 'select',
+    description: 'Project field(s) from each element. One field → array of values; many → array of objects.',
+    argsHint: 'a field path string, or an array of field paths',
+    apply(input, args) {
+        const fields = (Array.isArray(args) ? args : [args]).map((f) => asString(f, 'select'));
+        const project = (el) => {
+            if (fields.length === 1) {
+                return getValue(el, fields[0]) ?? null;
+            }
+            return fields.reduce((o, f) => {
+                o[lastSegment(f)] = getValue(el, f) ?? null;
+                return o;
+            }, {});
+        };
+        if (Array.isArray(input)) {
+            return input.map(project);
+        }
+        // Projecting off a non-array object that has a nested array, where none of the requested
+        // fields exist on the outer object, is the classic "forgot to extract the collection"
+        // mistake — fail loudly with the extraction hint instead of silently returning null (which
+        // would only surface as a confusing error one stage later).
+        const allMissing = fields.every((f) => getValue(input, f) === undefined);
+        if (allMissing && input !== null && typeof input === 'object' && Object.values(input).some(Array.isArray)) {
+            throw new Error(`"select" found none of [${fields.join(', ')}] on this value.${nonArrayHint(input)}`);
+        }
+        return project(input);
+    },
+};
+const Sort = {
+    name: 'sort',
+    description: 'Sort an array by field(s). Prefix a field with "-" for descending.',
+    argsHint: 'a field path string (e.g. "-Balance"), or an array of them',
+    apply(input, args) {
+        const arr = requireArray(input, 'sort');
+        const keys = (Array.isArray(args) ? args : [args]).map((k) => asString(k, 'sort'));
+        return [...arr].sort((a, b) => {
+            for (const key of keys) {
+                const desc = key.startsWith('-');
+                const path = desc ? key.slice(1) : key;
+                const c = compareValues(getValue(a, path), getValue(b, path));
+                if (c !== 0) {
+                    return desc ? -c : c;
+                }
+            }
+            return 0;
+        });
+    },
+};
+const First = {
+    name: 'first',
+    description: 'Keep the first N elements of an array.',
+    argsHint: 'a number N',
+    apply(input, args) {
+        return requireArray(input, 'first').slice(0, Math.max(0, asInt(args, 'first')));
+    },
+};
+const Last = {
+    name: 'last',
+    description: 'Keep the last N elements of an array.',
+    argsHint: 'a number N',
+    apply(input, args) {
+        const arr = requireArray(input, 'last');
+        const n = Math.max(0, asInt(args, 'last'));
+        return arr.slice(Math.max(0, arr.length - n));
+    },
+};
+const Count = {
+    name: 'count',
+    description: 'Replace the value with its size: array length, object key count, or string length.',
+    argsHint: 'no arguments',
+    apply(input) {
+        if (Array.isArray(input))
+            return input.length;
+        if (typeof input === 'string')
+            return input.length;
+        if (input !== null && typeof input === 'object')
+            return Object.keys(input).length;
+        return input == null ? 0 : 1;
+    },
+};
+const Distinct = {
+    name: 'distinct',
+    description: 'Remove duplicate array elements, optionally by a field path.',
+    argsHint: 'optional field path to dedupe by; omit (or pass true) to dedupe whole elements',
+    apply(input, args) {
+        const arr = requireArray(input, 'distinct');
+        // A non-empty string arg dedupes by that field path; anything else (omitted, `true`, `{}`)
+        // dedupes by the whole element — so `{ "distinct": true }` after a `select` works as expected.
+        const field = typeof args === 'string' && args.trim() !== '' ? args : null;
+        const seen = new Set();
+        const keyOf = (el) => field ? valueToText(getValue(el, field) ?? null) : valueToText(el);
+        return arr.filter((el) => {
+            const k = keyOf(el);
+            if (seen.has(k))
+                return false;
+            seen.add(k);
+            return true;
+        });
+    },
+};
+const Flatten = {
+    name: 'flatten',
+    description: 'Flatten a nested array one level.',
+    argsHint: 'no arguments',
+    apply(input) {
+        return requireArray(input, 'flatten').flatMap((el) => (Array.isArray(el) ? el : [el]));
+    },
+};
+const GroupBy = {
+    name: 'groupBy',
+    description: 'Group array elements by field(s) and aggregate. Each group gets a "count"; optionally add ' +
+        'sum/avg/min/max of a numeric field (output keys like "sum_Amount"). This is how you answer ' +
+        'analytical questions over large data without returning the rows.',
+    argsHint: 'a field path (count per group), or { "by": <field | [fields]>, "sum"?: field, "avg"?: field, "min"?: field, "max"?: field }',
+    apply(input, args) {
+        const arr = requireArray(input, 'groupBy');
+        const cfg = typeof args === 'string' ? { by: args } : args ?? {};
+        const byList = Array.isArray(cfg.by) ? cfg.by : [cfg.by];
+        if (cfg.by == null || byList.some((f) => typeof f !== 'string' || f.trim() === '')) {
+            throw new Error('groupBy needs a "by" field — the field to group on, e.g. { "by": "Category", "sum": "Amount" }.');
+        }
+        const byFields = byList;
+        const aggSpecs = ['sum', 'avg', 'min', 'max']
+            .filter((op) => cfg[op] != null)
+            .map((op) => {
+            const field = cfg[op];
+            if (typeof field !== 'string' || field.trim() === '') {
+                throw new Error(`groupBy "${op}" needs a numeric field name, e.g. { "by": "Category", "${op}": "Amount" }.`);
+            }
+            return { op, field };
+        });
+        const groups = new Map();
+        for (const el of arr) {
+            const key = {};
+            for (const f of byFields) {
+                key[lastSegment(f)] = getValue(el, f) ?? null;
+            }
+            const mapKey = valueToText(byFields.map((f) => getValue(el, f) ?? null));
+            const existing = groups.get(mapKey);
+            if (existing) {
+                existing.rows.push(el);
+            }
+            else {
+                groups.set(mapKey, { key, rows: [el] });
+            }
+        }
+        return [...groups.values()].map(({ key, rows }) => {
+            const out = { ...key, count: rows.length };
+            for (const { op, field } of aggSpecs) {
+                const nums = rows.map((r) => Number(getValue(r, field))).filter((n) => Number.isFinite(n));
+                out[`${op}_${lastSegment(field)}`] = applyAggregate(op, nums);
+            }
+            return out;
+        });
+    },
+};
+const JsonPath = {
+    name: 'jsonpath',
+    description: 'Extract value(s) at a JSONPath (member/index/[*]/.. ). One match → the value; many → an array.',
+    argsHint: 'a JSONPath string, e.g. "$.Results[*].Status"',
+    apply(input, args) {
+        const matches = getValues(input, asString(args, 'jsonpath'));
+        if (matches.length === 0)
+            return null;
+        return matches.length === 1 ? matches[0] : matches;
+    },
+};
+// ─── text operators (coerce-to-text) ───
+const Lines = {
+    name: 'lines',
+    description: 'Split a string value into an array of lines (so object operators can work on it).',
+    argsHint: 'no arguments',
+    apply(input) {
+        return toLines(input);
+    },
+};
+const Grep = {
+    name: 'grep',
+    description: 'Keep matching lines/elements by regex. On a string → matching lines (joined); on an array → matching elements.',
+    argsHint: '{ "pattern": "regex", "ignoreCase"?: bool, "invert"?: bool } or a bare pattern string',
+    apply(input, args) {
+        const opts = typeof args === 'string' ? { pattern: args } : args;
+        const pattern = asString(opts?.pattern, 'grep');
+        const flags = opts?.ignoreCase ? 'i' : '';
+        const invert = opts?.invert === true;
+        let regex;
+        try {
+            regex = new RegExp(pattern, flags);
+        }
+        catch (e) {
+            throw new Error(`Invalid grep pattern "${pattern}": ${e.message}`);
+        }
+        const keep = (line) => regex.test(line) !== invert;
+        if (Array.isArray(input)) {
+            return input.filter((el) => keep(valueToText(el)));
+        }
+        return toLines(input).filter(keep).join('\n');
+    },
+};
+const Head = {
+    name: 'head',
+    description: 'First N LINES of a string (text only — use `first` for the first N array elements).',
+    argsHint: 'a number N',
+    apply(input, args) {
+        rejectArray(input, 'head', 'first');
+        const n = Math.max(0, asInt(args, 'head'));
+        return toLines(input).slice(0, n).join('\n');
+    },
+};
+const Tail = {
+    name: 'tail',
+    description: 'Last N LINES of a string (text only — use `last` for the last N array elements).',
+    argsHint: 'a number N',
+    apply(input, args) {
+        rejectArray(input, 'tail', 'last');
+        const n = Math.max(0, asInt(args, 'tail'));
+        const lines = toLines(input);
+        return lines.slice(Math.max(0, lines.length - n)).join('\n');
+    },
+};
+const ALL = [
+    Where, Select, Sort, First, Last, Count, Distinct, Flatten, GroupBy, JsonPath, Lines, Grep, Head, Tail,
+];
+const BY_NAME = new Map(ALL.map((o) => [o.name, o]));
+/** All operators, in catalog order (for docs). */
+export function GetAllOperators() {
+    return ALL;
+}
+/** Resolve an operator by verb name (exact, lowercase verbs). */
+export function GetOperator(name) {
+    return BY_NAME.get(name);
+}
+/** Reserved verbs that are NOT operators (control constructs + capability stages). */
+export const CONTROL_VERBS = new Set(['tool', 'map', 'let']);
+//# sourceMappingURL=operators.js.map

package/dist/pipeline/operators.js.map

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

package/dist/pipeline/path.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @fileoverview The one field-path grammar reused across `where`, `select`, `sort`, and `{{...}}`
+ * templating. Accepts root-relative paths (`Status`, `Customer.Email`, `Items[*].SKU`) as well as
+ * absolute (`$.Results[*].Name`). Built on the eval-free JSONPath evaluator — paths are parsed,
+ * never `eval`'d, so LLM-authored paths can't execute code.
+ *
+ * @module @memberjunction/ai-agents
+ */
+import { PipeValue } from './pipeline.types.js';
+/** All values matching `path` within `value`. */
+export declare function getValues(value: PipeValue, path: string): PipeValue[];
+/** First value matching `path`, or undefined. Used by where/sort/template (single-valued contexts). */
+export declare function getValue(value: PipeValue, path: string): PipeValue | undefined;
+/** Field names available on an object value (for field-listing error messages). */
+export declare function fieldNames(value: PipeValue): string[];
+//# sourceMappingURL=path.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../src/pipeline/path.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAe7C,iDAAiD;AACjD,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,CAErE;AAED,uGAAuG;AACvG,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAG9E;AAED,mFAAmF;AACnF,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,EAAE,CAUrD"}

package/dist/pipeline/path.js

@@ -0,0 +1,34 @@
+import { parseJsonPath, evaluateJsonPath } from './jsonpath-eval.js';
+/** Normalize a relative path to absolute JSONPath form. `$`/`$.x` pass through; `x.y` → `$.x.y`. */
+function toAbsolute(path) {
+    const p = path.trim();
+    if (p === '' || p === '$') {
+        return '$';
+    }
+    if (p.startsWith('$')) {
+        return p;
+    }
+    return p.startsWith('[') ? `$${p}` : `$.${p}`;
+}
+/** All values matching `path` within `value`. */
+export function getValues(value, path) {
+    return evaluateJsonPath(parseJsonPath(toAbsolute(path)), value);
+}
+/** First value matching `path`, or undefined. Used by where/sort/template (single-valued contexts). */
+export function getValue(value, path) {
+    const vs = getValues(value, path);
+    return vs.length > 0 ? vs[0] : undefined;
+}
+/** Field names available on an object value (for field-listing error messages). */
+export function fieldNames(value) {
+    if (Array.isArray(value)) {
+        // Surface the element fields — that's what `where`/`select` operate on.
+        const first = value.find((v) => v !== null && typeof v === 'object' && !Array.isArray(v));
+        return first ? Object.keys(first) : [];
+    }
+    if (value !== null && typeof value === 'object') {
+        return Object.keys(value);
+    }
+    return [];
+}
+//# sourceMappingURL=path.js.map

package/dist/pipeline/path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.js","sourceRoot":"","sources":["../../src/pipeline/path.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAElE,oGAAoG;AACpG,SAAS,UAAU,CAAC,IAAY;IAC5B,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IACtB,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;QACxB,OAAO,GAAG,CAAC;IACf,CAAC;IACD,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACpB,OAAO,CAAC,CAAC;IACb,CAAC;IACD,OAAO,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;AAClD,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,SAAS,CAAC,KAAgB,EAAE,IAAY;IACpD,OAAO,gBAAgB,CAAC,aAAa,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,EAAE,KAAK,CAAgB,CAAC;AACnF,CAAC;AAED,uGAAuG;AACvG,MAAM,UAAU,QAAQ,CAAC,KAAgB,EAAE,IAAY;IACnD,MAAM,EAAE,GAAG,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAClC,OAAO,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7C,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,UAAU,CAAC,KAAgB;IACvC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACvB,wEAAwE;QACxE,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1F,OAAO,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAgC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACtE,CAAC;IACD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9C,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,EAAE,CAAC;AACd,CAAC"}

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

@@ -0,0 +1,6 @@
+/**
+ * Build the pipeline docs. Returns '' when there are no sources — a pipeline's first stage must be
+ * a capability (Action/artifact tool), so with none available pipelines are impossible.
+ */
+export declare function BuildPipelineToolDocs(sourceToolNames: string[]): string;
+//# sourceMappingURL=pipeline-docs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-docs.d.ts","sourceRoot":"","sources":["../../src/pipeline/pipeline-docs.ts"],"names":[],"mappings":"AAWA;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,eAAe,EAAE,MAAM,EAAE,GAAG,MAAM,CA2IvE"}

package/dist/pipeline/pipeline-docs.js

@@ -0,0 +1,137 @@
+/**
+ * @fileoverview Generates the `pipeline` tool documentation injected into the agent's system prompt
+ * (`_PIPELINE_TOOLS`). Teaches the value model, the verb catalog, the field-path grammar, and a few
+ * worked examples. Pure function.
+ *
+ * @module @memberjunction/ai-agents
+ */
+import { GetAllOperators } from './operators.js';
+const MAX_SOURCES_LISTED = 50;
+/**
+ * Build the pipeline docs. Returns '' when there are no sources — a pipeline's first stage must be
+ * a capability (Action/artifact tool), so with none available pipelines are impossible.
+ */
+export function BuildPipelineToolDocs(sourceToolNames) {
+    if (sourceToolNames.length === 0) {
+        return '';
+    }
+    const operators = GetAllOperators()
+        .map((o) => `- **${o.name}** — ${o.description} _(args: ${o.argsHint})_`)
+        .join('\n');
+    return [
+        '## Agent Pipelines',
+        '',
+        'Run a multi-step dataflow **server-side** so large intermediate results never enter your context. ' +
+            'Set `nextStep.type` to `"Pipeline"` and provide `nextStep.pipeline.steps` (a flat array); ' +
+            '**values flow between stages as structured JSON** ' +
+            '(arrays/objects), PowerShell-style — stages bind to fields, you do NOT re-parse text. Only the ' +
+            'FINAL stage\'s value is returned to you. Reach for this whenever a step produces a large payload ' +
+            'and you only need a slice/shape of it, or to chain several actions without paying context for the ' +
+            'data passing between them.',
+        '',
+        '### Keep the final value SMALL',
+        'Only the FINAL stage\'s value is returned to you — every intermediate stays server-side, so those tokens ' +
+            'are saved. Make the last stage small: end with `select`/`count`/`first`, and **inside `map`, extract or ' +
+            'reduce each element** (e.g. `grep` then `count`, or `select` a few fields). Do NOT let a `map` return ' +
+            'whole fetched pages/records — that large payload would become your final value. Fetch big, return small.',
+        '',
+        '### Stage kinds (one verb per stage)',
+        '- **Capability:** `{ "tool": "<name>", "with": { ...params }, "pipeInto": "<paramName>" }` — run an ' +
+            'Action/artifact tool. `pipeInto` puts the whole upstream value into that param; omit it for a ' +
+            'source (first stage). Params may use `{{ path }}` templates over the upstream value (`$`) or ' +
+            'map/let bindings.',
+        '- **Operators** (pure, applied to the upstream value):',
+        operators,
+        '- **`map`:** `{ "map": { "as": "row", "do": [ ...sub-stages ] } }` — run the sub-pipeline once per ' +
+            'array element (`{{row.field}}` available inside). **`map` REPLACES the array with each element\'s ' +
+            'FINAL sub-stage value** — it does NOT add a field to existing rows. Use it for per-element *actions/' +
+            'transforms* (e.g. send an email per row), NOT to compute a column. To filter/sort/aggregate or keep ' +
+            'fields, use the operators directly (`where`/`select`/`sort`/`groupBy`) — no `map` needed.',
+        '- **`let`:** `{ "let": { "name": "x", "value": [ ...sub-stages ] } }` — capture a result as `{{x}}` ' +
+            'for later stages; the main stream passes through unchanged (use for joins/correlation).',
+        '',
+        '### Field paths',
+        'Used by `where`/`select`/`sort`/templates: `Status`, `Customer.Email`, `Results[0].Name`, `Items[*].SKU`. ' +
+            '`where` predicates support `== != < > <= >= contains startsWith endsWith matches in` and `and/or/not`, ' +
+            'e.g. `Balance > 0 and Status == \'Open\'`.',
+        '',
+        '### Input shapes — operators need an ARRAY',
+        '`where`/`select`/`sort`/`distinct`/`first`/`last` operate on an **array of objects**. Tabular tools ' +
+            '(`get_rows`) already hand you that array of row objects — pipe them straight into `where`/`select`, ' +
+            'no unwrapping needed. If a source instead returns a wrapper object (e.g. `{ "Results": [...] }`), ' +
+            'extract the array first with a `{ "jsonpath": "$.Results[*]" }` stage. When an operator reports ' +
+            '"expects an array but received an object", read the listed keys and add exactly that `jsonpath` stage.',
+        '',
+        '### Sources available now',
+        sourceToolNames.slice(0, MAX_SOURCES_LISTED).map((n) => `\`${n}\``).join(', ') +
+            (sourceToolNames.length > MAX_SOURCES_LISTED ? ', …' : '') +
+            ' (artifact tools take an `artifactId` param).',
+        '',
+        '### Examples',
+        '```json',
+        JSON.stringify({
+            nextStep: {
+                type: 'Pipeline',
+                pipeline: {
+                    steps: [
+                        { tool: sourceToolNames[0], with: {} },
+                        { where: "Status == 'Rejected'" },
+                        { select: ['ID', 'Email'] },
+                        { first: 10 },
+                    ],
+                },
+            },
+        }, null, 2),
+        '```',
+        'Batch action chain (intermediates never in context):',
+        '```json',
+        JSON.stringify({
+            nextStep: {
+                type: 'Pipeline',
+                pipeline: {
+                    steps: [
+                        { tool: sourceToolNames[0], with: {} },
+                        { where: 'Balance > 0' },
+                        { map: { as: 'row', do: [{ tool: sourceToolNames[0], with: { Note: '{{row.ID}}' } }] } },
+                        { count: true },
+                    ],
+                },
+            },
+        }, null, 2),
+        '```',
+        'Tabular artifact tool — `get_rows` yields the row objects directly; filter and shape them with no unwrapping:',
+        '```json',
+        JSON.stringify({
+            nextStep: {
+                type: 'Pipeline',
+                pipeline: {
+                    steps: [
+                        { tool: 'get_rows', with: { artifactId: 'A', start: 0, count: 500 } },
+                        { where: "Department == 'Engineering' and Status == 'Active'" },
+                        { select: ['EmployeeID', 'Name', 'Region'] },
+                        { distinct: 'Region' },
+                    ],
+                },
+            },
+        }, null, 2),
+        '```',
+        'Analytical question over a LARGE file — aggregate server-side, return a tiny summary (the raw ' +
+            'rows never enter your context, so this works even when the file is too big to read whole):',
+        '```json',
+        JSON.stringify({
+            nextStep: {
+                type: 'Pipeline',
+                pipeline: {
+                    steps: [
+                        { tool: 'get_full', with: { artifactId: 'A' } },
+                        { groupBy: { by: 'Category', sum: 'Amount', avg: 'Amount' } },
+                        { sort: '-sum_Amount' },
+                        { first: 10 },
+                    ],
+                },
+            },
+        }, null, 2),
+        '```',
+    ].join('\n');
+}
+//# sourceMappingURL=pipeline-docs.js.map

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

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

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

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview The Agent Pipeline executor — runs a server-side dataflow over {@link PipeValue}s.
+ *
+ * Stage kinds:
+ *  - operator (`where`/`select`/…) — pure, applied directly.
+ *  - `tool` — an Action/artifact tool; params get `{{template}}` resolution + optional `pipeInto`
+ *    (the whole upstream value injected into a named param).
+ *  - `map` — run a sub-pipeline per element of an array (bounded concurrency, caps, fail-policy).
+ *  - `let` — run a sub-pipeline, bind its result to a name for later `{{name}}` use; stream unchanged.
+ *
+ * Only top-level stages produce log records; `map`/`let` summarize. Fails fast with an agent-facing
+ * message (never echoes a piped value; field-errors list available fields).
+ *
+ * @module @memberjunction/ai-agents
+ */
+import { PipelineStage, PipelineExecutionResult } from './pipeline.types.js';
+import { PipelineToolRegistry } from './pipeline-registry.js';
+export declare const MAX_PIPELINE_STAGES = 20;
+export declare const MAX_MAP_ELEMENTS = 1000;
+export declare const MAP_CONCURRENCY = 8;
+/** Default wall-clock budget for an entire pipeline (incl. all map/let sub-pipelines). */
+export declare const DEFAULT_PIPELINE_DEADLINE_MS = 120000;
+/** Optional runtime controls for a pipeline execution. */
+export interface PipelineExecutorOptions {
+    /** Wall-clock budget for the whole pipeline. Checked between stages + map batches. */
+    deadlineMs?: number;
+    /** Caller cancellation; honored at the same checkpoints as the deadline. */
+    signal?: AbortSignal;
+}
+export declare class PipelineExecutor {
+    private readonly registry;
+    private readonly 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.
+     */
+    private producedBytes;
+    /** Absolute wall-clock deadline (epoch ms) for this run; set at the start of {@link Execute}. */
+    private deadlineAt;
+    private readonly deadlineMs;
+    private readonly signal?;
+    constructor(registry: PipelineToolRegistry, maxStages?: number, opts?: PipelineExecutorOptions);
+    /**
+     * 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).
+     */
+    private checkAbort;
+    /** Validate + run a pipeline. Returns a structured result; never throws on stage failure. */
+    Execute(stages: PipelineStage[]): Promise<PipelineExecutionResult>;
+    private validateShape;
+    /** Dispatch one stage. Never throws — converts errors into a failed outcome. */
+    private runStage;
+    private runOperatorStage;
+    private runToolStage;
+    private runMapStage;
+    private runLetStage;
+    /** Run a sub-pipeline (map/let) with no top-level record-keeping; fails fast internally. */
+    private runStages;
+    private failure;
+    /**
+     * 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.
+     */
+    private computeSaved;
+}
+//# sourceMappingURL=pipeline-executor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-executor.d.ts","sourceRoot":"","sources":["../../src/pipeline/pipeline-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAEH,aAAa,EAEb,uBAAuB,EAE1B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAK3D,eAAO,MAAM,mBAAmB,KAAK,CAAC;AACtC,eAAO,MAAM,gBAAgB,OAAO,CAAC;AACrC,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,0FAA0F;AAC1F,eAAO,MAAM,4BAA4B,SAAU,CAAC;AAEpD,0DAA0D;AAC1D,MAAM,WAAW,uBAAuB;IACpC,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,WAAW,CAAC;CACxB;AAaD,qBAAa,gBAAgB;IAcrB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAd9B;;;;;OAKG;IACH,OAAO,CAAC,aAAa,CAAK;IAC1B,iGAAiG;IACjG,OAAO,CAAC,UAAU,CAA4B;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAc;gBAGjB,QAAQ,EAAE,oBAAoB,EAC9B,SAAS,GAAE,MAA4B,EACxD,IAAI,GAAE,uBAA4B;IAMtC;;;;;;OAMG;IACH,OAAO,CAAC,UAAU;IAWlB,6FAA6F;IAChF,OAAO,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAiE/E,OAAO,CAAC,aAAa;IAUrB,gFAAgF;YAClE,QAAQ;IAkBtB,OAAO,CAAC,gBAAgB;YAaV,YAAY;YAsBZ,WAAW;YAwDX,WAAW;IAazB,4FAA4F;YAC9E,SAAS;IAqBvB,OAAO,CAAC,OAAO;IAuBf;;;;OAIG;IACH,OAAO,CAAC,YAAY;CAGvB"}