@exellix/graph-engine 6.0.0

package/dist/src/runtime/resolveTaskNodeInputs.js

@@ -0,0 +1,140 @@
+import { readExecutionVariableBuckets, } from './executionVariableBuckets.js';
+import { readTaskNodeInputsConfig } from './readTaskNodeInputsConfig.js';
+function isPlainObject(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+function getByDotPath(root, path) {
+    if (!path)
+        return root;
+    const parts = path.split('.').filter(Boolean);
+    let cur = root;
+    for (const p of parts) {
+        if (cur == null)
+            return undefined;
+        if (typeof cur !== 'object')
+            return undefined;
+        cur = cur[p];
+    }
+    return cur;
+}
+function isExecutionMemoryBinding(val) {
+    return isPlainObject(val) && val.type === 'executionMemoryPath' && typeof val.path === 'string';
+}
+/** Best-effort `$path` resolution for legacy binding refs in `inputsConfig`. */
+function resolvePathRef(fullPath, execution) {
+    const p = fullPath.trim();
+    if (p.startsWith('executionMemory.'))
+        return getByDotPath(execution, p.slice('executionMemory.'.length));
+    if (p.startsWith('input.'))
+        return getByDotPath(execution, p);
+    if (p.startsWith('execution.'))
+        return getByDotPath(execution, p.slice('execution.'.length));
+    return getByDotPath(execution, p);
+}
+function resolveExecutionMemoryBinding(val, execution) {
+    const v = getByDotPath(execution, val.path);
+    if ((v === undefined || v === null) && val.optional === true)
+        return undefined;
+    return v;
+}
+function resolvePathFromBuckets(fullPath, buckets) {
+    const p = fullPath.trim();
+    if (p.startsWith('variables.') || p.startsWith('jobVariables.')) {
+        const tail = p.startsWith('variables.')
+            ? p.slice('variables.'.length)
+            : p.slice('jobVariables.'.length);
+        return getByDotPath(buckets.jobVariables, tail);
+    }
+    if (p.startsWith('taskVariables.')) {
+        return getByDotPath(buckets.taskVariables, p.slice('taskVariables.'.length));
+    }
+    return undefined;
+}
+/**
+ * Resolves `node.taskVariable` into concrete values for `RunTaskRequest.input`.
+ * `$path` refs resolve against the matching execution bucket only (no cross-bucket merge).
+ */
+export function resolveTaskNodeTaskVariableForRunTask(args) {
+    const recipe = (args.node.taskVariable ?? {});
+    const out = {};
+    for (const [key, val] of Object.entries(recipe)) {
+        const resolved = resolveTaskVariableValue(val, args.buckets);
+        if (resolved !== undefined)
+            out[key] = resolved;
+    }
+    return out;
+}
+function resolveTaskVariableValue(val, buckets) {
+    if (!isPlainObject(val))
+        return val;
+    const o = val;
+    if (typeof o.$path === 'string') {
+        return resolvePathFromBuckets(o.$path, buckets);
+    }
+    const nested = {};
+    for (const [k, v] of Object.entries(o)) {
+        if (k === '$path')
+            continue;
+        const child = resolveTaskVariableValue(v, buckets);
+        if (child !== undefined)
+            nested[k] = child;
+    }
+    return Object.keys(nested).length > 0 ? nested : val;
+}
+/**
+ * Resolves runtime payload bindings from `node.inputsConfig` only (plus deprecated aliases).
+ */
+export function resolveTaskNodeInputBindingsForRunTask(args) {
+    const recipe = readTaskNodeInputsConfig(args.node);
+    const out = {};
+    for (const [key, val] of Object.entries(recipe)) {
+        if (isExecutionMemoryBinding(val)) {
+            out[key] = resolveExecutionMemoryBinding(val, args.execution);
+            continue;
+        }
+        if (isPlainObject(val) && typeof val.$path === 'string') {
+            const p = val.$path.trim();
+            if (p.startsWith('variables.') || p.startsWith('jobVariables.') || p.startsWith('taskVariables.')) {
+                continue;
+            }
+            out[key] = resolvePathRef(p, args.execution);
+        }
+    }
+    return out;
+}
+/** Legacy literals / variable refs still under deprecated `inputs`. */
+function resolveLegacyTaskVariableFromInputBindings(args) {
+    const recipe = readTaskNodeInputsConfig(args.node);
+    const out = {};
+    for (const [key, val] of Object.entries(recipe)) {
+        if (isExecutionMemoryBinding(val))
+            continue;
+        if (isPlainObject(val) && typeof val.$path === 'string') {
+            const p = val.$path.trim();
+            if (!p.startsWith('variables.') && !p.startsWith('jobVariables.') && !p.startsWith('taskVariables.')) {
+                continue;
+            }
+        }
+        const resolved = resolveTaskVariableValue(val, args.buckets);
+        if (resolved !== undefined)
+            out[key] = resolved;
+    }
+    return out;
+}
+/**
+ * Resolves task-node model input for MAIN `RunTaskRequest.input`:
+ * `taskVariable` plus execution-memory bindings (separate buckets, no merge).
+ */
+export function resolveTaskNodeInputsForRunTask(args) {
+    const buckets = readExecutionVariableBuckets(args.execution);
+    const legacyTaskVar = resolveLegacyTaskVariableFromInputBindings({
+        node: args.node,
+        buckets,
+    });
+    const taskVariable = resolveTaskNodeTaskVariableForRunTask({ node: args.node, buckets });
+    const bindings = resolveTaskNodeInputBindingsForRunTask({
+        node: args.node,
+        execution: args.execution,
+    });
+    return { ...legacyTaskVar, ...taskVariable, ...bindings };
+}

package/dist/src/runtime/runTaskAugments.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared pieces for assembling `@exellix/ai-tasks` requests from graph-engine (llmCall merge, identity, trace mode).
+ */
+export declare function mergeDefinedLlmCallParts(...parts: Array<Record<string, unknown> | undefined | null>): Record<string, unknown> | undefined;
+/** Whether to send `executionMode: "trace"` on `runTask` (ai-tasks 5.6+). */
+export declare function shouldForwardRunTaskTraceMode(opts: {
+    debugMode?: boolean;
+    runTaskExecutionMode?: 'default' | 'trace';
+}): boolean;
+export declare function buildRunTaskIdentityEnvelope(args: {
+    base?: Record<string, unknown>;
+    nodeMeta?: Record<string, unknown> | undefined;
+    graphId?: string;
+    nodeId: string;
+    taskId: string;
+    jobId: string;
+}): Record<string, unknown>;

package/dist/src/runtime/runTaskAugments.js

@@ -0,0 +1,37 @@
+/**
+ * Shared pieces for assembling `@exellix/ai-tasks` requests from graph-engine (llmCall merge, identity, trace mode).
+ */
+export function mergeDefinedLlmCallParts(...parts) {
+    const out = {};
+    for (const p of parts) {
+        if (!p || typeof p !== 'object' || Array.isArray(p))
+            continue;
+        for (const [k, v] of Object.entries(p)) {
+            if (v !== undefined)
+                out[k] = v;
+        }
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/** Whether to send `executionMode: "trace"` on `runTask` (ai-tasks 5.6+). */
+export function shouldForwardRunTaskTraceMode(opts) {
+    if (opts.runTaskExecutionMode === 'trace')
+        return true;
+    if (opts.runTaskExecutionMode === 'default')
+        return false;
+    return opts.debugMode === true;
+}
+export function buildRunTaskIdentityEnvelope(args) {
+    const fromNodeRaw = args.nodeMeta?.runTaskIdentity ?? args.nodeMeta?.identity;
+    const fromNode = fromNodeRaw != null && typeof fromNodeRaw === 'object' && !Array.isArray(fromNodeRaw)
+        ? fromNodeRaw
+        : {};
+    return {
+        ...(args.base ?? {}),
+        ...fromNode,
+        ...(args.graphId != null && args.graphId !== '' ? { graphId: args.graphId } : {}),
+        nodeId: args.nodeId,
+        taskId: args.taskId,
+        jobId: args.jobId,
+    };
+}

package/dist/src/runtime/runTaskResponse.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Normalize task client responses: mocks and adapters may set `success`, `ok`, or neither (throw-only errors).
+ */
+export declare function runTaskResponseSucceeded(res: unknown): boolean;

package/dist/src/runtime/runTaskResponse.js

@@ -0,0 +1,13 @@
+/**
+ * Normalize task client responses: mocks and adapters may set `success`, `ok`, or neither (throw-only errors).
+ */
+export function runTaskResponseSucceeded(res) {
+    if (res == null || typeof res !== 'object')
+        return false;
+    const r = res;
+    if (r.error != null)
+        return false;
+    if (r.success === false || r.ok === false)
+        return false;
+    return true;
+}

package/dist/src/runtime/runtimeObjects.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Runtime Objects Observability — types and composition for graph + downstream packages.
+ * Callers (playground, UIs) use {@link RuntimeObjects} and queryable clients instead of reading Mongo directly.
+ */
+/** Published npm name of this package (root layer in composed observability). */
+export declare const EXELLIX_GRAPH_RUNTIME_PACKAGE_NAME: "@exellix/graph-engine";
+/** Task layer package name in {@link RuntimeObjects.packagesRuntimeObjects}. */
+export declare const EXELLIX_AI_TASKS_PACKAGE_NAME: "@exellix/ai-tasks";
+export type ActivixQueryableClient = {
+    getJobActivities(input: {
+        jobId: string;
+        graphId?: string;
+        nodeId?: string;
+        limit?: number;
+    }): Promise<{
+        jobId: string;
+        graphRun?: unknown;
+        activities: unknown[];
+    }>;
+};
+export type LogxerLogLine = {
+    ts?: number | string;
+    level?: 'debug' | 'info' | 'warn' | 'error';
+    scope?: string;
+    packageName?: string;
+    nodeId?: string;
+    message: string;
+    data?: unknown;
+};
+export type LogxerQueryableClient = {
+    getJobLogs(input: {
+        jobId: string;
+        graphId?: string;
+        nodeId?: string;
+        limit?: number;
+    }): Promise<{
+        jobId: string;
+        lines: LogxerLogLine[];
+    }>;
+};
+export type PackageRuntimeObjects = {
+    name: string;
+    activixClient?: ActivixQueryableClient;
+    logxerClient?: LogxerQueryableClient;
+};
+export type RuntimeObjects = {
+    lastJobId?: string;
+    activixClient?: ActivixQueryableClient;
+    logxerClient?: LogxerQueryableClient;
+    packagesRuntimeObjects: PackageRuntimeObjects[];
+};
+export type BuildExellixGraphRuntimeObjectsInput = {
+    /** Graph-level Activix query surface (e.g. from `@x12i/activix` when available). */
+    graphActivixClient?: ActivixQueryableClient;
+    /** Graph-level Logxer query surface. */
+    graphLogxerClient?: LogxerQueryableClient;
+    /**
+     * Partial subtree from `@exellix/ai-tasks` when that package exports `runtimeObjects`.
+     * Nested `packagesRuntimeObjects` are appended after the ai-tasks row without overwriting entries.
+     */
+    aiTasksRuntimeObjects?: Pick<RuntimeObjects, 'activixClient' | 'logxerClient'> & {
+        packagesRuntimeObjects?: PackageRuntimeObjects[];
+    };
+};
+/**
+ * Builds the composed {@link RuntimeObjects} for exellix-graph: graph-level clients at the root,
+ * then an `@exellix/ai-tasks` package row plus any nested package rows from ai-tasks (flattened as siblings).
+ */
+export declare function buildExellixGraphRuntimeObjects(input: BuildExellixGraphRuntimeObjectsInput): RuntimeObjects;
+/**
+ * Sets the root correlation id for the current graph run (same id forwarded on `runTask` as `jobId`).
+ * Mutates `runtimeObjects` in place when defined.
+ */
+export declare function setRuntimeObjectsLastJobId(runtimeObjects: RuntimeObjects | undefined, jobId: string): void;
+export type RuntimeObjectsObservabilitySummary = {
+    lastJobId?: string;
+    graphActivix: boolean;
+    graphLogxer: boolean;
+    packages: Array<{
+        name: string;
+        activix: boolean;
+        logxer: boolean;
+    }>;
+};
+export declare function summarizeRuntimeObjectsForPlayground(ro: RuntimeObjects): RuntimeObjectsObservabilitySummary;

package/dist/src/runtime/runtimeObjects.js

@@ -0,0 +1,50 @@
+/**
+ * Runtime Objects Observability — types and composition for graph + downstream packages.
+ * Callers (playground, UIs) use {@link RuntimeObjects} and queryable clients instead of reading Mongo directly.
+ */
+/** Published npm name of this package (root layer in composed observability). */
+export const EXELLIX_GRAPH_RUNTIME_PACKAGE_NAME = '@exellix/graph-engine';
+/** Task layer package name in {@link RuntimeObjects.packagesRuntimeObjects}. */
+export const EXELLIX_AI_TASKS_PACKAGE_NAME = '@exellix/ai-tasks';
+/**
+ * Builds the composed {@link RuntimeObjects} for exellix-graph: graph-level clients at the root,
+ * then an `@exellix/ai-tasks` package row plus any nested package rows from ai-tasks (flattened as siblings).
+ */
+export function buildExellixGraphRuntimeObjects(input) {
+    const ai = input.aiTasksRuntimeObjects;
+    const tail = [...(ai?.packagesRuntimeObjects ?? [])];
+    const packagesRuntimeObjects = [
+        {
+            name: EXELLIX_AI_TASKS_PACKAGE_NAME,
+            activixClient: ai?.activixClient,
+            logxerClient: ai?.logxerClient,
+        },
+        ...tail,
+    ];
+    return {
+        activixClient: input.graphActivixClient,
+        logxerClient: input.graphLogxerClient,
+        packagesRuntimeObjects,
+    };
+}
+/**
+ * Sets the root correlation id for the current graph run (same id forwarded on `runTask` as `jobId`).
+ * Mutates `runtimeObjects` in place when defined.
+ */
+export function setRuntimeObjectsLastJobId(runtimeObjects, jobId) {
+    if (!runtimeObjects || jobId.length === 0)
+        return;
+    runtimeObjects.lastJobId = jobId;
+}
+export function summarizeRuntimeObjectsForPlayground(ro) {
+    return {
+        lastJobId: ro.lastJobId,
+        graphActivix: ro.activixClient != null,
+        graphLogxer: ro.logxerClient != null,
+        packages: ro.packagesRuntimeObjects.map((p) => ({
+            name: p.name,
+            activix: p.activixClient != null,
+            logxer: p.logxerClient != null,
+        })),
+    };
+}

package/dist/src/runtime/smartInputPaths.d.ts

@@ -0,0 +1,13 @@
+import type { SmartInputConfig } from '../types/aiTasksDerivedTypes.js';
+import type { TaskNode } from '../types/refs.js';
+/**
+ * Normalizes one smartInput path entry: plain string or graphs-studio `{ path, title?, required? }`.
+ */
+export declare function normalizeSmartInputPath(entry: unknown): string | undefined;
+/** Collects normalized path strings from a task node (authoring may use string or object entries). */
+export declare function collectSmartInputPaths(node: TaskNode): string[];
+/** Wire shape for ai-tasks `runTask`: normalized string `paths` (authoring may use graphs-studio objects). */
+export declare function normalizeSmartInputConfigForRunTask(smartInput: SmartInputConfig | undefined): {
+    paths: string[];
+    strict?: boolean;
+} | undefined;

package/dist/src/runtime/smartInputPaths.js

@@ -0,0 +1,38 @@
+function isPlainObject(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+/**
+ * Normalizes one smartInput path entry: plain string or graphs-studio `{ path, title?, required? }`.
+ */
+export function normalizeSmartInputPath(entry) {
+    if (typeof entry === 'string') {
+        const t = entry.trim();
+        return t.length > 0 ? t : undefined;
+    }
+    if (isPlainObject(entry) && typeof entry.path === 'string') {
+        const t = entry.path.trim();
+        return t.length > 0 ? t : undefined;
+    }
+    return undefined;
+}
+/** Collects normalized path strings from a task node (authoring may use string or object entries). */
+export function collectSmartInputPaths(node) {
+    const raw = node.smartInput?.paths;
+    if (!Array.isArray(raw))
+        return [];
+    return raw.map(normalizeSmartInputPath).filter((p) => p != null);
+}
+/** Wire shape for ai-tasks `runTask`: normalized string `paths` (authoring may use graphs-studio objects). */
+export function normalizeSmartInputConfigForRunTask(smartInput) {
+    if (smartInput == null || typeof smartInput !== 'object' || Array.isArray(smartInput)) {
+        return undefined;
+    }
+    const raw = smartInput;
+    const paths = collectSmartInputPaths({ smartInput: raw });
+    if (paths.length === 0 && raw.strict === undefined)
+        return undefined;
+    return {
+        ...(raw.strict !== undefined ? { strict: raw.strict } : {}),
+        paths,
+    };
+}

package/dist/src/runtime/stepRetry.d.ts

@@ -0,0 +1,21 @@
+import type { RunLogEntry } from '../types/runLog.js';
+import type { RunTaskRequest, RunTaskResponse, StepRetryPolicy } from '../types/options.js';
+import type { TaskNode } from '../types/refs.js';
+import type { StepAttemptRecord } from '../types/results.js';
+export type ResolvedStepRetryPolicy = Required<Pick<StepRetryPolicy, 'maxAttempts' | 'retryOnTimeout' | 'retryOnTokenLimit' | 'tokenBumpMultiplier' | 'tokenBumpCap' | 'baseMaxTokensFallback'>>;
+export declare function resolveStepRetryPolicy(graphPolicy: StepRetryPolicy | undefined, node: Pick<TaskNode, 'taskConfiguration'> | undefined): ResolvedStepRetryPolicy;
+export type RunTaskWithRetryResult = {
+    response: RunTaskResponse;
+    attempts: StepAttemptRecord[];
+    syntheticRunLog: RunLogEntry[];
+    lastRequest: RunTaskRequest;
+};
+export declare function runRunTaskWithRetry(args: {
+    initialRequest: RunTaskRequest;
+    doRunTask: (req: RunTaskRequest) => Promise<RunTaskResponse>;
+    nodeTimeoutMs?: number;
+    policy: ResolvedStepRetryPolicy;
+    nodeId: string;
+    skillKey: string;
+    nodeTimeoutErrorFactory: () => Error;
+}): Promise<RunTaskWithRetryResult>;

package/dist/src/runtime/stepRetry.js

@@ -0,0 +1,238 @@
+import { runTaskResponseSucceeded } from './runTaskResponse.js';
+import { withTimeout } from './withTimeout.js';
+const DEFAULT_POLICY = {
+    maxAttempts: 3,
+    retryOnTimeout: true,
+    retryOnTokenLimit: true,
+    tokenBumpMultiplier: 2,
+    tokenBumpCap: 16_000,
+    baseMaxTokensFallback: 2000,
+};
+export function resolveStepRetryPolicy(graphPolicy, node) {
+    const nodeRaw = node?.taskConfiguration?.stepRetryPolicy;
+    const nodePolicy = nodeRaw != null && typeof nodeRaw === 'object' && !Array.isArray(nodeRaw) ? nodeRaw : undefined;
+    const merged = { ...DEFAULT_POLICY, ...graphPolicy, ...nodePolicy };
+    const maxAttempts = Math.max(1, Math.floor(merged.maxAttempts ?? DEFAULT_POLICY.maxAttempts));
+    return {
+        maxAttempts,
+        retryOnTimeout: merged.retryOnTimeout !== false,
+        retryOnTokenLimit: merged.retryOnTokenLimit !== false,
+        tokenBumpMultiplier: Math.max(1, merged.tokenBumpMultiplier ?? DEFAULT_POLICY.tokenBumpMultiplier),
+        tokenBumpCap: Math.max(1, merged.tokenBumpCap ?? DEFAULT_POLICY.tokenBumpCap),
+        baseMaxTokensFallback: Math.max(1, merged.baseMaxTokensFallback ?? DEFAULT_POLICY.baseMaxTokensFallback),
+    };
+}
+function readNum(v) {
+    return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+}
+function readMaxTokensFromRequest(req) {
+    const llm = req.llmCall;
+    return (readNum(llm?.maxTokens) ??
+        readNum(llm?.max_tokens));
+}
+function shallowCloneRunTaskRequest(req) {
+    return {
+        ...req,
+        ...(req.modelConfig != null && typeof req.modelConfig === 'object' && !Array.isArray(req.modelConfig)
+            ? { modelConfig: { ...req.modelConfig } }
+            : {}),
+        ...(req.llmCall != null && typeof req.llmCall === 'object' && !Array.isArray(req.llmCall)
+            ? { llmCall: { ...req.llmCall } }
+            : {}),
+        ...(req.input != null && typeof req.input === 'object' && !Array.isArray(req.input)
+            ? { input: { ...req.input } }
+            : {}),
+    };
+}
+function applyTokenBump(workingReq, policy) {
+    const current = readMaxTokensFromRequest(workingReq) ?? policy.baseMaxTokensFallback;
+    const after = Math.min(policy.tokenBumpCap, Math.floor(current * policy.tokenBumpMultiplier));
+    workingReq.llmCall =
+        workingReq.llmCall != null && typeof workingReq.llmCall === 'object' && !Array.isArray(workingReq.llmCall)
+            ? { ...workingReq.llmCall, maxTokens: after }
+            : { maxTokens: after };
+    return { before: current, after };
+}
+function classifyThrownError(err) {
+    if (err == null || typeof err !== 'object')
+        return 'other';
+    const e = err;
+    const code = typeof e.code === 'string' ? e.code : '';
+    const name = typeof e.name === 'string' ? e.name : '';
+    const msg = typeof e.message === 'string' ? e.message.toLowerCase() : '';
+    if (code === 'NODE_TIMEOUT' || code === 'ETIMEDOUT')
+        return 'timeout';
+    if (name === 'ProviderTimeoutError')
+        return 'timeout';
+    if (msg.includes('timed out') || msg.includes('timeout'))
+        return 'timeout';
+    if (code === 'MAX_TOKENS' ||
+        code === 'LENGTH' ||
+        code === 'OUTPUT_TRUNCATED' ||
+        code === 'CONTEXT_LENGTH_EXCEEDED') {
+        return 'token-limit';
+    }
+    return 'other';
+}
+function classifyResponseFailure(response) {
+    const err = response.error;
+    const code = typeof err?.code === 'string' ? err.code.toUpperCase() : '';
+    if (code === 'MAX_TOKENS' || code === 'LENGTH' || code === 'OUTPUT_TRUNCATED' || code === 'CONTEXT_LENGTH_EXCEEDED') {
+        return 'token-limit';
+    }
+    const parsed = response.parsed;
+    const meta = parsed?.meta;
+    const finishReason = typeof meta?.finishReason === 'string' ? meta.finishReason.toLowerCase() : '';
+    if (finishReason === 'length')
+        return 'token-limit';
+    if (code === 'ETIMEDOUT' || code === 'NODE_TIMEOUT')
+        return 'timeout';
+    const msg = typeof err?.message === 'string' ? err.message.toLowerCase() : '';
+    if (msg.includes('timed out') || msg.includes('timeout'))
+        return 'timeout';
+    return 'other';
+}
+function shouldRetryClassification(c, policy, attemptIndex) {
+    if (c === 'other')
+        return false;
+    if (attemptIndex >= policy.maxAttempts - 1)
+        return false;
+    if (c === 'timeout' && !policy.retryOnTimeout)
+        return false;
+    if (c === 'token-limit' && !policy.retryOnTokenLimit)
+        return false;
+    return true;
+}
+function pushSyntheticRunLog(out, args) {
+    out.push({
+        ts: Date.now(),
+        level: args.level,
+        scope: 'node',
+        nodeId: args.nodeId,
+        skillKey: args.skillKey,
+        message: args.message,
+        data: args.data,
+    });
+}
+export async function runRunTaskWithRetry(args) {
+    const { policy, nodeId, skillKey } = args;
+    let workingReq = shallowCloneRunTaskRequest(args.initialRequest);
+    const attempts = [];
+    const syntheticRunLog = [];
+    for (let attemptIndex = 0; attemptIndex < policy.maxAttempts; attemptIndex++) {
+        const startedAt = Date.now();
+        let response;
+        let thrown;
+        try {
+            const p = args.doRunTask(workingReq);
+            response = args.nodeTimeoutMs
+                ? await withTimeout(p, args.nodeTimeoutMs, args.nodeTimeoutErrorFactory)
+                : await p;
+        }
+        catch (e) {
+            thrown = e;
+        }
+        const endedAt = Date.now();
+        const durationMs = endedAt - startedAt;
+        const maxTok = readMaxTokensFromRequest(workingReq);
+        if (thrown != null) {
+            const c = classifyThrownError(thrown);
+            attempts.push({
+                index: attemptIndex,
+                ok: false,
+                startedAt,
+                endedAt,
+                durationMs,
+                classification: c,
+                errorCode: thrown?.code,
+                errorMessage: thrown?.message,
+                maxTokensRequested: maxTok,
+            });
+            pushSyntheticRunLog(syntheticRunLog, {
+                nodeId,
+                skillKey,
+                level: c === 'other' ? 'error' : 'warn',
+                message: `step attempt ${attemptIndex + 1}/${policy.maxAttempts} failed (${c})`,
+                data: {
+                    classification: c,
+                    errorCode: thrown?.code,
+                    maxTokensRequested: maxTok,
+                },
+            });
+            if (!shouldRetryClassification(c, policy, attemptIndex)) {
+                const err = thrown instanceof Error ? thrown : new Error(String(thrown));
+                err.syntheticStepRetryRunLog = syntheticRunLog;
+                err.stepRetryAttempts = attempts;
+                throw err;
+            }
+            if (c === 'token-limit' && policy.retryOnTokenLimit) {
+                const { before, after } = applyTokenBump(workingReq, policy);
+                pushSyntheticRunLog(syntheticRunLog, {
+                    nodeId,
+                    skillKey,
+                    level: 'info',
+                    message: `step retry ${attemptIndex + 2}/${policy.maxAttempts}: token-limit bump maxTokens ${before} -> ${after}`,
+                    data: { classification: c, maxTokensBefore: before, maxTokensAfter: after, attempt: attemptIndex + 1 },
+                });
+            }
+            continue;
+        }
+        if (response == null) {
+            const err = new Error('runTask returned undefined');
+            err.syntheticStepRetryRunLog = syntheticRunLog;
+            err.stepRetryAttempts = attempts;
+            throw err;
+        }
+        if (runTaskResponseSucceeded(response)) {
+            attempts.push({
+                index: attemptIndex,
+                ok: true,
+                startedAt,
+                endedAt,
+                durationMs,
+                maxTokensRequested: maxTok,
+            });
+            return { response, attempts, syntheticRunLog, lastRequest: workingReq };
+        }
+        const c = classifyResponseFailure(response);
+        attempts.push({
+            index: attemptIndex,
+            ok: false,
+            startedAt,
+            endedAt,
+            durationMs,
+            classification: c,
+            errorCode: response.error?.code,
+            errorMessage: response.error?.message,
+            maxTokensRequested: maxTok,
+        });
+        pushSyntheticRunLog(syntheticRunLog, {
+            nodeId,
+            skillKey,
+            level: c === 'other' ? 'error' : 'warn',
+            message: `step attempt ${attemptIndex + 1}/${policy.maxAttempts} failed (${c})`,
+            data: {
+                classification: c,
+                errorCode: response.error?.code,
+                maxTokensRequested: maxTok,
+            },
+        });
+        if (!shouldRetryClassification(c, policy, attemptIndex)) {
+            return { response, attempts, syntheticRunLog, lastRequest: workingReq };
+        }
+        if (c === 'token-limit' && policy.retryOnTokenLimit) {
+            const { before, after } = applyTokenBump(workingReq, policy);
+            pushSyntheticRunLog(syntheticRunLog, {
+                nodeId,
+                skillKey,
+                level: 'info',
+                message: `step retry ${attemptIndex + 2}/${policy.maxAttempts}: token-limit bump maxTokens ${before} -> ${after}`,
+                data: { classification: c, maxTokensBefore: before, maxTokensAfter: after, attempt: attemptIndex + 1 },
+            });
+        }
+    }
+    const err = new Error('runRunTaskWithRetry: exhausted attempts without result');
+    err.syntheticStepRetryRunLog = syntheticRunLog;
+    err.stepRetryAttempts = attempts;
+    throw err;
+}

package/dist/src/runtime/synthesizedContextPipeline.d.ts

@@ -0,0 +1,12 @@
+/**
+ * PRE `synthesized-context` step config normalization. Used by executeNode and ExellixGraphRuntime
+ * so explicit pipeline `config` is normalized; input synthesis is authored on `taskConfiguration.aiTaskProfile.inputSynthesis`.
+ */
+import type { ExecutionStepOption } from '../types/options.js';
+export declare function normalizeSynthesizedContextConfig(config: unknown): Record<string, unknown>;
+export type PipelineStep = ExecutionStepOption;
+/**
+ * When the pipeline includes a `pre` + `synthesized-context` step, shallow-merge
+ * a caller-supplied baseline into that step's `config` (step keys override).
+ */
+export declare function mergeNodeSynthesizedContextIntoPipeline(executionPipeline: PipelineStep[], rawNodeSynth: unknown): PipelineStep[];