@exellix/graph-engine 6.0.0

package/dist/src/types/events.d.ts

@@ -0,0 +1,23 @@
+import { GraphNode } from './refs.js';
+/**
+ * Event types emitted during graph execution
+ */
+export interface GraphExecutionEvent {
+    type: 'graph:start' | 'graph:complete' | 'graph:fail' | 'node:start' | 'node:complete' | 'node:fail';
+    timestamp: number;
+    /** Host correlation id (mandatory on every `executeGraph` call). */
+    jobId: string;
+    /** One UUID per graph run — generated inside graph-engine, sent on every `runTask` as `taskId`. */
+    taskId: string;
+    graphId: string;
+    nodeId?: string;
+    data?: any;
+}
+export interface NodeExecutionEvent extends GraphExecutionEvent {
+    type: 'node:start' | 'node:complete' | 'node:fail';
+    nodeId: string;
+    node: GraphNode;
+    skillKey?: string;
+    result?: any;
+    error?: any;
+}

package/dist/src/types/events.js

@@ -0,0 +1 @@
+export {};

package/dist/src/types/job.d.ts

@@ -0,0 +1,9 @@
+import { Job } from './refs.js';
+/**
+ * Job execution context
+ */
+export interface JobContext {
+    job: Job;
+    jobId: string;
+    agentId?: string;
+}

package/dist/src/types/job.js

@@ -0,0 +1 @@
+export {};

package/dist/src/types/narrix.d.ts

@@ -0,0 +1,60 @@
+import type { RunTaskRequest } from '@exellix/ai-tasks';
+/** Same as `RunTaskRequest['narrix']` (ai-tasks exports `RunTaskRequest` but not this alias on the root barrel). */
+type AITasksNarrixPreProcessorConfig = NonNullable<RunTaskRequest['narrix']>;
+/**
+ * Graph-engine wire shape for the resolved `RunTaskRequest.narrix` payload after merging
+ * `taskConfiguration.aiTaskProfile.webScoping` into `taskConfiguration.narrix`. Used internally; authors do
+ * **not** set web-scope fields on `taskConfiguration.narrix`.
+ */
+export type ResolvedNarrixWirePayload = AITasksNarrixPreProcessorConfig;
+/** One web-scope question on the resolved narrix wire payload; produced from `aiTaskProfile.webScoping.questions`. */
+export type WebScopeQuestion = {
+    id: string;
+    question: string;
+    purpose?: string;
+};
+/**
+ * Authoring shape for `taskConfiguration.narrix` on a graph task node — discovery only.
+ *
+ * 5.x removed every web-scope key from this type. Authors set web intent under
+ * `taskConfiguration.aiTaskProfile.webScoping` (`enabled`, `questions: string[]`); graph-engine
+ * fills the corresponding fields on the resolved `RunTaskRequest.narrix` automatically,
+ * and `assertCanonicalGraphDocument` rejects web-scope keys here at load time.
+ */
+export type NarrixPreProcessorConfig = {
+    /** Which pack and entity type the engine runs (e.g. `"network.vuln.instances"`). */
+    datasetId?: string;
+    /**
+     * Opaque string from graph JSON (`taskConfiguration.narrix.layer`). Forwarded to NARRIX pack lookup only.
+     * Vocabulary and meaning live in your graph set / pack model — not in exellix-graph.
+     */
+    layer?: string;
+    /** Narrative type IDs from the catalog this node can produce or consume. */
+    narrativeTypeIds?: string[];
+    /** Framework question this node answers (e.g. q0, q1, q2, q3, q5, q6). */
+    questionId?: string;
+};
+/**
+ * Context shape passed to NARRIX graph task handlers (matches ai-tasks LocalTaskContext).
+ */
+export type LocalTaskHandler = (args: {
+    input: unknown;
+    ctx: LocalTaskContext;
+}) => Promise<unknown>;
+export interface LocalTaskContext {
+    taskId?: string;
+    skillKey?: string;
+    jobMemory?: Record<string, unknown>;
+    taskMemory?: Record<string, unknown>;
+    executionMemory?: Record<string, unknown>;
+    variables?: Record<string, unknown>;
+    jobId?: string;
+    agentId?: string;
+    graphId?: string;
+    nodeId?: string;
+    prevNodeId?: string;
+    coreSkillId?: string;
+    masterSkillId?: string;
+    masterSkillActivityId?: string;
+}
+export {};

package/dist/src/types/narrix.js

@@ -0,0 +1 @@
+export {};

package/dist/src/types/options.d.ts

