@noetic-tools/core 2.2.1 → 2.3.0

package/dist/builders/step-builders.d.ts

@@ -66,7 +66,7 @@ export declare const step: {
      * @throws `NoeticConfigError` with code `MISSING_EXECUTE_FUNCTION` if `execute` is not provided.
      * @throws `NoeticConfigError` with code `DUPLICATE_STEP_ID` if another step with the same id is already registered with a different body.
      */
-    run<TMemory = Readonly<Record<string, Record<string, unknown>>>, I = unknown, O = unknown>(opts: StepRunOpts<TMemory, I, O>): StepRun<TMemory, I, O>;
+    run<TMemory = ContextMemory, I = unknown, O = unknown>(opts: StepRunOpts<TMemory, I, O>): StepRun<TMemory, I, O>;
     /**
      * Creates an LLM model call step with optional tools and structured output.
      *
@@ -82,7 +82,7 @@ export declare const step: {
      * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
      * @throws `NoeticConfigError` with code `MISSING_MODEL` if an eager `model` string is empty. Function-form models are validated at step execution.
      */
-    llm<TMemory = Readonly<Record<string, Record<string, unknown>>>, I = unknown, O = unknown>(opts: StepLLMOpts<TMemory, O>): StepLLM<TMemory, I, O>;
+    llm<TMemory = ContextMemory, I = unknown, O = unknown>(opts: StepLLMOpts<TMemory, O>): StepLLM<TMemory, I, O>;
     /**
      * Creates a tool execution step that invokes a typed tool definition.
      *
@@ -95,7 +95,7 @@ export declare const step: {
      * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
      * @throws `NoeticConfigError` with code `MISSING_TOOL` if `tool` is not provided.
      */
-    tool<TMemory = Readonly<Record<string, Record<string, unknown>>>, I = unknown, O = unknown>(opts: StepToolOpts<I, O>): StepTool<TMemory, I, O>;
+    tool<TMemory = ContextMemory, I = unknown, O = unknown>(opts: StepToolOpts<I, O>): StepTool<TMemory, I, O>;
     /**
      * Creates a step that delegates a turn to the Claude Code harness.
      *
@@ -108,27 +108,27 @@ export declare const step: {
      * @returns A `StepSubHarness` of kind `claude-code`, auto-registered in the step registry.
      * @throws `NoeticConfigError` `EMPTY_STEP_ID` / `MISSING_SUB_HARNESS` / `SUB_HARNESS_KIND_MISMATCH`.
      */
-    claudeCode<TMemory = Readonly<Record<string, Record<string, unknown>>>, I = unknown, O = unknown>(opts: StepSubHarnessOpts<TMemory, O>): StepSubHarness<TMemory, I, O>;
+    claudeCode<TMemory = ContextMemory, I = unknown, O = unknown>(opts: StepSubHarnessOpts<TMemory, O>): StepSubHarness<TMemory, I, O>;
     /**
      * Creates a step that delegates a turn to the Codex harness.
      * @public
      * @param opts - See {@link step.claudeCode}; `opts.harness` is a `codex(...)` adapter.
      * @returns A `StepSubHarness` of kind `codex`.
      */
-    codex<TMemory = Readonly<Record<string, Record<string, unknown>>>, I = unknown, O = unknown>(opts: StepSubHarnessOpts<TMemory, O>): StepSubHarness<TMemory, I, O>;
+    codex<TMemory = ContextMemory, I = unknown, O = unknown>(opts: StepSubHarnessOpts<TMemory, O>): StepSubHarness<TMemory, I, O>;
     /**
      * Creates a step that delegates a turn to the opencode harness.
      * @public
      * @param opts - See {@link step.claudeCode}; `opts.harness` is an `opencode(...)` adapter.
      * @returns A `StepSubHarness` of kind `opencode`.
      */
-    opencode<TMemory = Readonly<Record<string, Record<string, unknown>>>, I = unknown, O = unknown>(opts: StepSubHarnessOpts<TMemory, O>): StepSubHarness<TMemory, I, O>;
+    opencode<TMemory = ContextMemory, I = unknown, O = unknown>(opts: StepSubHarnessOpts<TMemory, O>): StepSubHarness<TMemory, I, O>;
     /**
      * Creates a step that delegates a turn to the pi harness.
      * @public
      * @param opts - See {@link step.claudeCode}; `opts.harness` is a `pi(...)` adapter.
      * @returns A `StepSubHarness` of kind `pi`.
      */
-    pi<TMemory = Readonly<Record<string, Record<string, unknown>>>, I = unknown, O = unknown>(opts: StepSubHarnessOpts<TMemory, O>): StepSubHarness<TMemory, I, O>;
+    pi<TMemory = ContextMemory, I = unknown, O = unknown>(opts: StepSubHarnessOpts<TMemory, O>): StepSubHarness<TMemory, I, O>;
 };
 export {};

