@exellix/graph-engine 6.0.0

package/dist/src/runtime/synthesizedContextPipeline.js

@@ -0,0 +1,28 @@
+export function normalizeSynthesizedContextConfig(config) {
+    const normalized = config != null && typeof config === 'object' && !Array.isArray(config)
+        ? { ...config }
+        : {};
+    if (typeof normalized.mode === 'string' && normalized.synthesisMode === undefined) {
+        normalized.synthesisMode = normalized.mode;
+    }
+    return normalized;
+}
+/**
+ * When the pipeline includes a `pre` + `synthesized-context` step, shallow-merge
+ * a caller-supplied baseline into that step's `config` (step keys override).
+ */
+export function mergeNodeSynthesizedContextIntoPipeline(executionPipeline, rawNodeSynth) {
+    const hasSynthesizedContextPre = executionPipeline.some((s) => s.phase === 'pre' && s.type === 'synthesized-context');
+    if (!hasSynthesizedContextPre)
+        return executionPipeline;
+    const nodeSynthBaseline = rawNodeSynth != null && rawNodeSynth !== false
+        ? normalizeSynthesizedContextConfig(rawNodeSynth)
+        : {};
+    return executionPipeline.map((s) => {
+        if (s.phase === 'pre' && s.type === 'synthesized-context') {
+            const stepConfig = normalizeSynthesizedContextConfig(s.config);
+            return { ...s, config: { ...nodeSynthBaseline, ...stepConfig } };
+        }
+        return s;
+    });
+}

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

@@ -0,0 +1,27 @@
+import type { RunxClient } from '@x12i/runx';
+import type { TaskNodeConditionWhen, TaskNodeConditions } from '../types/refs.js';
+import type { PredicateEvalContext } from './predicates.js';
+export type TaskNodeConditionEvalContext = PredicateEvalContext & {
+    job?: unknown;
+};
+export type TaskNodeConditionsEvalDeps = {
+    runx?: RunxClient;
+};
+export type TaskNodeConditionsEvalResult = {
+    ok: true;
+} | {
+    ok: false;
+    skipReason: string;
+    error?: string;
+};
+export declare function applyConditionNegate(meetsCondition: boolean, negate?: boolean): boolean;
+/** AND across present gates in a `when` block. */
+export declare function evaluateConditionWhen(when: TaskNodeConditionWhen, ctx: TaskNodeConditionEvalContext, executionInput: Record<string, unknown>, deps: TaskNodeConditionsEvalDeps): Promise<{
+    ok: boolean;
+    skipReason?: string;
+    error?: string;
+}>;
+/**
+ * Returns whether the node should run. False → caller should skip the node.
+ */
+export declare function evaluateTaskNodeConditions(conditions: TaskNodeConditions | undefined, ctx: TaskNodeConditionEvalContext, executionInput: Record<string, unknown>, deps: TaskNodeConditionsEvalDeps): Promise<TaskNodeConditionsEvalResult>;

package/dist/src/runtime/taskNodeConditionsEvaluation.js

