@noetic-tools/core 0.0.1 → 0.1.1

package/dist/memory/layers/plan.js

@@ -1,9 +1,9 @@
 import { z } from 'zod';
-import { layerData, layerFn } from '../../builders/layer-provides-builders';
-import { createMessage, estimateTokens } from '../../interpreter/message-helpers';
-import { FlowSchema, flowDepth } from '../../patterns/flow';
-import { Slot } from '../../types/memory';
-import { SteeringAction } from '../../types/steering';
+import { Slot } from '../../types/memory.js';
+import { SteeringAction } from '../../types/steering.js';
+import { createMessage, estimateTokens } from '../../util/message-helpers.js';
+import { FlowSchema, flowDepth } from '../flow-schema.js';
+import { layerData, layerFn } from '../layer-provides.js';
 //#region Constants
 const MAX_PRD_LENGTH = 5e4;
 const MAX_TREE_DEPTH = 5;
@@ -14,7 +14,12 @@ const ALLOWED_TOOLS_IN_PLAN_MODE = new Set([
     'Grep',
     'Find',
     'Ls',
+    'AskUserQuestion',
     'activateSkill',
+    'agent',
+    'checkAgent',
+    'sendMessage',
+    'requestPlanApproval',
     'plan/enterPlanMode',
     'plan/updatePrd',
     'plan/setPlanTree',
@@ -63,15 +68,15 @@ function trimExecutionLog(log) {
 function recallPlanning(state, additionalInstructions) {
     const sections = [
         '<plan_mode>',
-        'You are in PLAN MODE. You may only use read-only tools (Read, Grep, Find, Ls) to explore the codebase.',
+        'You are in PLAN MODE. You may only use read-only tools (Read, Grep, Find, Ls), AskUserQuestion, skill activation, sub-agent coordination tools, and requestPlanApproval to explore the codebase and request execution approval.',
         'Your goal is to produce a PRD document and (optionally) a structured execution plan.',
         '',
         '## Workflow (5 phases)',
         '',
-        '1. **Initial Understanding** — Read code and gather context. To parallelise exploration, fork over `{ kind: "subagent", preset: "explore", prompt: "..." }` nodes; up to 3 in parallel. Each Explore subagent returns a focused report.',
-        '2. **Design** — Synthesise findings. Optionally invoke `{ kind: "subagent", preset: "plan", prompt: "..." }` (1–3 in parallel) to draft alternative implementation approaches and surface trade-offs.',
+        '1. **Initial Understanding** — Read code and gather context. To parallelise exploration, use the `agent` tool to spawn bounded read-only sub-agents; up to 3 in parallel. Each sub-agent returns a focused report.',
+        '2. **Design** — Synthesise findings. Optionally spawn planning sub-agents (1–3 in parallel) to draft alternative implementation approaches and surface trade-offs.',
         '3. **Review** — Read the critical files identified by your subagents directly so you understand them first-hand. If anything is ambiguous, ask the user a focused question.',
-        '4. **Final Plan** — Write the PRD via `plan/updatePrd`. Lead with a **Context** section (why this change), then your single recommended approach, the paths of files to modify, existing functions/utilities to reuse, and a **Verification** section. If the task warrants custom step orchestration, also call `plan/setPlanTree` with a JSON noetic flow built from the existing step primitives (`step.llm`, `step.branch`, `step.fork`, `step.spawn`, `step.loop`) — tool refs by name string. Otherwise omit the tree.',
+        '4. **Final Plan** — Write the PRD via `plan/updatePrd`. Lead with a **Context** section (why this change), then your single recommended approach, the paths of files to modify, existing functions/utilities to reuse, and a **Verification** section. Then call `plan/setPlanTree` with a JSON noetic flow built from the existing step primitives (`step.llm`, `step.branch`, `step.fork`, `step.spawn`, `step.loop`) — tool refs by name string.',
         '5. **Exit** — Call `plan/exitPlanMode` with `{ action: "execute" }` to request approval. The user must accept before execution begins; if they reject, you stay in Plan Mode and may revise.',
         '',
         '## Available actions',
@@ -81,7 +86,7 @@ function recallPlanning(state, additionalInstructions) {
         '- `plan/exitPlanMode` `{ action: "cancel" }` — discard plan and return to idle',
         '',
         '## Constraints',
-        '- DO NOT create, modify, or delete files (other than via `plan/updatePrd`).',
+        '- DO NOT create, modify, or delete files (other than via `plan/updatePrd` and `plan/setPlanTree`).',
         '- DO NOT run mutating shell commands. Read-only exploration only.',
         '- End each turn either by asking the user a focused clarifying question or by calling `plan/exitPlanMode`.',
     ];

package/dist/memory/layers/static-content.d.ts

@@ -1,4 +1,4 @@
-import type { MemoryScope } from '../../types/memory';
+import type { MemoryScope } from '../../types/memory.js';
 interface StaticContentOpts {
     id?: string;
     slot?: number;
@@ -21,7 +21,7 @@ export declare function staticContent(opts: StaticContentOpts): {
         init(): Promise<{
             state: string;
         }>;
-        recall({ state }: import("../..").RecallParams<string>): Promise<string | null>;
+        recall({ state }: import("../../index.js").RecallParams<string>): Promise<string | null>;
     };
 };
 export {};

package/dist/memory/layers/static-content.js

@@ -1,4 +1,4 @@
-import { Slot } from '../../types/memory';
+import { Slot } from '../../types/memory.js';
 /**
  * Creates a read-only memory layer that loads static content once at init and injects it into recall.
  *

package/dist/memory/layers/steering.d.ts

@@ -1,5 +1,5 @@
-import type { MemoryScope } from '../../types/memory';
-import type { AfterModelCallParams, BeforeToolCallParams, LedgerEntry, SteeringConfig, SteeringDecision, SteeringState } from '../../types/steering';
+import type { MemoryScope } from '../../types/memory.js';
+import type { AfterModelCallParams, BeforeToolCallParams, LedgerEntry, SteeringConfig, SteeringDecision, SteeringState } from '../../types/steering.js';
 /**
  * Creates a steering memory layer that evaluates rules before tool calls and after model calls.
  *
@@ -21,11 +21,11 @@ export declare function steering(config: SteeringConfig): {
         afterModelCall: number;
     };
     hooks: {
-        init({ storage }: import("../..").InitParams): Promise<{
+        init({ storage }: import("../../index.js").InitParams): Promise<{
             state: SteeringState;
         }>;
-        recall({ state }: import("../..").RecallParams<SteeringState>): Promise<{
-            items: import("../..").InputMessageItem[];
+        recall({ state }: import("../../index.js").RecallParams<SteeringState>): Promise<{
+            items: import("../../index.js").InputMessageItem[];
             tokenCount: number;
             state: SteeringState;
         } | null>;
@@ -38,13 +38,13 @@ export declare function steering(config: SteeringConfig): {
             decision: SteeringDecision;
             state: SteeringState;
         }>;
-        onSpawn({ parentState }: import("../..").SpawnParams<SteeringState>): Promise<{
+        onSpawn({ parentState }: import("../../index.js").SpawnParams<SteeringState>): Promise<{
             childState: {
                 ledger: LedgerEntry[];
                 pendingAsync: never[];
             };
         }>;
-        onComplete({ state, outcome }: import("../..").CompleteParams<SteeringState>): Promise<{
+        onComplete({ state, outcome }: import("../../index.js").CompleteParams<SteeringState>): Promise<{
             state: SteeringState;
         }>;
     };

package/dist/memory/layers/steering.js

@@ -1,8 +1,8 @@
-import { NoeticConfigError } from '../../errors/noetic-config-error';
-import { createMessage, estimateTokens, extractAssistantText, } from '../../interpreter/message-helpers';
-import { Slot } from '../../types/memory';
-import { LedgerEntryKind, SteeringAction } from '../../types/steering';
-import { mostRestrictive } from '../layer-lifecycle';
+import { NoeticConfigError } from '../../errors/noetic-config-error.js';
+import { Slot } from '../../types/memory.js';
+import { LedgerEntryKind, SteeringAction } from '../../types/steering.js';
+import { createMessage, estimateTokens, extractAssistantText } from '../../util/message-helpers.js';
+import { mostRestrictive } from '../layer-lifecycle.js';
 //#region Constants
 const DEFAULT_MAX_LEDGER_ENTRIES = 100;
 //#endregion

package/dist/memory/layers/tool-memory-layer.d.ts

@@ -1,5 +1,5 @@
-import type { Tool } from '../../types/common';
-import type { MemoryLayer } from '../../types/memory';
+import type { MemoryLayer } from '../../types/memory.js';
+import type { Tool } from '../../types/tool.js';
 interface ToolMemoryLayerOpts {
     slot?: number;
 }

package/dist/memory/layers/tool-memory-layer.js

@@ -1,4 +1,4 @@
-import { Slot } from '../../types/memory';
+import { Slot } from '../../types/memory.js';
 const EXECUTION_SCOPE = 'execution';
 /**
  * Generates one MemoryLayer per unique memory id among the provided tools.

package/dist/memory/layers/working-memory.d.ts

@@ -23,21 +23,21 @@ export declare function workingMemory(config?: WorkingMemoryConfig): {
         max: number;
     };
     provides: {
-        snapshot: import("../..").LayerDataDecl<WorkingMemoryState, WorkingMemoryState>;
-        update: import("../..").LayerFunctionDecl<Record<string, unknown>, void, WorkingMemoryState>;
+        snapshot: import("../../index.js").LayerDataDecl<WorkingMemoryState, WorkingMemoryState>;
+        update: import("../../index.js").LayerFunctionDecl<Record<string, unknown>, void, WorkingMemoryState>;
     };
     hooks: {
-        init({ storage }: import("../..").InitParams): Promise<{
+        init({ storage }: import("../../index.js").InitParams): Promise<{
             state: WorkingMemoryState;
         }>;
-        recall({ state }: import("../..").RecallParams<WorkingMemoryState>): Promise<{
-            items: import("../..").InputMessageItem[];
+        recall({ state }: import("../../index.js").RecallParams<WorkingMemoryState>): Promise<{
+            items: import("../../index.js").InputMessageItem[];
             tokenCount: number;
         } | null>;
-        store({ newItems, state }: import("../..").StoreParams<WorkingMemoryState>): Promise<{
+        store({ newItems, state }: import("../../index.js").StoreParams<WorkingMemoryState>): Promise<{
             state: WorkingMemoryState;
         } | undefined>;
-        onSpawn({ parentState }: import("../..").SpawnParams<WorkingMemoryState>): Promise<{
+        onSpawn({ parentState }: import("../../index.js").SpawnParams<WorkingMemoryState>): Promise<{
             childState: WorkingMemoryState;
         } | null>;
     };

package/dist/memory/layers/working-memory.js

@@ -1,8 +1,8 @@
 import { z } from 'zod';
-import { layerData, layerFn } from '../../builders/layer-provides-builders';
-import { createMessage, estimateTokens } from '../../interpreter/message-helpers';
-import { Slot } from '../../types/memory';
-import { findFunctionCall } from '../function-call-utils';
+import { Slot } from '../../types/memory.js';
+import { createMessage, estimateTokens } from '../../util/message-helpers.js';
+import { findFunctionCall } from '../function-call-utils.js';
+import { layerData, layerFn } from '../layer-provides.js';
 function safeMerge(state, args) {
     const { __proto__: _p, constructor: _c, ...safeArgs } = args;
     if (typeof state === 'object' && state !== null) {

package/dist/memory/projector.d.ts

@@ -1,5 +1,5 @@
-import type { Item } from '../types/items';
-import type { ProjectionPolicy } from '../types/memory';
+import type { Item } from '../types/items.js';
+import type { ProjectionPolicy } from '../types/memory.js';
 interface AssembleViewParams {
     systemPromptItems: Item[];
     layerOutputItems: Item[];

package/dist/memory/scope.d.ts

@@ -1,3 +1,3 @@
-import type { ExecutionContext, MemoryScope, ScopedStorage, StorageAdapter } from '../types/memory';
+import type { ExecutionContext, MemoryScope, ScopedStorage, StorageAdapter } from '../types/memory.js';
 export declare function resolveScopeKey(scope: MemoryScope, ctx: ExecutionContext): string;
 export declare function createScopedStorage(storage: StorageAdapter, layerId: string, scopeKey: string): ScopedStorage;

package/dist/memory/strip-unresolved.d.ts

@@ -8,6 +8,6 @@
  * session-resume path to drop dangling pairs left by a crash, and by the
  * `historyWindow` memory layer to clean orphans at the slice boundary.
  */
-import type { Item } from '../types/items';
+import type { Item } from '../types/items.js';
 /** @public */
 export declare function stripUnresolvedToolCalls(items: ReadonlyArray<Item>): Item[];

package/dist/observability/span-impl.d.ts

@@ -1,4 +1,4 @@
-import type { Span } from '../types/observability';
+import type { Span } from '../types/observability.js';
 export declare class SpanImpl implements Span {
     readonly traceId: string;
     readonly spanId: string;

package/dist/observability/trace-exporter.d.ts

@@ -1,5 +1,5 @@
-import type { Span, TraceExporter } from '../types/observability';
-import { SpanImpl } from './span-impl';
+import type { Span, TraceExporter } from '../types/observability.js';
+import { SpanImpl } from './span-impl.js';
 /** @public No-op trace exporter that silently discards all spans. */
 export declare class NoopExporter implements TraceExporter {
     export(_spans: Span[]): Promise<void>;

package/dist/observability/trace-exporter.js

@@ -1,4 +1,4 @@
-import { SpanImpl } from './span-impl';
+import { SpanImpl } from './span-impl.js';
 /** @public No-op trace exporter that silently discards all spans. */
 export class NoopExporter {
     async export(_spans) {

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

@@ -0,0 +1,55 @@
+/**
+ * Pattern that lets an LLM generate a workflow as JSON during execution,
+ * then hydrates and runs it within the same harness session.
+ */
+import type { Context } from '../types/context.js';
+import type { ContextMemory } from '../types/memory.js';
+import type { AgentHarnessContract } from '../types/runtime.js';
+import type { Step } from '../types/step.js';
+import type { Tool } from '../types/tool.js';
+/** @public Options for creating a dynamic workflow step. */
+export interface DynamicWorkflowOpts {
+    model?: string;
+    instructions?: string;
+    tools: Tool[];
+    maxDepth?: number;
+    maxRevisions?: number;
+}
+/**
+ * Creates a step that uses an LLM to generate a workflow as JSON, then
+ * hydrates and executes it. The entire plan-and-execute cycle happens
+ * within a single harness run.
+ *
+ * @public
+ * @param opts.model - Model for the planner LLM. Default: `openai/gpt-4o`.
+ * @param opts.instructions - Additional instructions prepended to the planner prompt.
+ * @param opts.tools - Tools the generated workflow may reference by name.
+ * @param opts.maxDepth - Maximum workflow tree depth. Default: 5.
+ * @param opts.maxRevisions - Retries with error feedback on validation failure. Default: 3.
+ * @returns A `Step` that dynamically plans and executes.
+ */
+export declare function dynamicWorkflow(opts: DynamicWorkflowOpts): Step<ContextMemory, string, string>;
+/** @public Options for `parseAndRunWorkflow`. */
+export interface ParseAndRunWorkflowOpts {
+    json: unknown;
+    harness: AgentHarnessContract;
+    ctx: Context;
+    tools: Tool[];
+    input?: string;
+    maxDepth?: number;
+}
+/**
+ * Parses raw JSON into a `WorkflowDocument`, hydrates it into a live step
+ * tree, and executes it via the harness.
+ *
+ * @public
+ * @param opts.json - Raw JSON (string or parsed object) representing a workflow.
+ * @param opts.harness - The agent harness to execute the workflow with.
+ * @param opts.ctx - Execution context.
+ * @param opts.tools - Available tools the workflow may reference.
+ * @param opts.maxDepth - Maximum workflow tree depth. Default: 5.
+ * @returns The string output of the executed workflow.
+ * @throws `NoeticConfigError` with code `WORKFLOW_VALIDATION_FAILED` if JSON is invalid.
+ * @throws `NoeticConfigError` with code `UNKNOWN_TOOL_REFERENCE` if a tool reference cannot be resolved.
+ */
+export declare function parseAndRunWorkflow(opts: ParseAndRunWorkflowOpts): Promise<string>;

package/dist/patterns/dynamic-workflow.js

@@ -0,0 +1,194 @@
+/**
+ * Pattern that lets an LLM generate a workflow as JSON during execution,
+ * then hydrates and runs it within the same harness session.
+ */
+import { step } from '../builders/step-builders.js';
+import { hydrateWorkflow } from '../builders/workflow-hydrator.js';
+import { NoeticConfigError } from '../errors/noetic-config-error.js';
+import { WorkflowDocumentSchema, workflowDepth } from '../schemas/workflow.js';
+import { frameworkCast } from '../util/framework-cast.js';
+//#endregion
+//#region Constants
+const DEFAULT_MAX_DEPTH = 5;
+const DEFAULT_MAX_REVISIONS = 3;
+const DEFAULT_MODEL = 'openai/gpt-4o';
+const PLANNER_INSTRUCTIONS = `You are a workflow planner. Given a task, generate a JSON workflow document that describes how to accomplish it.
+
+The workflow document must be valid JSON with this structure:
+{
+  "version": 1,
+  "root": <WorkflowNode>
+}
+
+A WorkflowNode is one of:
+- { "kind": "llm", "id": "<unique>", "instructions": "<prompt>", "model": "<optional>", "tools": ["<tool-name>", ...] }
+- { "kind": "tool", "id": "<unique>", "toolName": "<name>", "args": { ... } }
+- { "kind": "sequence", "id": "<unique>", "steps": [<WorkflowNode>, ...] }
+- { "kind": "fork", "id": "<unique>", "mode": "all"|"race"|"settle", "paths": [<WorkflowNode>, ...], "merge": "last"|"first"|"concat" }
+- { "kind": "loop", "id": "<unique>", "body": <WorkflowNode>, "until": { "kind": "maxSteps", "n": <number> } }
+- { "kind": "branch", "id": "<unique>", "routes": [{ "match": "<substring>", "target": <WorkflowNode> }], "default": <WorkflowNode> }
+- { "kind": "spawn", "id": "<unique>", "child": <WorkflowNode> }
+
+Until predicates: maxSteps, maxCost, maxDuration, noToolCalls, outputContains, outputEquals, converged, any, all.
+
+Respond with ONLY the JSON document, no markdown fences or explanation.`;
+//#endregion
+//#region Public API
+/**
+ * Creates a step that uses an LLM to generate a workflow as JSON, then
+ * hydrates and executes it. The entire plan-and-execute cycle happens
+ * within a single harness run.
+ *
+ * @public
+ * @param opts.model - Model for the planner LLM. Default: `openai/gpt-4o`.
+ * @param opts.instructions - Additional instructions prepended to the planner prompt.
+ * @param opts.tools - Tools the generated workflow may reference by name.
+ * @param opts.maxDepth - Maximum workflow tree depth. Default: 5.
+ * @param opts.maxRevisions - Retries with error feedback on validation failure. Default: 3.
+ * @returns A `Step` that dynamically plans and executes.
+ */
+export function dynamicWorkflow(opts) {
+    const model = opts.model ?? DEFAULT_MODEL;
+    const maxDepth = opts.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const maxRevisions = opts.maxRevisions ?? DEFAULT_MAX_REVISIONS;
+    const toolMap = buildToolMap(opts.tools);
+    return step.run({
+        id: 'dynamic-workflow',
+        execute: async (input, ctx) => {
+            const harness = ctx.harness;
+            if (!harness) {
+                throw new NoeticConfigError({
+                    code: 'MISSING_HARNESS_CONTEXT',
+                    message: 'dynamicWorkflow requires a harness on the execution context.',
+                    hint: 'Execute this step via AgentHarness.run() or ensure ctx.harness is set.',
+                });
+            }
+            const toolList = opts.tools.map((t) => `- ${t.name}: ${t.description}`).join('\n');
+            const basePrompt = [
+                opts.instructions,
+                PLANNER_INSTRUCTIONS,
+                `\nAvailable tools:\n${toolList}`,
+                `\nTask: ${input}`,
+            ]
+                .filter(Boolean)
+                .join('\n\n');
+            let lastError;
+            for (let revision = 0; revision < maxRevisions; revision++) {
+                const prompt = lastError
+                    ? `${basePrompt}\n\nPrevious attempt failed with error: ${lastError}\nPlease fix the workflow and try again.`
+                    : basePrompt;
+                const plannerStep = step.llm({
+                    id: `dynamic-workflow-planner-${revision}`,
+                    model,
+                    instructions: prompt,
+                });
+                const executeStep = frameworkCast(harness.run.bind(harness));
+                const rawOutput = await executeStep(plannerStep, input, ctx);
+                const text = coerceToString(rawOutput);
+                const parseResult = tryParseWorkflow(text, maxDepth);
+                if (!parseResult.ok) {
+                    lastError = parseResult.error;
+                    if (revision === maxRevisions - 1) {
+                        throw new NoeticConfigError({
+                            code: 'WORKFLOW_VALIDATION_FAILED',
+                            message: `Failed to generate valid workflow after ${maxRevisions} attempts: ${lastError}`,
+                            hint: 'The planner model may need clearer instructions or a more capable model.',
+                        });
+                    }
+                    continue;
+                }
+                const hydrationCtx = {
+                    tools: toolMap,
+                    executeStep,
+                };
+                const hydrated = hydrateWorkflow(parseResult.doc, hydrationCtx);
+                return frameworkCast(await executeStep(hydrated, input, ctx));
+            }
+            throw new NoeticConfigError({
+                code: 'WORKFLOW_VALIDATION_FAILED',
+                message: `Failed to generate valid workflow after ${maxRevisions} attempts.`,
+                hint: 'The planner model may need clearer instructions or a more capable model.',
+            });
+        },
+    });
+}
+/**
+ * Parses raw JSON into a `WorkflowDocument`, hydrates it into a live step
+ * tree, and executes it via the harness.
+ *
+ * @public
+ * @param opts.json - Raw JSON (string or parsed object) representing a workflow.
+ * @param opts.harness - The agent harness to execute the workflow with.
+ * @param opts.ctx - Execution context.
+ * @param opts.tools - Available tools the workflow may reference.
+ * @param opts.maxDepth - Maximum workflow tree depth. Default: 5.
+ * @returns The string output of the executed workflow.
+ * @throws `NoeticConfigError` with code `WORKFLOW_VALIDATION_FAILED` if JSON is invalid.
+ * @throws `NoeticConfigError` with code `UNKNOWN_TOOL_REFERENCE` if a tool reference cannot be resolved.
+ */
+export async function parseAndRunWorkflow(opts) {
+    const parseResult = tryParseWorkflow(opts.json, opts.maxDepth ?? DEFAULT_MAX_DEPTH);
+    if (!parseResult.ok) {
+        throw new NoeticConfigError({
+            code: 'WORKFLOW_VALIDATION_FAILED',
+            message: `Invalid workflow document: ${parseResult.error}`,
+            hint: 'Ensure the JSON matches the WorkflowDocumentSchema.',
+        });
+    }
+    const executeStep = frameworkCast(opts.harness.run.bind(opts.harness));
+    const hydrationCtx = {
+        tools: buildToolMap(opts.tools),
+        executeStep,
+    };
+    const hydrated = hydrateWorkflow(parseResult.doc, hydrationCtx);
+    const result = await executeStep(hydrated, opts.input ?? '', opts.ctx);
+    return coerceToString(result);
+}
+function buildToolMap(tools) {
+    return new Map(tools.map((t) => [
+        t.name,
+        t,
+    ]));
+}
+function coerceToString(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    return String(value ?? '');
+}
+function tryParseWorkflow(raw, maxDepth) {
+    const parsed = typeof raw === 'string' ? safeParse(raw) : raw;
+    if (parsed === null) {
+        return {
+            ok: false,
+            error: 'Input is not valid JSON.',
+        };
+    }
+    const result = WorkflowDocumentSchema.safeParse(parsed);
+    if (!result.success) {
+        return {
+            ok: false,
+            error: result.error.message,
+        };
+    }
+    const depth = workflowDepth(result.data.root);
+    if (depth > maxDepth) {
+        return {
+            ok: false,
+            error: `Workflow tree depth ${depth} exceeds maximum ${maxDepth}.`,
+        };
+    }
+    return {
+        ok: true,
+        doc: result.data,
+    };
+}
+function safeParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+//#endregion

package/dist/patterns/flow.d.ts

@@ -1,52 +1,2 @@
-/**
- * Zod schema for plan-mode flow JSON.
- *
- * A "flow" is a JSON-serialisable subset of noetic's `Step` shape that the model
- * may emit during plan mode. The runtime expands each node into a concrete `Step`
- * via the existing builders (`step.llm`, `fork`, `spawn`) at execute time.
- *
- * Tool references inside `llm` nodes are name strings — they get resolved against
- * the harness's live tool registry when the flow runs.
- */
-import { z } from 'zod';
-interface NodeBase {
-    id: string;
-    subPlanRef?: string;
-}
-export interface LlmFlowNode extends NodeBase {
-    kind: 'llm';
-    model?: string;
-    instructions: string;
-    tools?: string[];
-}
-export interface SubagentFlowNode extends NodeBase {
-    kind: 'subagent';
-    preset: string;
-    prompt: string;
-}
-export interface ForkFlowNode extends NodeBase {
-    kind: 'fork';
-    mode: 'all' | 'race' | 'settle';
-    paths: FlowNode[];
-}
-export interface SpawnFlowNode extends NodeBase {
-    kind: 'spawn';
-    child: FlowNode;
-}
-export interface SequenceFlowNode extends NodeBase {
-    kind: 'sequence';
-    steps: FlowNode[];
-}
-export type FlowNode = LlmFlowNode | SubagentFlowNode | ForkFlowNode | SpawnFlowNode | SequenceFlowNode;
-/** Top-level flow document — a single root node. */
-export declare const FlowSchema: z.ZodType<FlowNode, unknown, z.core.$ZodTypeInternals<FlowNode, unknown>>;
-/** Validates a candidate flow document. Throws `ZodError` on invalid input. */
-export declare function validateFlow(input: unknown): FlowNode;
-/** Walks a flow tree depth-first, yielding each node. */
-export declare function walkFlow(root: FlowNode): Iterable<FlowNode>;
-/**
- * Returns the maximum depth of a flow tree. A leaf (llm/subagent) is depth 0.
- * Structural nodes (sequence/fork/spawn) contribute +1 over their deepest child.
- */
-export declare function flowDepth(node: FlowNode): number;
-export {};
+export type { FlowNode, ForkFlowNode, LlmFlowNode, SequenceFlowNode, SpawnFlowNode, SubagentFlowNode, } from '../memory/flow-schema.js';
+export { FlowSchema, flowDepth, validateFlow, walkFlow } from '../memory/flow-schema.js';

package/dist/patterns/flow.js

@@ -1,103 +1 @@
-/**
- * Zod schema for plan-mode flow JSON.
- *
- * A "flow" is a JSON-serialisable subset of noetic's `Step` shape that the model
- * may emit during plan mode. The runtime expands each node into a concrete `Step`
- * via the existing builders (`step.llm`, `fork`, `spawn`) at execute time.
- *
- * Tool references inside `llm` nodes are name strings — they get resolved against
- * the harness's live tool registry when the flow runs.
- */
-import { z } from 'zod';
-//#endregion
-//#region Schema
-const FlowNodeRef = z.lazy(() => FlowNodeSchema);
-const SHARED_FIELDS = {
-    id: z.string().min(1),
-    subPlanRef: z.string().optional(),
-};
-const LlmNodeSchema = z.object({
-    kind: z.literal('llm'),
-    ...SHARED_FIELDS,
-    model: z.string().optional(),
-    instructions: z.string(),
-    tools: z.array(z.string()).optional(),
-});
-const SubagentNodeSchema = z.object({
-    kind: z.literal('subagent'),
-    ...SHARED_FIELDS,
-    preset: z.string().min(1),
-    prompt: z.string(),
-});
-const ForkNodeSchema = z.object({
-    kind: z.literal('fork'),
-    ...SHARED_FIELDS,
-    mode: z.enum([
-        'all',
-        'race',
-        'settle',
-    ]),
-    paths: z.array(FlowNodeRef).min(1),
-});
-const SpawnNodeSchema = z.object({
-    kind: z.literal('spawn'),
-    ...SHARED_FIELDS,
-    child: FlowNodeRef,
-});
-const SequenceNodeSchema = z.object({
-    kind: z.literal('sequence'),
-    ...SHARED_FIELDS,
-    steps: z.array(FlowNodeRef).min(1),
-});
-const FlowNodeSchema = z.discriminatedUnion('kind', [
-    LlmNodeSchema,
-    SubagentNodeSchema,
-    ForkNodeSchema,
-    SpawnNodeSchema,
-    SequenceNodeSchema,
-]);
-/** Top-level flow document — a single root node. */
-export const FlowSchema = FlowNodeSchema;
-//#endregion
-//#region Public API
-/** Validates a candidate flow document. Throws `ZodError` on invalid input. */
-export function validateFlow(input) {
-    return FlowSchema.parse(input);
-}
-/** Walks a flow tree depth-first, yielding each node. */
-export function* walkFlow(root) {
-    yield root;
-    if (root.kind === 'fork') {
-        for (const path of root.paths) {
-            yield* walkFlow(path);
-        }
-        return;
-    }
-    if (root.kind === 'sequence') {
-        for (const step of root.steps) {
-            yield* walkFlow(step);
-        }
-        return;
-    }
-    if (root.kind === 'spawn') {
-        yield* walkFlow(root.child);
-        return;
-    }
-}
-/**
- * Returns the maximum depth of a flow tree. A leaf (llm/subagent) is depth 0.
- * Structural nodes (sequence/fork/spawn) contribute +1 over their deepest child.
- */
-export function flowDepth(node) {
-    if (node.kind === 'sequence') {
-        return 1 + Math.max(0, ...node.steps.map(flowDepth));
-    }
-    if (node.kind === 'fork') {
-        return 1 + Math.max(0, ...node.paths.map(flowDepth));
-    }
-    if (node.kind === 'spawn') {
-        return 1 + flowDepth(node.child);
-    }
-    return 0;
-}
-//#endregion
+export { FlowSchema, flowDepth, validateFlow, walkFlow } from '../memory/flow-schema.js';