@noetic-tools/core 1.2.0 → 1.2.2

package/dist/harness/agent-harness.d.ts

@@ -105,6 +105,13 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
     readonly layerStateStore: LayerStateStore;
     /** Per-harness memoization cache for `recallMode: 'eventual'` layers. */
     readonly recallCache: RecallCache;
+    /**
+     * Execution ids whose layer `init` hooks have already run, so repeated/nested
+     * `run()` calls and the session turn path never re-init (which would clobber
+     * accumulated in-memory state by re-hydrating from storage). Keyed by
+     * `ctx.id` (the layer-state store's executionId).
+     */
+    private readonly initializedExecutions;
     readonly traceExporter: TraceExporter;
     /**
      * Long-lived shared cwd state. The same reference is seeded into every
@@ -143,6 +150,14 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
     /** Run all layer `init` hooks before the first step executes. Per spec 11,
      *  init MUST complete before any recall fires so layer state is populated. */
     private initAndRun;
+    /**
+     * Idempotently run layer `init` hooks for `ctx` (keyed by `ctx.id`). Init
+     * MUST complete before any recall/store fires so init-bearing layers are not
+     * treated as disabled. Guarded so nested/repeated `run()` calls and the
+     * session turn path never re-init — re-init would re-hydrate from storage and
+     * clobber accumulated in-memory state.
+     */
+    private ensureLayersInit;
     detachedSpawn<I, O>(s: Step<ContextMemory, I, O>, input: I, parentCtx: Context, overrides?: DetachedSpawnOverrides): DetachedHandle<O>;
     createContext(opts?: {
         parent?: Context;

package/dist/harness/agent-harness.js

@@ -110,6 +110,13 @@ export class AgentHarness {
     layerStateStore;
     /** Per-harness memoization cache for `recallMode: 'eventual'` layers. */
     recallCache;
+    /**
+     * Execution ids whose layer `init` hooks have already run, so repeated/nested
+     * `run()` calls and the session turn path never re-init (which would clobber
+     * accumulated in-memory state by re-hydrating from storage). Keyed by
+     * `ctx.id` (the layer-state store's executionId).
+     */
+    initializedExecutions = new Set();
     traceExporter;
     /**
      * Long-lived shared cwd state. The same reference is seeded into every
@@ -342,6 +349,7 @@ export class AgentHarness {
             callModelOverride: this.callModelOverride,
             streamIdleTimeoutMs: this.streamIdleTimeoutMs,
             harness: this,
+            traceExporter: this.traceExporter,
         }).callModel(request);
     }
     //#endregion
@@ -356,17 +364,36 @@ export class AgentHarness {
                 ...this.harnessTools,
             ]);
         }
+        // Hydrate/recall/persist memory on the bare `run()` path too (issue #48):
+        // configuring `memory` + `storage` must "just work" without going through
+        // `execute()`/`seedSessionHistory`. Idempotent — see `ensureLayersInit`.
+        await this.ensureLayersInit(ctx);
         return execute(s, input, ctx);
     }
     /** Run all layer `init` hooks before the first step executes. Per spec 11,
      *  init MUST complete before any recall fires so layer state is populated. */
     async initAndRun(s, input, ctx) {
+        await this.ensureLayersInit(ctx);
+        return execute(s, input, ctx);
+    }
+    /**
+     * Idempotently run layer `init` hooks for `ctx` (keyed by `ctx.id`). Init
+     * MUST complete before any recall/store fires so init-bearing layers are not
+     * treated as disabled. Guarded so nested/repeated `run()` calls and the
+     * session turn path never re-init — re-init would re-hydrate from storage and
+     * clobber accumulated in-memory state.
+     */
+    async ensureLayersInit(ctx) {
         const layers = ctx.layers;
         const storage = this.config.storage;
-        if (layers && layers.length > 0 && storage) {
-            await this.initLayers(layers, ctx, storage);
+        if (!layers || layers.length === 0 || !storage) {
+            return;
         }
-        return execute(s, input, ctx);
+        if (this.initializedExecutions.has(ctx.id)) {
+            return;
+        }
+        this.initializedExecutions.add(ctx.id);
+        await this.initLayers(layers, ctx, storage);
     }
     detachedSpawn(s, input, parentCtx, overrides) {
         return dispatchStepThroughAdapter(this, s, input, parentCtx, overrides);
@@ -538,6 +565,9 @@ export class AgentHarness {
         });
     }
     async disposeLayers(layers, ctx) {
+        // Drop the init guard so a deliberate dispose→run cycle re-hydrates from
+        // storage (disposeLayers also clears the layer-state store for this id).
+        this.initializedExecutions.delete(ctx.id);
         await disposeLayers({
             layers,
             ctx: this.toExecCtx(ctx),

package/dist/harness/model-call.d.ts

@@ -1,4 +1,4 @@
-import type { AgentHarnessContract, CallModelRequest, ItemSchemaRegistry, LLMResponse } from '@noetic-tools/types';
+import type { AgentHarnessContract, CallModelRequest, ItemSchemaRegistry, LLMResponse, TraceExporter } from '@noetic-tools/types';
 import type { OpenRouter } from '@openrouter/agent';
 import type { MessageQueue } from '../runtime/message-queue.js';
 interface StreamIdleWatchdog {
@@ -28,13 +28,16 @@ interface AgentHarnessModelCallerOpts {
     callModelOverride?: (request: CallModelRequest) => Promise<LLMResponse>;
     streamIdleTimeoutMs: number;
     harness: AgentHarnessContract;
+    traceExporter: TraceExporter;
 }
 export declare class AgentHarnessModelCaller {
     private readonly opts;
     constructor(opts: AgentHarnessModelCallerOpts);
+    private newSpanCollector;
     private callOverriddenModel;
     private requireModelClient;
     callModel(request: CallModelRequest): Promise<LLMResponse>;
+    private runModelLoop;
     private injectBetweenRoundMessages;
     private handleModelRecovery;
     private handleEmptyOutputRecovery;

package/dist/harness/model-call.js

@@ -2,6 +2,7 @@ import { frameworkCast, NoeticConfigError } from '@noetic-tools/types';
 import { z } from 'zod';
 import { convertTools, executeToolCall, extractOutputItems, extractSystemInstruction, extractUsage, itemsToInput, sanitizeToolNameForWire, } from '../adapters/openrouter.js';
 import { isFunctionCall } from '../interpreter/typeguards.js';
+import { GenAI, ToolAttr } from '../observability/genai-attributes.js';
 import { emitFrameworkEvent, getBroadcaster, shouldEmit } from '../runtime/broadcaster-utils.js';
 import { buildItemSchemaRegistry, createToolResultItem } from './model-schema.js';
 const MAX_TOOL_ROUNDS = 32;
@@ -219,25 +220,85 @@ function filterAllowedTools(request) {
     const allowedNames = new Set(request.allowedToolNames);
     return request.tools.filter((tool) => allowedNames.has(tool.name));
 }
+/**
+ * Per-`callModel` span accumulator. Spans are created lazily from the calling
+ * context's span (so the trace tree mirrors the execution tree) and flushed to
+ * the harness `traceExporter` once the call settles — see issue #50, where the
+ * exporter was stored but never invoked.
+ */
+class CallSpanCollector {
+    harness;
+    exporter;
+    parent;
+    spans = [];
+    constructor(harness, exporter, parent) {
+        this.harness = harness;
+        this.exporter = exporter;
+        this.parent = parent;
+    }
+    /** Open a model-call span stamped with GenAI semantic-convention attributes. */
+    startModelSpan(model) {
+        const span = this.harness.createSpan('llm.call', this.parent);
+        span.setAttribute(GenAI.SYSTEM, 'openrouter');
+        span.setAttribute(GenAI.REQUEST_MODEL, model);
+        this.spans.push(span);
+        return span;
+    }
+    /** Record usage + cost on a model-call span. */
+    finishModelSpan(span, usage, cost) {
+        span.setAttribute(GenAI.USAGE_INPUT_TOKENS, usage.inputTokens);
+        span.setAttribute(GenAI.USAGE_OUTPUT_TOKENS, usage.outputTokens);
+        if (cost !== undefined) {
+            span.setAttribute(GenAI.COST, cost);
+        }
+        span.end();
+    }
+    /** Open and immediately close a tool-call span under the given model span. */
+    recordToolSpan(parent, toolName, needsApproval) {
+        const span = this.harness.createSpan('tool.call', parent);
+        span.setAttribute(ToolAttr.NAME, toolName);
+        span.setAttribute(ToolAttr.NEEDS_APPROVAL, needsApproval);
+        span.end();
+        this.spans.push(span);
+    }
+    /** Flush all accumulated spans to the exporter. */
+    async flush() {
+        if (this.spans.length === 0) {
+            return;
+        }
+        await this.exporter.export(this.spans);
+    }
+}
 export class AgentHarnessModelCaller {
     opts;
     constructor(opts) {
         this.opts = opts;
     }
+    newSpanCollector(request) {
+        return new CallSpanCollector(this.opts.harness, this.opts.traceExporter, request.parentSpan ?? request.ctx?.span ?? null);
+    }
     async callOverriddenModel(request) {
         if (!this.opts.callModelOverride) {
             throw new Error('No callModel override configured.');
         }
-        const response = await this.opts.callModelOverride(request);
-        const itemSchemas = buildItemSchemaRegistry({
-            base: this.opts.itemSchemas,
-            layers: request.layers,
-            tools: request.tools,
-        });
-        return {
-            ...response,
-            items: itemSchemas.parseMany(response.items),
-        };
+        const spans = this.newSpanCollector(request);
+        const modelSpan = spans.startModelSpan(request.model);
+        try {
+            const response = await this.opts.callModelOverride(request);
+            const itemSchemas = buildItemSchemaRegistry({
+                base: this.opts.itemSchemas,
+                layers: request.layers,
+                tools: request.tools,
+            });
+            spans.finishModelSpan(modelSpan, response.usage, response.cost);
+            return {
+                ...response,
+                items: itemSchemas.parseMany(response.items),
+            };
+        }
+        finally {
+            await spans.flush();
+        }
     }
     requireModelClient() {
         if (this.opts.client) {
@@ -254,6 +315,15 @@ export class AgentHarnessModelCaller {
             return this.callOverriddenModel(request);
         }
         const client = this.requireModelClient();
+        const spans = this.newSpanCollector(request);
+        try {
+            return await this.runModelLoop(request, client, spans);
+        }
+        finally {
+            await spans.flush();
+        }
+    }
+    async runModelLoop(request, client, spans) {
         const prepared = prepareModelRequest(request, this.opts.agentName);
         const allItems = [];
         const totalUsage = {
@@ -299,6 +369,7 @@ export class AgentHarnessModelCaller {
                 toolCount: prepared.sdkTools?.length ?? 0,
                 recoveryContinuation,
             });
+            const modelSpan = spans.startModelSpan(request.model);
             const callResult = client.callModel({
                 model: request.model,
                 input: modelInput,
@@ -360,6 +431,7 @@ export class AgentHarnessModelCaller {
                 emitIfAllowed: prepared.emitIfAllowed,
             });
             if (recovery.kind === 'continue') {
+                modelSpan.end();
                 invalidRecoveryContinuations = recovery.invalidRecoveryContinuations;
                 useEphemeralContinue = true;
                 continue;
@@ -378,6 +450,7 @@ export class AgentHarnessModelCaller {
                 emitIfAllowed: prepared.emitIfAllowed,
             });
             if (outputRecovery.kind === 'continue') {
+                modelSpan.end();
                 invalidRecoveryContinuations = outputRecovery.invalidRecoveryContinuations;
                 useEphemeralContinue = true;
                 continue;
@@ -388,10 +461,15 @@ export class AgentHarnessModelCaller {
                 itemCount: sdkResponse.output?.length ?? 0,
             });
             const roundUsage = extractUsage(sdkResponse.usage);
+            const roundCost = sdkResponse.usage?.cost ?? 0;
+            spans.finishModelSpan(modelSpan, {
+                inputTokens: roundUsage.inputTokens,
+                outputTokens: roundUsage.outputTokens,
+            }, roundCost > 0 ? roundCost : undefined);
             totalUsage.inputTokens += roundUsage.inputTokens;
             totalUsage.outputTokens += roundUsage.outputTokens;
             totalUsage.cachedTokens += roundUsage.cachedTokens ?? 0;
-            totalCost += sdkResponse.usage?.cost ?? 0;
+            totalCost += roundCost;
             allItems.push(...roundItems);
             const functionCalls = roundItems.filter(isFunctionCall);
             if (functionCalls.length === 0 || !request.tools) {
@@ -404,6 +482,8 @@ export class AgentHarnessModelCaller {
                 conversationInput,
                 round,
                 emitIfAllowed: prepared.emitIfAllowed,
+                spans,
+                modelSpan,
             });
             round += 1;
             const limitRecovery = this.handleToolRoundLimit({
@@ -516,7 +596,7 @@ export class AgentHarnessModelCaller {
         };
     }
     async executeToolRound(params) {
-        const { functionCalls, request, allItems, conversationInput } = params;
+        const { functionCalls, request, allItems, conversationInput, spans, modelSpan } = params;
         params.emitIfAllowed('tool_round_started', {
             round: params.round,
             toolCount: functionCalls.length,
@@ -534,6 +614,8 @@ export class AgentHarnessModelCaller {
             if (request.signal?.aborted) {
                 break;
             }
+            const toolForCall = request.tools?.find((tool) => tool.name === fc.name || sanitizeToolNameForWire(tool.name) === fc.name);
+            spans.recordToolSpan(modelSpan, fc.name, toolForCall?.needsApproval ?? false);
             await this.executeFunctionCall({
                 fc,
                 request,

package/dist/index.d.ts

@@ -72,7 +72,7 @@ export { durableTaskState, fileReference, findFunctionCall, historyWindow, obser
 /** @public */
 export { createMessage, estimateTokens } from '@noetic-tools/types';
 /** @public */
-export { GenAI, ToolAttr } from './observability/genai-attributes.js';
+export { GenAI, NoeticAttr, ToolAttr } from './observability/genai-attributes.js';
 /** @public */
 export { InMemoryExporter, NoopExporter } from './observability/trace-exporter.js';
 /** @public */

package/dist/index.js

@@ -66,7 +66,7 @@ export { createMessage, estimateTokens } from '@noetic-tools/types';
 //#endregion
 //#region Observability
 /** @public */
-export { GenAI, ToolAttr } from './observability/genai-attributes.js';
+export { GenAI, NoeticAttr, ToolAttr } from './observability/genai-attributes.js';
 /** @public */
 export { InMemoryExporter, NoopExporter } from './observability/trace-exporter.js';
 /** @public */

package/dist/interpreter/execute-action.js

@@ -293,6 +293,7 @@ export async function executeLLM(step, input, ctx, layers) {
                 ctx: baseCtx,
                 layers,
                 allowedToolNames,
+                parentSpan: baseCtx.span,
             }
             : {
                 model: resolvedModel,
@@ -301,6 +302,7 @@ export async function executeLLM(step, input, ctx, layers) {
                 params: step.params,
                 outputSchema: step.output,
                 emit: step.emit,
+                parentSpan: baseCtx.span,
             };
         const response = await baseCtx.harness.callModel(request);
         // Track tokens/cost for EVERY model call, including responses steering

package/dist/observability/genai-attributes.d.ts

@@ -9,3 +9,15 @@ export declare const ToolAttr: {
     readonly NAME: "tool.name";
     readonly NEEDS_APPROVAL: "tool.needs_approval";
 };
+export declare const NoeticAttr: {
+    /** Full JSON-serialised `WorkflowDocument` (the DAG, lossless). */
+    readonly WORKFLOW_DOCUMENT: "noetic.workflow.document";
+    /** Workflow document schema version. */
+    readonly WORKFLOW_VERSION: "noetic.workflow.version";
+    /** Count of declared nodes in the workflow tree. */
+    readonly WORKFLOW_NODE_COUNT: "noetic.workflow.node_count";
+    /** JSON array of `{ id, kind }` for every declared node (flattened graph). */
+    readonly WORKFLOW_NODES: "noetic.workflow.nodes";
+    /** JSON array of `{ from, to }` parent→child edges between declared nodes. */
+    readonly WORKFLOW_EDGES: "noetic.workflow.edges";
+};

package/dist/observability/genai-attributes.js

@@ -10,3 +10,17 @@ export const ToolAttr = {
     NAME: 'tool.name',
     NEEDS_APPROVAL: 'tool.needs_approval',
 };
+// Noetic-specific span attributes describing the static workflow graph (the
+// "potential paths" of the DAG) carried on the root `workflow.run` span.
+export const NoeticAttr = {
+    /** Full JSON-serialised `WorkflowDocument` (the DAG, lossless). */
+    WORKFLOW_DOCUMENT: 'noetic.workflow.document',
+    /** Workflow document schema version. */
+    WORKFLOW_VERSION: 'noetic.workflow.version',
+    /** Count of declared nodes in the workflow tree. */
+    WORKFLOW_NODE_COUNT: 'noetic.workflow.node_count',
+    /** JSON array of `{ id, kind }` for every declared node (flattened graph). */
+    WORKFLOW_NODES: 'noetic.workflow.nodes',
+    /** JSON array of `{ from, to }` parent→child edges between declared nodes. */
+    WORKFLOW_EDGES: 'noetic.workflow.edges',
+};

package/dist/patterns/dynamic-workflow.js

@@ -5,7 +5,8 @@
 import { frameworkCast, NoeticConfigError } from '@noetic-tools/types';
 import { step } from '../builders/step-builders.js';
 import { hydrateWorkflow } from '../builders/workflow-hydrator.js';
-import { WorkflowDocumentSchema, workflowDepth } from '../schemas/workflow.js';
+import { NoeticAttr } from '../observability/genai-attributes.js';
+import { WorkflowDocumentSchema, workflowDepth, workflowGraph } from '../schemas/workflow.js';
 //#endregion
 //#region Constants
 const DEFAULT_MAX_DEPTH = 5;
@@ -143,8 +144,38 @@ export async function parseAndRunWorkflow(opts) {
         executeStep,
     };
     const hydrated = hydrateWorkflow(parseResult.doc, hydrationCtx);
-    const result = await executeStep(hydrated, opts.input ?? '', opts.ctx);
-    return coerceToString(result);
+    const runSpan = beginWorkflowRunSpan(opts.harness, opts.ctx, parseResult.doc);
+    try {
+        const result = await executeStep(hydrated, opts.input ?? '', opts.ctx);
+        return coerceToString(result);
+    }
+    finally {
+        runSpan.end();
+        await opts.harness.traceExporter.export([
+            runSpan,
+        ]);
+    }
+}
+/**
+ * Open the root `workflow.run` span and stamp the static DAG onto it (document,
+ * version, node/edge graph). The span is installed on `ctx.span` so the LLM
+ * step's model/tool spans nest under it — the trace tree then mirrors the
+ * declared workflow graph, with the executed path overlaid (issue #50 follow-up).
+ */
+function beginWorkflowRunSpan(harness, ctx, doc) {
+    const span = harness.createSpan('workflow.run', null);
+    const graph = workflowGraph(doc.root);
+    span.setAttribute(NoeticAttr.WORKFLOW_DOCUMENT, JSON.stringify(doc));
+    span.setAttribute(NoeticAttr.WORKFLOW_VERSION, doc.version);
+    span.setAttribute(NoeticAttr.WORKFLOW_NODE_COUNT, graph.nodes.length);
+    span.setAttribute(NoeticAttr.WORKFLOW_NODES, JSON.stringify(graph.nodes));
+    span.setAttribute(NoeticAttr.WORKFLOW_EDGES, JSON.stringify(graph.edges));
+    installRunSpan(ctx, span);
+    return span;
+}
+/** Install the run span as `ctx.span` so descendant model calls parent under it. */
+function installRunSpan(ctx, span) {
+    frameworkCast(ctx).span = span;
 }
 function buildToolMap(tools) {
     return new Map(tools.map((t) => [

package/dist/schemas/workflow.d.ts

@@ -164,6 +164,23 @@ export declare const WorkflowDocumentSchema: z.ZodType<WorkflowDocument>;
 export declare function validateWorkflow(input: unknown): WorkflowDocument;
 /** Walks a workflow tree depth-first, yielding each node. */
 export declare function walkWorkflow(node: WorkflowNode): Iterable<WorkflowNode>;
+/** A flattened, JSON-safe view of a workflow tree: its nodes and parent→child edges. */
+export interface WorkflowGraph {
+    nodes: Array<{
+        id: string;
+        kind: WorkflowNode['kind'];
+    }>;
+    edges: Array<{
+        from: string;
+        to: string;
+    }>;
+}
+/**
+ * Flattens a workflow tree into a node + edge list — the static "potential
+ * paths" of the DAG, suitable for attaching to a trace span so observers can
+ * reconstruct the declared graph independent of which branches actually ran.
+ */
+export declare function workflowGraph(root: WorkflowNode): WorkflowGraph;
 /**
  * Returns the maximum depth of a workflow tree.
  * Leaf nodes (`llm`, `tool`) have depth 0. Structural nodes add +1.

package/dist/schemas/workflow.js

@@ -279,6 +279,31 @@ export function* walkWorkflow(node) {
         yield* walkWorkflow(child);
     }
 }
+/**
+ * Flattens a workflow tree into a node + edge list — the static "potential
+ * paths" of the DAG, suitable for attaching to a trace span so observers can
+ * reconstruct the declared graph independent of which branches actually ran.
+ */
+export function workflowGraph(root) {
+    const nodes = [];
+    const edges = [];
+    for (const node of walkWorkflow(root)) {
+        nodes.push({
+            id: node.id,
+            kind: node.kind,
+        });
+        for (const child of childNodes(node)) {
+            edges.push({
+                from: node.id,
+                to: child.id,
+            });
+        }
+    }
+    return {
+        nodes,
+        edges,
+    };
+}
 /**
  * Returns the maximum depth of a workflow tree.
  * Leaf nodes (`llm`, `tool`) have depth 0. Structural nodes add +1.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/core",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "type": "module",
   "description": "Step primitives, interpreter, runtime, and memory layer contract for Noetic agents.",
   "license": "Apache-2.0",
@@ -67,7 +67,7 @@
   },
   "dependencies": {
     "@noetic-tools/memory": "^1.0.1",
-    "@noetic-tools/types": "^1.0.1",
+    "@noetic-tools/types": "^1.0.2",
     "@openrouter/agent": "^0.6.0",
     "zod": "^4.0.0"
   },