@@ -0,0 +1,140 @@
+import { checkContentCondition } from '@x12i/runx/condition';
+export function applyConditionNegate(meetsCondition, negate) {
+    return negate === true ? !meetsCondition : meetsCondition;
+}
+function buildConditionContent(ctx, executionInput) {
+    const em = ctx.executionMemory != null && typeof ctx.executionMemory === 'object' && !Array.isArray(ctx.executionMemory)
+        ? ctx.executionMemory
+        : undefined;
+    return {
+        data: executionInput,
+        input: executionInput,
+        executionMemory: ctx.executionMemory,
+        variables: em?.jobVariables ?? ctx.variables,
+        jobVariables: em?.jobVariables ?? ctx.variables,
+        taskVariables: em?.taskVariables,
+        jobMemory: ctx.jobMemory,
+        taskMemory: ctx.taskMemory,
+        job: ctx.job,
+    };
+}
+function normalizeCapabilityBoolean(output) {
+    if (typeof output === 'boolean')
+        return output;
+    if (output != null && typeof output === 'object' && !Array.isArray(output)) {
+        const o = output;
+        if (typeof o.meetsCondition === 'boolean')
+            return o.meetsCondition;
+        if (typeof o.ok === 'boolean' && 'meetsCondition' in o)
+            return o.meetsCondition;
+    }
+    return undefined;
+}
+async function evaluateJsonCondition(spec, content, deps) {
+    const result = await checkContentCondition({
+        content,
+        condition: spec.condition,
+        parameters: spec.parameters,
+        conditionType: 'json',
+        mode: 'deterministic',
+        options: spec.options,
+    }, deps.runx?.funcx != null ? { funcx: deps.runx.funcx } : undefined);
+    if (!result.ok) {
+        return { ok: false, error: result.error };
+    }
+    return { ok: applyConditionNegate(result.meetsCondition, spec.negate) };
+}
+async function evaluateJsCondition(spec, content, deps) {
+    if (!deps.runx) {
+        return { ok: false, error: 'runx client is required for jsConditionFunction' };
+    }
+    const runResult = await deps.runx.run(spec.conditionFunctionId, {
+        content,
+        parameters: spec.parameters ?? {},
+    });
+    if (!runResult.ok) {
+        return { ok: false, error: String(runResult.error ?? 'runx.run failed') };
+    }
+    const meets = normalizeCapabilityBoolean(runResult.output);
+    if (meets === undefined) {
+        return { ok: false, error: 'jsConditionFunction capability must return boolean or { meetsCondition: boolean }' };
+    }
+    return { ok: applyConditionNegate(meets, spec.negate) };
+}
+async function evaluateAiCondition(spec, content, deps) {
+    const mode = spec.mode ?? 'hybrid';
+    const result = await checkContentCondition({
+        content,
+        condition: spec.condition,
+        parameters: spec.parameters,
+        conditionType: 'json',
+        mode,
+        model: spec.model,
+        client: deps.runx?.funcx,
+    }, deps.runx?.funcx != null ? { funcx: deps.runx.funcx } : undefined);
+    if (!result.ok) {
+        return { ok: false, error: result.error };
+    }
+    return { ok: applyConditionNegate(result.meetsCondition, spec.negate) };
+}
+/** AND across present gates in a `when` block. */
+export async function evaluateConditionWhen(when, ctx, executionInput, deps) {
+    const content = buildConditionContent(ctx, executionInput);
+    if (when.jsonConditions != null) {
+        const ev = await evaluateJsonCondition(when.jsonConditions, content, deps);
+        if (ev.error) {
+            return { ok: false, skipReason: 'condition_eval_error', error: ev.error };
+        }
+        if (!ev.ok) {
+            return { ok: false, skipReason: 'json_conditions' };
+        }
+    }
+    if (when.jsConditionFunction != null) {
+        const ev = await evaluateJsCondition(when.jsConditionFunction, content, deps);
+        if (ev.error) {
+            return { ok: false, skipReason: 'condition_eval_error', error: ev.error };
+        }
+        if (!ev.ok) {
+            return { ok: false, skipReason: 'js_condition' };
+        }
+    }
+    if (when.aiCondition != null) {
+        const ev = await evaluateAiCondition(when.aiCondition, content, deps);
+        if (ev.error) {
+            return { ok: false, skipReason: 'condition_eval_error', error: ev.error };
+        }
+        if (!ev.ok) {
+            return { ok: false, skipReason: 'ai_condition' };
+        }
+    }
+    return { ok: true };
+}
+function hasEvaluatedConditionGate(conditions) {
+    if (conditions == null)
+        return false;
+    return (conditions.jsonConditions != null ||
+        conditions.jsConditionFunction != null ||
+        conditions.aiCondition != null);
+}
+/**
+ * Returns whether the node should run. False → caller should skip the node.
+ */
+export async function evaluateTaskNodeConditions(conditions, ctx, executionInput, deps) {
+    if (!hasEvaluatedConditionGate(conditions)) {
+        return { ok: true };
+    }
+    const when = {
+        jsonConditions: conditions.jsonConditions,
+        jsConditionFunction: conditions.jsConditionFunction,
+        aiCondition: conditions.aiCondition,
+    };
+    const ev = await evaluateConditionWhen(when, ctx, executionInput, deps);
+    if (ev.ok) {
+        return { ok: true };
+    }
+    return {
+        ok: false,
+        skipReason: ev.skipReason ?? 'condition_eval_error',
+        error: ev.error,
+    };
+}

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