package/dist/builders/workflow-hydrator.js

@@ -271,39 +271,63 @@ function hydrateForkNode(node, ctx) {
         _optimizable: optimizable,
     });
 }
+/**
+ * Resolves layer names declared on a `provide` / `spawn` node against the
+ * registry on `HydrationContext.layers`. Returns `[]` when no registry was
+ * supplied — the host runs with its harness-default layers in that case.
+ */
+function resolveNamedLayers({ names, nodeKind, nodeId, ctx, }) {
+    if (!ctx.layers) {
+        return [];
+    }
+    return names.map((name) => {
+        const layer = ctx.layers?.get(name);
+        if (!layer) {
+            throw new NoeticConfigError({
+                code: 'UNKNOWN_LAYER_REFERENCE',
+                message: `Memory layer '${name}' referenced in ${nodeKind} node '${nodeId}' is not registered.`,
+                hint: `Available layers: ${[
+                    ...(ctx.layers?.keys() ?? []),
+                ].join(', ') || '(none)'}. Pass named layers via HydrationContext.layers.`,
+            });
+        }
+        return layer;
+    });
+}
 function hydrateSpawnNode(node, ctx) {
     if (node.kind !== 'spawn') {
         return frameworkCast(undefined);
     }
+    // `memory` is left undefined when the node names no layers so the child
+    // inherits the parent's layers (spec 04). An explicit list replaces them.
+    const resolvedLayers = node.layers
+        ? resolveNamedLayers({
+            names: node.layers,
+            nodeKind: 'spawn',
+            nodeId: node.id,
+            ctx,
+        })
+        : undefined;
     return spawn({
         id: node.id,
         child: hydrateNode(node.child, ctx),
         timeout: node.timeout,
+        memory: resolvedLayers,
     });
 }
 function hydrateProvideNode(node, ctx) {
     if (node.kind !== 'provide') {
         return frameworkCast(undefined);
     }
-    const resolvedLayers = ctx.layers
-        ? node.layers.map((name) => {
-            const layer = ctx.layers?.get(name);
-            if (!layer) {
-                throw new NoeticConfigError({
-                    code: 'UNKNOWN_LAYER_REFERENCE',
-                    message: `Memory layer '${name}' referenced in provide node '${node.id}' is not registered.`,
-                    hint: `Available layers: ${[
-                        ...(ctx.layers?.keys() ?? []),
-                    ].join(', ') || '(none)'}. Pass named layers via HydrationContext.layers.`,
-                });
-            }
-            return layer;
-        })
-        : [];
     return provide({
         id: node.id,
         child: hydrateNode(node.child, ctx),
-        memory: resolvedLayers,
+        memory: resolveNamedLayers({
+            names: node.layers,
+            nodeKind: 'provide',
+            nodeId: node.id,
+            ctx,
+        }),
     });
 }
 function hydrateLoopNode(node, ctx) {

package/dist/interpreter/execute-control.d.ts

@@ -2,8 +2,14 @@
  * Control-flow step handlers: branch, fork, loop, every.
  */
 import type { Context, ExecuteStepFn, StepBranch, StepEvery, StepFork, StepLoop } from '@noetic-tools/types';
+import type { ItemSchemaRegistry, LayerStateStore } from './action-deps.js';
 export declare function executeBranch<TMemory, I, O>(step: StepBranch<TMemory, I, O>, input: I, ctx: Context<TMemory>, executeStep: ExecuteStepFn): Promise<O>;
-export declare function executeFork<TMemory, I, O>(step: StepFork<TMemory, I, O>, input: I, ctx: Context<TMemory>, executeStep: ExecuteStepFn): Promise<O>;
+/** Layer-boundary wiring supplied by the interpreter (see `buildSpawnOpts`). */
+export interface ExecuteForkOpts {
+    layerStore?: LayerStateStore;
+    itemSchemas?: ItemSchemaRegistry;
+}
+export declare function executeFork<TMemory, I, O>(step: StepFork<TMemory, I, O>, input: I, ctx: Context<TMemory>, rawExecuteStep: ExecuteStepFn, opts?: ExecuteForkOpts): Promise<O>;
 export declare function executeLoop<TMemory, I, O>(step: StepLoop<TMemory, I, O>, input: I, ctx: Context<TMemory>, executeStep: ExecuteStepFn): Promise<O>;
 /**
  * Executes an `every` step: runs the body step forever, paced by `ms ± jitter`,

package/dist/interpreter/execute-control.js

@@ -4,6 +4,7 @@
 import { createMessage, frameworkCast, isNoeticError, NoeticErrorImpl } from '@noetic-tools/types';
 import { ContextImpl } from '../runtime/context-impl.js';
 import { snapshotCwdState } from '../runtime/cwd-helpers.js';
+import { contextToExecCtx, returnLayers, spawnLayers } from './action-deps.js';
 import { cloneWithGuard } from './clone-guard.js';
 import { getContextChannelStore, isContextImpl, isMutableContext } from './typeguards.js';
 //#region branch
@@ -35,9 +36,83 @@ function createChildContexts(ctx, count, stepId) {
         resourceId,
         channelStore,
         cwdState: snapshotCwdState(ctx),
+        // Layers and the harness tool pool cross the fork boundary: without
+        // them an `llm` step inside a path would run with no memory
+        // projection and no layer tools, and a nested `spawn` would have no
+        // parent layers to inherit. Per-path layer STATE is still isolated —
+        // see `createForkLayerBridge`.
+        layers: ctx.layers,
+        unifiedTools: ctx.unifiedTools,
     }));
 }
-export async function executeFork(step, input, ctx, executeStep) {
+function createForkLayerBridge({ ctx, childContexts, opts, }) {
+    const layers = ctx.layers;
+    const layerStore = opts?.layerStore;
+    if (!layers || layers.length === 0 || !layerStore) {
+        return null;
+    }
+    const parentExecCtx = contextToExecCtx(ctx);
+    const childExecCtxs = childContexts.map((child) => contextToExecCtx(child));
+    let tail = Promise.resolve();
+    function serialize(fn) {
+        const run = tail.then(fn, fn);
+        tail = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    return {
+        async seed(index) {
+            await spawnLayers({
+                layers: layers ?? [],
+                parentCtx: parentExecCtx,
+                childCtx: childExecCtxs[index],
+                store: layerStore,
+                itemSchemas: opts?.itemSchemas,
+            });
+        },
+        settle(index, result) {
+            return serialize(() => returnLayers({
+                layers: layers ?? [],
+                parentCtx: parentExecCtx,
+                childCtx: childExecCtxs[index],
+                childLog: childContexts[index].itemLog,
+                result,
+                store: layerStore,
+            }));
+        },
+        cleanup(index) {
+            layerStore.cleanup(childExecCtxs[index].executionId);
+        },
+    };
+}
+/**
+ * Wraps the interpreter's `executeStep` so every forked path runs inside the
+ * layer child boundary. Contexts that are not one of this fork's children
+ * (nested steps within a path) pass straight through.
+ */
+function withForkLayers(executeStep, childContexts, bridge) {
+    if (!bridge) {
+        return executeStep;
+    }
+    const indexByContext = new Map(childContexts.map((child, i) => [
+        child,
+        i,
+    ]));
+    return async (step, input, childCtx) => {
+        const index = indexByContext.get(frameworkCast(childCtx));
+        if (index === undefined) {
+            return executeStep(step, input, childCtx);
+        }
+        await bridge.seed(index);
+        try {
+            const output = await executeStep(step, input, childCtx);
+            return await bridge.settle(index, output);
+        }
+        finally {
+            bridge.cleanup(index);
+        }
+    };
+}
+export async function executeFork(step, input, ctx, rawExecuteStep, opts) {
     const baseCtx = frameworkCast(ctx);
     const paths = step.paths(input, ctx);
     if (paths.length === 0) {
@@ -56,6 +131,11 @@ export async function executeFork(step, input, ctx, executeStep) {
     }
     const childContexts = createChildContexts(baseCtx, paths.length, step.id);
     const concurrency = step.concurrency ?? paths.length;
+    const executeStep = withForkLayers(rawExecuteStep, childContexts, createForkLayerBridge({
+        ctx: baseCtx,
+        childContexts,
+        opts,
+    }));
     switch (step.mode) {
         case 'all':
             return executeAll(step, paths, input, ctx, childContexts, executeStep, concurrency);

package/dist/interpreter/execute.js

@@ -194,7 +194,12 @@ export async function execute(step, input, ctx) {
                 result = await executeBranch(step, input, ctx, (s, i, c) => execute(s, i, c));
                 break;
             case 'fork':
-                result = await executeFork(step, input, ctx, (s, i, c) => execute(s, i, c));
+                result = await executeFork(step, input, ctx, (s, i, c) => execute(s, i, c), {
+                    // Fork paths are child executions: the layer store lets their
+                    // `onSpawn`/`onReturn` boundary run (see `createForkLayerBridge`).
+                    layerStore: harnessWithLayerStore(baseCtx).layerStateStore,
+                    itemSchemas: baseCtx.itemSchemas,
+                });
                 break;
             case 'spawn':
                 result = await dispatchViaAdapter(step, input, ctx, () => executeSpawn(step, input, ctx, (s, i, c) => execute(s, i, c), buildSpawnOpts(ctx)));

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

@@ -1,33 +1,33 @@
 export declare const GenAI: {
-    readonly SYSTEM: "gen_ai.system";
-    readonly REQUEST_MODEL: "gen_ai.request.model";
-    readonly USAGE_INPUT_TOKENS: "gen_ai.usage.input_tokens";
-    readonly USAGE_OUTPUT_TOKENS: "gen_ai.usage.output_tokens";
-    readonly COST: "gen_ai.cost";
+    readonly SYSTEM: 'gen_ai.system';
+    readonly REQUEST_MODEL: 'gen_ai.request.model';
+    readonly USAGE_INPUT_TOKENS: 'gen_ai.usage.input_tokens';
+    readonly USAGE_OUTPUT_TOKENS: 'gen_ai.usage.output_tokens';
+    readonly COST: 'gen_ai.cost';
 };
 export declare const ToolAttr: {
-    readonly NAME: "tool.name";
-    readonly NEEDS_APPROVAL: "tool.needs_approval";
+    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";
+    readonly WORKFLOW_DOCUMENT: 'noetic.workflow.document';
     /** Workflow document schema version. */
-    readonly WORKFLOW_VERSION: "noetic.workflow.version";
+    readonly WORKFLOW_VERSION: 'noetic.workflow.version';
     /** Count of declared nodes in the workflow tree. */
-    readonly WORKFLOW_NODE_COUNT: "noetic.workflow.node_count";
+    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";
+    readonly WORKFLOW_NODES: 'noetic.workflow.nodes';
     /** JSON array of `{ from, to }` parent→child edges between declared nodes. */
-    readonly WORKFLOW_EDGES: "noetic.workflow.edges";
+    readonly WORKFLOW_EDGES: 'noetic.workflow.edges';
     /** Id of the declared workflow node an `llm.call`/`tool.call` span belongs to. */
-    readonly NODE_ID: "noetic.node.id";
+    readonly NODE_ID: 'noetic.node.id';
     /**
      * Conversation/session this run belongs to (the run's `ctx.threadId`). Stamped
      * on the root `workflow.run` span so every turn of a multi-turn session shares
      * one id, letting a consumer group per-run traces back into their session.
      */
-    readonly SESSION_ID: "noetic.session.id";
+    readonly SESSION_ID: 'noetic.session.id';
     /** Resource the session is scoped to (the run's `ctx.resourceId`), when set. */
-    readonly RESOURCE_ID: "noetic.resource.id";
+    readonly RESOURCE_ID: 'noetic.resource.id';
 };

package/dist/patterns/dynamic-workflow.d.ts

@@ -2,7 +2,7 @@
  * Pattern that lets an LLM generate a workflow as JSON during execution,
  * then hydrates and runs it within the same harness session.
  */
-import type { ContextMemory } from '@noetic-tools/memory';
+import type { ContextMemory, MemoryLayer } from '@noetic-tools/memory';
 import type { AgentHarnessContract, Context, Step, Tool } from '@noetic-tools/types';
 /** @public Options for creating a dynamic workflow step. */
 export interface DynamicWorkflowOpts {
@@ -34,6 +34,12 @@ export interface ParseAndRunWorkflowOpts {
     tools: Tool[];
     input?: string;
     maxDepth?: number;
+    /**
+     * Memory layers the document's `provide` / `spawn` nodes may reference by name.
+     * Without a registry those nodes resolve to NO layers rather than failing, so a
+     * host that runs layer-bearing workflows must pass its layers here.
+     */
+    layers?: ReadonlyMap<string, MemoryLayer>;
 }
 /**
  * Parses raw JSON into a `WorkflowDocument`, hydrates it into a live step

package/dist/patterns/dynamic-workflow.js

@@ -142,6 +142,7 @@ export async function parseAndRunWorkflow(opts) {
     const hydrationCtx = {
         tools: buildToolMap(opts.tools),
         executeStep,
+        layers: opts.layers,
     };
     const hydrated = hydrateWorkflow(parseResult.doc, hydrationCtx);
     const runSpan = beginWorkflowRunSpan(opts.harness, opts.ctx, parseResult.doc);

package/dist/schemas/workflow.d.ts

@@ -44,17 +44,17 @@ export type UntilPredicate = {
 export declare const UntilPredicateSchema: z.ZodType<UntilPredicate>;
 /** @public ESM literal enum for merge strategies. */
 export declare const MergeStrategy: {
-    readonly Last: "last";
-    readonly First: "first";
-    readonly Concat: "concat";
+    readonly Last: 'last';
+    readonly First: 'first';
+    readonly Concat: 'concat';
 };
 /** @public Named merge strategy for fork nodes. */
 export type MergeStrategy = (typeof MergeStrategy)[keyof typeof MergeStrategy];
 /** @public Zod schema for the named merge strategy used by `fork` nodes. */
 export declare const MergeStrategySchema: z.ZodEnum<{
     concat: "concat";
-    last: "last";
     first: "first";
+    last: "last";
 }>;
 declare const ModelParamsSchema: z.ZodObject<{
     temperature: z.ZodOptional<z.ZodNumber>;
@@ -84,9 +84,9 @@ declare const LlmToolEntrySchema: z.ZodObject<{
 declare const RetryPolicySchema: z.ZodObject<{
     maxAttempts: z.ZodNumber;
     backoff: z.ZodEnum<{
+        exponential: "exponential";
         fixed: "fixed";
         linear: "linear";
-        exponential: "exponential";
     }>;
     initialDelay: z.ZodNumber;
     maxDelay: z.ZodOptional<z.ZodNumber>;
@@ -94,10 +94,10 @@ declare const RetryPolicySchema: z.ZodObject<{
 declare const HarnessSettingsSchema: z.ZodObject<{
     model: z.ZodOptional<z.ZodString>;
     permissionMode: z.ZodOptional<z.ZodEnum<{
-        default: "default";
-        plan: "plan";
         acceptEdits: "acceptEdits";
         bypassPermissions: "bypassPermissions";
+        default: "default";
+        plan: "plan";
     }>>;
     maxTurns: z.ZodOptional<z.ZodNumber>;
     allowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -106,9 +106,9 @@ declare const HarnessSettingsSchema: z.ZodObject<{
 declare const HarnessSessionPolicySchema: z.ZodObject<{
     reuse: z.ZodOptional<z.ZodString>;
     onComplete: z.ZodOptional<z.ZodEnum<{
-        stop: "stop";
-        detach: "detach";
         destroy: "destroy";
+        detach: "detach";
+        stop: "stop";
     }>>;
 }, z.core.$strip>;
 interface WorkflowNodeBase {
@@ -200,6 +200,13 @@ export interface SpawnWorkflowNode extends WorkflowNodeBase {
     kind: 'spawn';
     child: WorkflowNode;
     timeout?: number;
+    /**
+     * Memory layers the child runs with, by registered name (resolved from
+     * `HydrationContext.layers`, like `provide`). Omit to inherit the parent's
+     * layers — the default spawn behaviour. Naming layers here REPLACES the
+     * inherited set for the child, so list every layer the child needs.
+     */
+    layers?: string[];
 }
 export interface ProvideWorkflowNode extends WorkflowNodeBase {
     kind: 'provide';

package/dist/schemas/workflow.js

@@ -210,6 +210,7 @@ const SpawnNodeSchema = z.object({
     ...SHARED_FIELDS,
     child: WorkflowNodeRef,
     timeout: z.number().positive().optional(),
+    layers: z.array(z.string().min(1)).min(1).optional(),
 });
 const ProvideNodeSchema = z.object({
     kind: z.literal('provide'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/core",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "type": "module",
   "description": "Step primitives, interpreter, runtime, and memory layer contract for Noetic agents.",
   "license": "Apache-2.0",
@@ -66,8 +66,8 @@
     }
   },
   "dependencies": {
-    "@noetic-tools/memory": "^1.0.1",
-    "@noetic-tools/types": "^1.3.0",
+    "@noetic-tools/memory": "^1.1.0",
+    "@noetic-tools/types": "^1.4.0",
     "@openrouter/agent": "^0.6.0",
     "zod": "^4.0.0"
   },

package/schema/noetic-workflow.schema.json

@@ -316,6 +316,14 @@
             "timeout": {
               "type": "number",
               "exclusiveMinimum": 0
+            },
+            "layers": {
+              "minItems": 1,
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
             }
           },
           "required": [