@@ -0,0 +1,122 @@
+import type { Activix } from '@x12i/activix';
+import type { LlmCallConfig, RunTaskRequest as AiTasksRunTaskRequest, RunTaskResponse as AiTasksRunTaskResponse } from '@exellix/ai-tasks';
+import type { GraphModelAliasConfig, ModelConfigSelection, TaskNodeRuntimeObject } from './refs.js';
+import type { RuntimeObjects } from '../runtime/runtimeObjects.js';
+/**
+ * NOTE: `@exellix/ai-tasks` 5.5+ removed the exported `RunTaskDiagnostics` type.
+ * We keep a permissive type here for forward-compat while still forwarding the object to `runTask`.
+ */
+export type RunTaskDiagnostics = Record<string, unknown>;
+/** One step in the execution pipeline (pre → main → post). Compatible with @exellix/ai-tasks ExecutionStep. */
+export interface ExecutionStepOption {
+    phase: 'pre' | 'main' | 'post';
+    type: string;
+    config?: unknown;
+}
+/**
+ * Skill key resolution options
+ */
+export interface SkillKeyResolutionOptions {
+    allowFallbackToNodeId?: boolean;
+    fallbackPrefix?: string;
+    aliases?: Record<string, string>;
+}
+/**
+ * Per-task-node retry policy for transient `runTask` failures (timeouts, token-limit).
+ * Graph-level defaults may be overridden by `node.taskConfiguration.stepRetryPolicy`.
+ */
+export interface StepRetryPolicy {
+    /** Total attempts including the first (default **3**). Minimum **1**. */
+    maxAttempts?: number;
+    /** When false, timeouts do not trigger an automatic retry. Default **true**. */
+    retryOnTimeout?: boolean;
+    /** When false, token-limit signals do not trigger retry / bump. Default **true**. */
+    retryOnTokenLimit?: boolean;
+    /** Applied to effective max tokens before each token-limit retry (default **2**). */
+    tokenBumpMultiplier?: number;
+    /** Upper bound for `maxTokens` after bump (default **16000**). */
+    tokenBumpCap?: number;
+    /**
+     * Used when neither `llmCall.maxTokens` nor `llmCall.max_tokens` is set on the outbound request
+     * (default **2000**). `modelConfig` is reserved for model selection.
+     */
+    baseMaxTokensFallback?: number;
+}
+/** MAIN gate before `runTask`: empty execution input / synthesis context (graphs-studio G1, G4). */
+export type MainReadinessPolicy = 'fail' | 'warn' | 'off';
+/**
+ * Run-scoped knobs for `GraphRuntimeObject` (merged with {@link ExellixGraphRuntimeOptions} defaults).
+ *
+ * Precedence: explicit per-invocation input fields override `ExellixGraphRuntimeOptions` defaults.
+ * Within a node, graph-level `executionPipeline` overrides lose to node / `execution.executionPipeline`.
+ */
+export interface HostExecuteGraphRunOptions {
+    /**
+     * Stop scheduling further nodes after first failure when true.
+     * Default in 5.x: `false` (canonical `createExellixGraphRuntime().executeGraph(...)`).
+     */
+    failFast?: boolean;
+    skillKeyResolution?: SkillKeyResolutionOptions;
+    nodeTimeoutMs?: number;
+    executionPipeline?: ExecutionStepOption[];
+    playgroundMeta?: Record<string, unknown>;
+    clearSynthesizedContextPerNode?: boolean;
+    modelConfig?: ModelConfigSelection;
+    aliasConfig?: GraphModelAliasConfig;
+    nodes?: Record<string, TaskNodeRuntimeObject>;
+    llmCall?: LlmCallConfig;
+    runTaskIdentity?: Record<string, unknown>;
+    runTaskExecutionMode?: 'default' | 'trace';
+    runLogMode?: import('./runLog.js').RunLogMode;
+    maxRunLogEntries?: number;
+    maxRunLogDataJsonChars?: number;
+    runTaskDiagnostics?: RunTaskDiagnostics;
+    runtimeObjects?: RuntimeObjects;
+    /** Optional defaults for automatic step retries (timeouts / token-limit); node metadata may override. */
+    stepRetryPolicy?: StepRetryPolicy;
+    /**
+     * When `fail` or `warn`, checks declared graph entry / smart-input paths before MAIN `runTask`.
+     * Node `taskConfiguration.mainReadinessPolicy` overrides. Default `off`.
+     */
+    mainReadinessPolicy?: MainReadinessPolicy;
+}
+/**
+ * Optional Activix-backed persistence for per-node execution rows.
+ * When this block is present, logging is on unless `enabled: false`.
+ */
+export interface ActivixNodeActivityExellixConfig {
+    /** Default true when `activixNodeActivity` is set. */
+    enabled?: boolean;
+    activix: Activix;
+    /** Activix collection role for node activity rows. */
+    collection?: string;
+    /** Attach lightweight input hints on `node:start` records. */
+    includeInputSnapshot?: boolean;
+    /**
+     * When true, attempt to extract structured NARRIX outcome fields from `node:complete` output
+     * and persist them as `narrixSummary` in the node activity row.
+     */
+    extractNarrixOutcome?: boolean;
+}
+/** Canonical shape: `@exellix/ai-tasks` `RUNTASK_REQUEST.md` (required `jobTypeId`, `taskTypeId`, canonical `input`). */
+export type RunTaskRequest = AiTasksRunTaskRequest;
+/**
+ * Task client response: `@exellix/ai-tasks` / `@exellix/ai-skills` payload plus adapter fields used by graph-engine
+ * (`success`, `ok`, `output`, `rawContent`) when using {@link ../testkit/RealTasksClient.ts} or mocks.
+ */
+export type RunTaskResponse = AiTasksRunTaskResponse & {
+    success?: boolean;
+    ok?: boolean;
+    output?: unknown;
+    rawContent?: string;
+    error?: {
+        code?: string;
+        message?: string;
+        diagnostics?: unknown;
+        [key: string]: unknown;
+    };
+    execution?: unknown;
+    executionMemory?: unknown;
+    meta?: Record<string, unknown>;
+    [key: string]: unknown;
+};

package/dist/src/types/options.js

@@ -0,0 +1 @@
+export {};