@@ -0,0 +1,45 @@
+import type { GraphEntryContract, TaskNode } from '../types/refs.js';
+import type { MainReadinessPolicy } from '../types/options.js';
+import { type GraphEngineMemoryResolutionRoot } from './resolveGraphEngineMemoryPaths.js';
+export type { MainReadinessPolicy };
+/** Check ids aligned with graphs-studio Run Analysis (G1, G4). */
+export type MainReadinessCheckId = 'execution_input_empty' | 'synthesis_context_empty';
+export type MainReadinessEvaluation = {
+    policy: MainReadinessPolicy;
+    ok: boolean;
+    failedChecks: MainReadinessCheckId[];
+    warnings: MainReadinessCheckId[];
+    pathsByCheck: Partial<Record<MainReadinessCheckId, string[]>>;
+};
+export { normalizeSmartInputPath } from './smartInputPaths.js';
+export declare function collectInputSynthesisSourcePaths(node: TaskNode): string[];
+/**
+ * Evaluates MAIN-readiness before invoking the skill. Paths resolve via {@link resolveGraphEngineMemoryPathValue}
+ * (`input.*` and `inputs.*` are distinct roots). Policy `off` skips all checks.
+ */
+export declare function evaluateTaskNodeMainReadiness(args: {
+    policy: MainReadinessPolicy;
+    node: TaskNode;
+    graphEntry?: GraphEntryContract;
+    resolutionRoot: GraphEngineMemoryResolutionRoot;
+    smartInputPaths?: string[];
+    inputSynthesisPaths?: string[];
+}): MainReadinessEvaluation;
+export declare function buildMainReadinessResolutionRoot(args: {
+    taskInput: Record<string, unknown>;
+    callerInputs?: Record<string, unknown>;
+    executionMemory: Record<string, unknown>;
+    xynthesized: {
+        job: Record<string, unknown>;
+        task: Record<string, unknown>;
+        execution?: Record<string, unknown>;
+    };
+    jobMemory?: unknown;
+    taskMemory?: unknown;
+}): GraphEngineMemoryResolutionRoot;
+export declare function resolveMainReadinessPolicy(args: {
+    runtimePolicy?: MainReadinessPolicy;
+    nodeTaskConfiguration?: Record<string, unknown>;
+}): MainReadinessPolicy;
+/** Normalizes a smart-input path entry to a memory root key (for inspection helpers). */
+export declare function smartInputPathRoot(path: string): string | undefined;

package/dist/src/runtime/taskNodeMainReadiness.js

