@exellix/graph-engine 6.0.0

package/dist/src/playground/PlaygroundReporter.js

@@ -0,0 +1,480 @@
+/**
+ * Playground reporter: collects execution steps and in-memory debug artifacts
+ * for full visibility (graph start, plan rounds, node request/response/outputMapping, graph end).
+ *
+ * Each reporter instance corresponds to ONE graph execution.
+ * It never writes to the filesystem; callers can inspect artifacts via getArtifacts/getDebugSnapshot.
+ */
+const MAX_JSON_EXCERPT = 500;
+function safeKeys(obj) {
+    if (obj == null || typeof obj !== 'object')
+        return [];
+    return Object.keys(obj);
+}
+function jsonExcerpt(obj, maxLen = MAX_JSON_EXCERPT) {
+    try {
+        const s = JSON.stringify(obj, null, 2);
+        if (s.length <= maxLen)
+            return s;
+        return s.slice(0, maxLen) + '...';
+    }
+    catch {
+        return String(obj);
+    }
+}
+export function createPlaygroundReporter(options = {}) {
+    const { runId } = options;
+    const steps = [];
+    const artifacts = [];
+    /** Next 1-based step number to assign (single execution, single counter). */
+    let nextStep = 0;
+    /** nodeId -> assigned 1-based step number. */
+    const nodeStepIndex = new Map();
+    const artifactId = (stepNumber, nodeId, kind) => {
+        const prefix = stepNumber != null ? `${String(stepNumber).padStart(2, '0')}-` : '';
+        return `${prefix}${nodeId}-${kind}`;
+    };
+    const recordArtifact = (artifact) => {
+        const existingIndex = artifacts.findIndex((a) => a.artifactId === artifact.artifactId);
+        if (existingIndex >= 0) {
+            artifacts[existingIndex] = artifact;
+        }
+        else {
+            artifacts.push(artifact);
+        }
+    };
+    const step = (name, data) => {
+        const ts = Date.now();
+        steps.push({ name, data, ts });
+        if (!data)
+            return;
+        const nodeId = data.nodeId != null ? String(data.nodeId) : undefined;
+        if (!nodeId)
+            return;
+        if (name === 'node:request' && data.fullRequest !== undefined) {
+            nextStep += 1;
+            const stepNumber = nextStep;
+            nodeStepIndex.set(nodeId, stepNumber);
+            recordArtifact({
+                artifactId: artifactId(stepNumber, nodeId, 'request'),
+                kind: 'request',
+                nodeId,
+                stepNumber,
+                payload: data.fullRequest,
+                ts,
+            });
+        }
+        else if (name === 'node:response') {
+            const stepNumber = nodeStepIndex.get(nodeId);
+            const executionPart = data.execution !== undefined ? { execution: data.execution } : {};
+            const responsePayload = data.fullOutput !== undefined
+                ? { success: data.success !== false, output: data.fullOutput, ...executionPart }
+                : { success: data.success === true, error: data.errorMessage ?? data.error, ...executionPart };
+            recordArtifact({
+                artifactId: artifactId(stepNumber, nodeId, 'response'),
+                kind: 'response',
+                nodeId,
+                stepNumber,
+                payload: responsePayload,
+                ts,
+            });
+        }
+        else if (name === 'node:fail' && data.errorMessage != null) {
+            const stepNumber = nodeStepIndex.get(nodeId);
+            recordArtifact({
+                artifactId: artifactId(stepNumber, nodeId, 'response'),
+                kind: 'response',
+                nodeId,
+                stepNumber,
+                payload: {
+                    success: false,
+                    error: { message: data.errorMessage, code: data.errorCode },
+                    ...(data.execution !== undefined ? { execution: data.execution } : {}),
+                },
+                ts,
+            });
+        }
+    };
+    const getMarkdown = () => {
+        const lines = [];
+        lines.push('# Execution report');
+        lines.push('');
+        const startTs = steps[0]?.ts ?? Date.now();
+        const endTs = steps.length > 0 ? steps[steps.length - 1].ts : Date.now();
+        lines.push(`**Generated:** ${new Date().toISOString()} | **Duration:** ${endTs - startTs} ms`);
+        if (runId) {
+            lines.push(`**Run ID:** \`${runId}\``);
+        }
+        if (artifacts.length > 0) {
+            lines.push(`**Debug artifacts:** ${artifacts.length} full request/response payload(s) retained in memory via \`getArtifacts()\` / \`getDebugSnapshot()\`.`);
+        }
+        if (runId || artifacts.length > 0) {
+            lines.push('');
+        }
+        /** Step numbers for artifact ids: computed from execution order (node:request order). */
+        let nextStepRender = 0;
+        const nodeStepIndexRender = new Map();
+        let i = 0;
+        while (i < steps.length) {
+            const s = steps[i];
+            if (s.name === 'graph:start') {
+                lines.push('---');
+                lines.push('## Graph start');
+                lines.push('');
+                if (s.data?.jobId != null)
+                    lines.push(`- **Job ID:** ${s.data.jobId}`);
+                if (s.data?.graphId != null)
+                    lines.push(`- **Graph ID:** ${s.data.graphId}`);
+                if (s.data?.aiTasksPackageVersion != null) {
+                    lines.push(`- **@exellix/ai-tasks version:** \`${s.data.aiTasksPackageVersion}\``);
+                }
+                if (s.data?.exellixGraphPackageVersion != null) {
+                    lines.push(`- **@exellix/graph-engine version:** \`${s.data.exellixGraphPackageVersion}\``);
+                }
+                if (s.data?.executionKeys != null)
+                    lines.push(`- **Execution keys:** \`${s.data.executionKeys.join('`, `')}\``);
+                if (s.data?.variablesKeys != null)
+                    lines.push(`- **Variables keys:** \`${s.data.variablesKeys.join('`, `')}\``);
+                if (s.data?.executionExcerpt != null) {
+                    lines.push('- **Execution (excerpt):**');
+                    lines.push('```json');
+                    lines.push(String(s.data.executionExcerpt));
+                    lines.push('```');
+                }
+                lines.push('');
+                i++;
+                continue;
+            }
+            if (s.name === 'graph:observability') {
+                lines.push('### Runtime observability (`runtimeObjects`)');
+                lines.push('');
+                const d = s.data;
+                if (d?.lastJobId != null)
+                    lines.push(`- **lastJobId:** \`${d.lastJobId}\``);
+                lines.push(`- **Graph-level Activix client:** ${d?.graphActivix ? 'yes' : 'no'}`);
+                lines.push(`- **Graph-level Logxer client:** ${d?.graphLogxer ? 'yes' : 'no'}`);
+                if (d?.packages?.length) {
+                    lines.push('- **Packages:**');
+                    for (const p of d.packages) {
+                        lines.push(`  - \`${p.name}\`: activix=${p.activix}, logxer=${p.logxer}`);
+                    }
+                }
+                lines.push('');
+                i++;
+                continue;
+            }
+            if (s.name === 'plan') {
+                lines.push('### Plan round');
+                lines.push('');
+                if (s.data?.round != null)
+                    lines.push(`- **Round:** ${s.data.round}`);
+                if (s.data?.status != null)
+                    lines.push(`- **Status:** ${s.data.status}`);
+                if (s.data?.runnableNodeIds != null) {
+                    const ids = s.data.runnableNodeIds;
+                    lines.push(`- **Runnable nodes:** ${ids.length ? ids.join(', ') : '(none)'}`);
+                }
+                lines.push('');
+                i++;
+                continue;
+            }
+            if (s.name === 'node:start') {
+                lines.push(`### Node: ${s.data?.nodeId ?? '?'}`);
+                lines.push('');
+                if (s.data?.skillKey != null)
+                    lines.push(`- **Skill key:** \`${s.data.skillKey}\``);
+                if (s.data?.executionKeys != null)
+                    lines.push(`- **Execution keys (in):** \`${s.data.executionKeys.join('`, `')}\``);
+                lines.push('');
+                i++;
+                continue;
+            }
+            if (s.name === 'node:request') {
+                lines.push('- **Request:**');
+                if (s.data?.skillKey != null)
+                    lines.push(`  - skillKey: \`${s.data.skillKey}\``);
+                if (s.data?.executionMemoryKeys != null)
+                    lines.push(`  - executionMemory keys: \`${s.data.executionMemoryKeys.join('`, `')}\``);
+                if (s.data?.synthesisEnabled != null)
+                    lines.push(`  - synthesis enabled: ${s.data.synthesisEnabled}`);
+                if (s.data?.playgroundPhase != null)
+                    lines.push(`  - trace phase: \`${s.data.playgroundPhase}\``);
+                if (s.data?.synthesizedContextInMemoryBeforeTask != null) {
+                    lines.push(`  - **before runTask:** synthesizedContext already in executionMemory: ${s.data.synthesizedContextInMemoryBeforeTask}`);
+                }
+                if (s.data?.synthesizedContextCleared === true) {
+                    lines.push(`  - **synthesizedContext cleared before task** (\`clearSynthesizedContextPerNode=true\`): upstream artifact stripped; PRE will run fresh`);
+                }
+                if (s.data?.preRanFresh != null) {
+                    lines.push(`  - **preRanFresh:** ${s.data.preRanFresh}`);
+                }
+                if (s.data?.mainContextBeforeRunTask != null) {
+                    lines.push(`  - **before runTask (MAIN context):** ${s.data.mainContextBeforeRunTask}`);
+                }
+                if (s.data?.synthesizedContextInMemoryBeforeTask == null &&
+                    s.data?.synthesizedContextPresent != null) {
+                    lines.push(`  - synthesizedContext present (legacy): ${s.data.synthesizedContextPresent}`);
+                }
+                if (s.data?.mainContextBeforeRunTask == null && s.data?.mainContextSource != null) {
+                    lines.push(`  - main context source (legacy): \`${s.data.mainContextSource}\``);
+                }
+                if (s.data?.effectiveExecutionPipeline != null) {
+                    lines.push(`  - effective pipeline: \`${JSON.stringify(s.data.effectiveExecutionPipeline)}\``);
+                }
+                if (s.data?.nodeId != null && s.data.fullRequest !== undefined) {
+                    const n = String(s.data.nodeId);
+                    nextStepRender += 1;
+                    const stepNum = nextStepRender;
+                    nodeStepIndexRender.set(n, stepNum);
+                    lines.push(`  - **Full request artifact:** \`${artifactId(stepNum, n, 'request')}\``);
+                }
+                lines.push('');
+                i++;
+                continue;
+            }
+            if (s.name === 'node:response') {
+                lines.push('- **Response:**');
+                if (s.data?.success != null)
+                    lines.push(`  - success: ${s.data.success}`);
+                if (s.data?.outputKeys != null)
+                    lines.push(`  - output keys: \`${s.data.outputKeys.join('`, `')}\``);
+                if (s.data?.synthesisEnabled != null)
+                    lines.push(`  - synthesis enabled: ${s.data.synthesisEnabled}`);
+                if (s.data?.playgroundPhase != null)
+                    lines.push(`  - trace phase: \`${s.data.playgroundPhase}\``);
+                if (s.data?.synthesizedContextInMemoryAfterTask != null) {
+                    lines.push(`  - **after runTask:** synthesizedContext in executionMemory: ${s.data.synthesizedContextInMemoryAfterTask}`);
+                }
+                if (s.data?.inferredMainContextForMainStep != null) {
+                    lines.push(`  - **after runTask:** inferred MAIN input source: \`${s.data.inferredMainContextForMainStep}\` (from executionMemory shape; see ai-tasks metadata for authoritative MAIN routing)`);
+                }
+                if (s.data?.synthesizedContextInMemoryAfterTask == null &&
+                    s.data?.synthesizedContextPresent != null) {
+                    lines.push(`  - synthesizedContext present (legacy): ${s.data.synthesizedContextPresent}`);
+                }
+                if (s.data?.inferredMainContextForMainStep == null && s.data?.mainContextSource != null) {
+                    lines.push(`  - main context source (legacy): \`${s.data.mainContextSource}\``);
+                }
+                if (s.data?.effectiveExecutionPipeline != null) {
+                    lines.push(`  - effective pipeline: \`${JSON.stringify(s.data.effectiveExecutionPipeline)}\``);
+                }
+                if (s.data?.synthesizedContextCleared === true) {
+                    lines.push(`  - **synthesizedContext cleared before task** (\`clearSynthesizedContextPerNode=true\`): PRE ran fresh`);
+                }
+                if (s.data?.preRanFresh != null) {
+                    lines.push(`  - **preRanFresh:** ${s.data.preRanFresh}`);
+                }
+                if (s.data?.aiTasksObservability != null && typeof s.data.aiTasksObservability === 'object') {
+                    const obs = s.data.aiTasksObservability;
+                    const cores = obs.detectedTemplateCores;
+                    const coresEmpty = Array.isArray(cores) && cores.length === 0;
+                    const synthEnabled = obs.synthesisEnabled === true;
+                    lines.push('  - **ai-tasks observability (metadata):**');
+                    if (synthEnabled && coresEmpty) {
+                        lines.push('    > ⚠ `detectedTemplateCores` is empty — template-core detection did not fire. Structured synthesis anchors may be missing from the skill template.');
+                    }
+                    lines.push('    ```json');
+                    String(JSON.stringify(s.data.aiTasksObservability, null, 2))
+                        .split('\n')
+                        .forEach((l) => lines.push('    ' + l));
+                    lines.push('    ```');
+                }
+                if (s.data?.outputExcerpt != null) {
+                    lines.push('  - output (excerpt):');
+                    lines.push('    ```json');
+                    String(s.data.outputExcerpt).split('\n').forEach((l) => lines.push('    ' + l));
+                    lines.push('    ```');
+                }
+                if (s.data?.errorMessage != null)
+                    lines.push(`  - error: ${s.data.errorMessage}`);
+                const execution = s.data?.execution;
+                const webContext = execution != null && typeof execution === 'object'
+                    ? execution.webContext
+                    : undefined;
+                if (webContext != null && typeof webContext === 'object') {
+                    const available = webContext.available;
+                    if (typeof available === 'boolean') {
+                        lines.push('  - **Web scoping:**');
+                        lines.push(`    - available: ${available}`);
+                        if (available === true) {
+                            const ctx = webContext.context;
+                            const findings = ctx?.findings;
+                            const findingsArr = Array.isArray(findings) ? findings : [];
+                            lines.push(`    - findings: ${findingsArr.length}`);
+                            // Small, capped URL sample for readability.
+                            const urls = [];
+                            for (const f of findingsArr.slice(0, 3)) {
+                                const sources = f?.sources;
+                                if (!Array.isArray(sources))
+                                    continue;
+                                for (const src of sources.slice(0, 3)) {
+                                    const url = src?.url;
+                                    if (typeof url === 'string' && url.length > 0)
+                                        urls.push(url);
+                                    if (urls.length >= 6)
+                                        break;
+                                }
+                                if (urls.length >= 6)
+                                    break;
+                            }
+                            if (urls.length > 0) {
+                                lines.push('    - source URLs (sample):');
+                                urls.forEach((u) => lines.push(`      - ${u}`));
+                            }
+                        }
+                        else {
+                            const reason = webContext.reason;
+                            if (typeof reason === 'string' && reason.length > 0) {
+                                lines.push(`    - reason: ${reason}`);
+                            }
+                        }
+                    }
+                }
+                if (s.data?.nodeId != null) {
+                    const n = String(s.data.nodeId);
+                    const stepNum = nodeStepIndexRender.get(n);
+                    lines.push(`  - **Full response artifact:** \`${artifactId(stepNum, n, 'response')}\``);
+                }
+                if (s.data?.intermediateSteps != null && Array.isArray(s.data.intermediateSteps) && s.data.intermediateSteps.length > 0) {
+                    lines.push('  - **Intermediate steps (combined task):**');
+                    s.data.intermediateSteps.forEach((step, idx) => {
+                        const id = step.id ?? step.step ?? idx + 1;
+                        const summary = step.summary != null ? ` — ${String(step.summary)}` : '';
+                        const ok = step.ok !== false ? 'ok' : 'fail';
+                        lines.push(`    - ${idx + 1}. ${id}${summary} — ${ok}`);
+                    });
+                }
+                lines.push('');
+                i++;
+                continue;
+            }
+            if (s.name === 'node:outputMapping') {
+                lines.push('- **Output mapping:**');
+                if (s.data?.path != null)
+                    lines.push(`  - path: \`${s.data.path}\``);
+                if (s.data?.mode != null)
+                    lines.push(`  - mode: ${s.data.mode}`);
+                if (s.data?.executionKeysAfter != null)
+                    lines.push(`  - execution keys after: \`${s.data.executionKeysAfter.join('`, `')}\``);
+                lines.push('');
+                i++;
+                continue;
+            }
+            if (s.name === 'node:complete') {
+                lines.push('- **Result:** complete');
+                if (s.data?.executionKeys != null)
+                    lines.push(`  - execution keys: \`${s.data.executionKeys.join('`, `')}\``);
+                lines.push('');
+                i++;
+                continue;
+            }
+            if (s.name === 'node:fail') {
+                lines.push('- **Result:** fail');
+                if (s.data?.errorMessage != null)
+                    lines.push(`  - error: ${s.data.errorMessage}`);
+                if (s.data?.errorCode != null)
+                    lines.push(`  - code: ${s.data.errorCode}`);
+                const execution = s.data?.execution;
+                const webContext = execution != null && typeof execution === 'object'
+                    ? execution.webContext
+                    : undefined;
+                if (webContext != null && typeof webContext === 'object') {
+                    const available = webContext.available;
+                    if (typeof available === 'boolean') {
+                        lines.push('  - **Web scoping:**');
+                        lines.push(`    - available: ${available}`);
+                        if (available === false) {
+                            const reason = webContext.reason;
+                            if (typeof reason === 'string' && reason.length > 0) {
+                                lines.push(`    - reason: ${reason}`);
+                            }
+                        }
+                        else {
+                            const ctx = webContext.context;
+                            const findings = ctx?.findings;
+                            const findingsArr = Array.isArray(findings) ? findings : [];
+                            lines.push(`    - findings: ${findingsArr.length}`);
+                        }
+                    }
+                }
+                lines.push('');
+                i++;
+                continue;
+            }
+            if (s.name === 'graph:complete') {
+                lines.push('## Graph complete');
+                lines.push('');
+                if (s.data?.nodesExecuted != null)
+                    lines.push(`- **Nodes executed:** ${s.data.nodesExecuted}`);
+                if (s.data?.executionKeys != null)
+                    lines.push(`- **Final execution keys:** \`${s.data.executionKeys.join('`, `')}\``);
+                lines.push('');
+                i++;
+                continue;
+            }
+            if (s.name === 'graph:fail') {
+                lines.push('## Graph fail');
+                lines.push('');
+                if (s.data?.errorMessage != null)
+                    lines.push(`- **Error:** ${s.data.errorMessage}`);
+                if (s.data?.errorCode != null)
+                    lines.push(`- **Code:** ${s.data.errorCode}`);
+                if (s.data?.executionKeys != null)
+                    lines.push(`- **Execution keys at fail:** \`${s.data.executionKeys.join('`, `')}\``);
+                lines.push('');
+                i++;
+                continue;
+            }
+            if (s.name === 'ai-activities') {
+                lines.push('---');
+                lines.push('## AI activities');
+                lines.push('');
+                if (s.data?.activities != null && Array.isArray(s.data.activities) && s.data.activities.length > 0) {
+                    const activities = s.data.activities;
+                    activities.forEach((a, idx) => {
+                        lines.push(`- **${idx + 1}.** ${a.nodeId ?? a.activityId ?? '?'}${a.activityId != null ? ` (activityId: \`${a.activityId}\`)` : ''}`);
+                    });
+                    lines.push('');
+                }
+                else {
+                    lines.push('*Not collected for this run. AI activities are recorded when `ActivityTrackerIntegration` is used with `executeGraph` (eventEmitter). Query MongoDB collection `cognitive-activities` by `jobId`/`graphId` to see them.*');
+                    lines.push('');
+                }
+                i++;
+                continue;
+            }
+            lines.push(`### ${s.name}`);
+            if (s.data && Object.keys(s.data).length > 0) {
+                lines.push('```json');
+                lines.push(jsonExcerpt(s.data));
+                lines.push('```');
+                lines.push('');
+            }
+            i++;
+        }
+        // Always append AI activities section (empty unless step('ai-activities', { activities }) was used)
+        const hasAiActivitiesStep = steps.some((st) => st.name === 'ai-activities');
+        if (!hasAiActivitiesStep) {
+            lines.push('---');
+            lines.push('## AI activities');
+            lines.push('');
+            lines.push('*Not collected for this run. AI activities are recorded when `ActivityTrackerIntegration` is used with `executeGraph` (eventEmitter). Query MongoDB collection `cognitive-activities` by `jobId`/`graphId` to see them.*');
+            lines.push('');
+        }
+        return lines.join('\n');
+    };
+    const getSteps = () => steps.map((s) => ({ ...s }));
+    const getArtifacts = () => artifacts.map((a) => ({ ...a }));
+    const getDebugSnapshot = () => {
+        const snapshot = {
+            steps: getSteps(),
+            artifacts: getArtifacts(),
+            markdown: getMarkdown(),
+        };
+        if (runId !== undefined) {
+            snapshot.runId = runId;
+        }
+        return snapshot;
+    };
+    return { step, getSteps, getArtifacts, getDebugSnapshot, getMarkdown };
+}

package/dist/src/playground/index.d.ts

@@ -0,0 +1 @@
+export { createPlaygroundReporter, type CreatePlaygroundReporterOptions, type PlaygroundDebugArtifact, type PlaygroundDebugArtifactKind, type PlaygroundDebugSnapshot, type PlaygroundReporter, type PlaygroundStep, } from './PlaygroundReporter.js';

package/dist/src/playground/index.js

@@ -0,0 +1 @@
+export { createPlaygroundReporter, } from './PlaygroundReporter.js';