@@ -0,0 +1,164 @@
+import { splitGraphEngineMemoryPath } from './graphEngineMemoryPaths.js';
+import { buildMemoryResolutionRootFromExecution } from './executionVariableBuckets.js';
+import { resolveGraphEngineMemoryPathValue, } from './resolveGraphEngineMemoryPaths.js';
+function isPlainObject(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+function isEmptyReadinessValue(value) {
+    if (value === undefined || value === null)
+        return true;
+    if (typeof value === 'string')
+        return value.trim() === '';
+    if (Array.isArray(value))
+        return value.length === 0;
+    if (isPlainObject(value))
+        return Object.keys(value).length === 0;
+    return false;
+}
+export { normalizeSmartInputPath } from './smartInputPaths.js';
+import { collectSmartInputPaths } from './smartInputPaths.js';
+export function collectInputSynthesisSourcePaths(node) {
+    const profile = node.taskConfiguration?.aiTaskProfile;
+    const sources = profile?.inputSynthesis?.sources;
+    if (!Array.isArray(sources))
+        return [];
+    return sources
+        .map((s) => (typeof s === 'string' ? s.trim() : undefined))
+        .filter((s) => s != null && s.length > 0);
+}
+function collectGraphEntryInputPaths(graphEntry) {
+    const paths = new Set();
+    for (const p of graphEntry?.requiredExecutionPaths ?? []) {
+        if (typeof p === 'string' && p.trim() !== '')
+            paths.add(p.trim());
+    }
+    for (const spec of graphEntry?.inputs ?? []) {
+        if (spec == null || typeof spec !== 'object')
+            continue;
+        const rec = spec;
+        if (rec.kind === 'execution')
+            continue;
+        if (rec.required === false)
+            continue;
+        if (typeof rec.path === 'string' && rec.path.trim() !== '')
+            paths.add(rec.path.trim());
+    }
+    return [...paths];
+}
+function executionInputWatchPaths(args) {
+    const paths = new Set();
+    for (const p of collectGraphEntryInputPaths(args.graphEntry)) {
+        if (p === 'input' || p.startsWith('input.'))
+            paths.add(p);
+    }
+    for (const p of [...args.smartInputPaths, ...args.inputSynthesisPaths]) {
+        if (p === 'input' || p.startsWith('input.'))
+            paths.add(p);
+    }
+    return [...paths];
+}
+function synthesisWatchPaths(smartInputPaths, inputSynthesisPaths) {
+    const paths = new Set();
+    for (const p of [...smartInputPaths, ...inputSynthesisPaths]) {
+        const trimmed = p.trim();
+        if (trimmed === 'xynthesized.job' || trimmed.startsWith('xynthesized.job.')) {
+            paths.add(trimmed === 'xynthesized.job' ? 'xynthesized.job' : trimmed);
+        }
+        if (trimmed === 'xynthesized.execution' || trimmed.startsWith('xynthesized.execution.')) {
+            paths.add(trimmed === 'xynthesized.execution' ? 'xynthesized.execution' : trimmed);
+        }
+    }
+    return [...paths];
+}
+function pathRequiresDeclaredEntry(path, graphEntry) {
+    if (graphEntry == null)
+        return false;
+    const declared = collectGraphEntryInputPaths(graphEntry);
+    if (declared.length > 0)
+        return true;
+    return (graphEntry.inputs?.length ?? 0) > 0 || (graphEntry.requiredExecutionPaths?.length ?? 0) > 0;
+}
+/**
+ * Evaluates MAIN-readiness before invoking the skill. Paths resolve via {@link resolveGraphEngineMemoryPathValue}
+ * (`input.*` and `inputs.*` are distinct roots). Policy `off` skips all checks.
+ */
+export function evaluateTaskNodeMainReadiness(args) {
+    const policy = args.policy ?? 'off';
+    const smartInputPaths = args.smartInputPaths ?? collectSmartInputPaths(args.node);
+    const inputSynthesisPaths = args.inputSynthesisPaths ?? collectInputSynthesisSourcePaths(args.node);
+    const failedChecks = [];
+    const warnings = [];
+    const pathsByCheck = {};
+    if (policy === 'off') {
+        return { policy, ok: true, failedChecks, warnings, pathsByCheck };
+    }
+    const inputPaths = executionInputWatchPaths({
+        graphEntry: args.graphEntry,
+        smartInputPaths,
+        inputSynthesisPaths,
+    });
+    const emptyInputPaths = [];
+    const graphEntryDeclaresInputs = pathRequiresDeclaredEntry('input', args.graphEntry);
+    if (graphEntryDeclaresInputs || inputPaths.length > 0) {
+        const toCheck = inputPaths.length > 0
+            ? inputPaths
+            : collectGraphEntryInputPaths(args.graphEntry).filter((p) => p === 'input' || p.startsWith('input.'));
+        for (const path of toCheck) {
+            const value = resolveGraphEngineMemoryPathValue(args.resolutionRoot, path);
+            if (isEmptyReadinessValue(value))
+                emptyInputPaths.push(path);
+        }
+        if (emptyInputPaths.length > 0) {
+            pathsByCheck.execution_input_empty = emptyInputPaths;
+            if (policy === 'fail')
+                failedChecks.push('execution_input_empty');
+            else
+                warnings.push('execution_input_empty');
+        }
+    }
+    const synthPaths = synthesisWatchPaths(smartInputPaths, inputSynthesisPaths);
+    const emptySynthPaths = [];
+    for (const path of synthPaths) {
+        const value = resolveGraphEngineMemoryPathValue(args.resolutionRoot, path);
+        if (isEmptyReadinessValue(value))
+            emptySynthPaths.push(path);
+    }
+    if (emptySynthPaths.length > 0) {
+        pathsByCheck.synthesis_context_empty = emptySynthPaths;
+        if (policy === 'fail')
+            failedChecks.push('synthesis_context_empty');
+        else
+            warnings.push('synthesis_context_empty');
+    }
+    return {
+        policy,
+        ok: failedChecks.length === 0,
+        failedChecks,
+        warnings,
+        pathsByCheck,
+    };
+}
+export function buildMainReadinessResolutionRoot(args) {
+    return buildMemoryResolutionRootFromExecution({
+        execution: args.executionMemory,
+        input: args.taskInput,
+        inputs: args.callerInputs,
+        jobMemory: args.jobMemory,
+        taskMemory: args.taskMemory,
+        xynthesized: args.xynthesized,
+    });
+}
+export function resolveMainReadinessPolicy(args) {
+    const nodePolicy = args.nodeTaskConfiguration?.mainReadinessPolicy;
+    if (nodePolicy === 'fail' || nodePolicy === 'warn' || nodePolicy === 'off')
+        return nodePolicy;
+    const rt = args.runtimePolicy;
+    if (rt === 'fail' || rt === 'warn' || rt === 'off')
+        return rt;
+    return 'off';
+}
+/** Normalizes a smart-input path entry to a memory root key (for inspection helpers). */
+export function smartInputPathRoot(path) {
+    const { root } = splitGraphEngineMemoryPath(path.trim());
+    return root ?? undefined;
+}

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

@@ -0,0 +1,89 @@
+/**
+ * Graph-level preflight for `@exellix/ai-tasks` validation and analysis on task nodes.
+ * Builds the same outbound {@link RunTaskRequest} as `executeNode` (without PRE strategy phases or `runTask`).
+ */
+import type { Catalox } from '@x12i/catalox';
+import type { RunTaskRequest } from '@exellix/ai-tasks';
+import { type AnalyzeRunTaskRequestOptions, type AnalyzeRunTaskRequestResult, type RunTaskInvokeValidationResult, type RunTaskValidationResult, type ValidateRunTaskInvokeParams } from '@exellix/ai-tasks';
+import type { GraphAiModelConfig, Job, TaskNode } from '../types/refs.js';
+import type { ExecutionStepOption, RunTaskDiagnostics, SkillKeyResolutionOptions } from '../types/options.js';
+export type TaskNodeRunTaskPreflightSkipReason = 'local_skill' | 'finalizer';
+export type BuildTaskNodeRunTaskRequestResult = {
+    runnable: true;
+    skillKey: string;
+    request: RunTaskRequest;
+} | {
+    runnable: false;
+    skillKey: string;
+    reason: TaskNodeRunTaskPreflightSkipReason;
+};
+export type BuildTaskNodeRunTaskRequestArgs = {
+    graphId: string;
+    node: TaskNode;
+    job: Job;
+    execution?: Record<string, unknown>;
+    jobMemory?: unknown;
+    taskMemory?: unknown;
+    taskVariables?: Record<string, unknown>;
+    prevNodeId?: string;
+    /** Same UUID used for every `runTask` in one `executeGraph` invocation. */
+    graphRunTaskId?: string;
+    /** Host job id on `job.jobId` / `job.id`; defaults from `job` when omitted. */
+    runTaskJobId?: string;
+    modelConfig?: GraphAiModelConfig;
+    llmCall?: Record<string, unknown>;
+    /** Runtime default merged with per-node `taskConfiguration.llmCall`. */
+    runtimeLlmCall?: Record<string, unknown>;
+    runTaskIdentity?: Record<string, unknown>;
+    runTaskExecutionMode?: 'default' | 'trace';
+    runTaskDiagnostics?: RunTaskDiagnostics;
+    jobKnowledgePatch?: Record<string, unknown>;
+    taskKnowledgePatch?: Record<string, unknown>;
+    graphExecutionPipeline?: ExecutionStepOption[];
+    skillKeyResolution?: SkillKeyResolutionOptions;
+    clearSynthesizedContextPerNode?: boolean;
+};
+/**
+ * Materialize the outbound `RunTaskRequest` graph-engine would send for a task node
+ * (mirrors `executeNode` request assembly; does not run PRE strategy phases or `runTask`).
+ */
+export declare function buildTaskNodeRunTaskRequest(args: BuildTaskNodeRunTaskRequestArgs): BuildTaskNodeRunTaskRequestResult;
+export type ValidateTaskNodeRunTaskConfigArgs = BuildTaskNodeRunTaskRequestArgs;
+export type ValidateTaskNodeRunTaskConfigResult = {
+    skipped: true;
+    skillKey: string;
+    reason: TaskNodeRunTaskPreflightSkipReason;
+} | ({
+    skipped: false;
+    skillKey: string;
+    request: RunTaskRequest;
+} & RunTaskValidationResult);
+/** Static ai-tasks validation on the graph-built {@link RunTaskRequest}. */
+export declare function validateTaskNodeRunTaskConfig(args: ValidateTaskNodeRunTaskConfigArgs): ValidateTaskNodeRunTaskConfigResult;
+export type ValidateTaskNodeRunTaskInvokeArgs = BuildTaskNodeRunTaskRequestArgs & Omit<ValidateRunTaskInvokeParams, 'request'>;
+export type ValidateTaskNodeRunTaskInvokeResult = {
+    skipped: true;
+    skillKey: string;
+    reason: TaskNodeRunTaskPreflightSkipReason;
+} | ({
+    skipped: false;
+    skillKey: string;
+    request: RunTaskRequest;
+} & RunTaskInvokeValidationResult);
+/** Config + payload + template path validation via ai-tasks {@link validateRunTaskInvoke}. */
+export declare function validateTaskNodeRunTaskInvoke(args: ValidateTaskNodeRunTaskInvokeArgs): Promise<ValidateTaskNodeRunTaskInvokeResult>;
+export type AnalyzeTaskNodeRunTaskRequestArgs = BuildTaskNodeRunTaskRequestArgs & {
+    catalox: Catalox;
+    analyzeOptions?: AnalyzeRunTaskRequestOptions;
+};
+export type AnalyzeTaskNodeRunTaskRequestResult = {
+    skipped: true;
+    skillKey: string;
+    reason: TaskNodeRunTaskPreflightSkipReason;
+} | ({
+    skipped: false;
+    skillKey: string;
+    request: RunTaskRequest;
+} & AnalyzeRunTaskRequestResult);
+/** Catalox-backed skill request analysis on the graph-built {@link RunTaskRequest}. */
+export declare function analyzeTaskNodeRunTaskRequest(args: AnalyzeTaskNodeRunTaskRequestArgs): Promise<AnalyzeTaskNodeRunTaskRequestResult>;