@noetic-tools/core 0.0.1

package/dist/observability/span-impl.js

@@ -0,0 +1,33 @@
+export class SpanImpl {
+    traceId;
+    spanId;
+    parentSpanId;
+    name;
+    startTime;
+    endTime;
+    attributes = new Map();
+    events = [];
+    constructor(name, parent, traceId) {
+        this.name = name;
+        this.traceId = traceId ?? parent?.traceId ?? crypto.randomUUID();
+        this.spanId = crypto.randomUUID();
+        this.parentSpanId = parent?.spanId ?? null;
+        this.startTime = Date.now();
+    }
+    setAttribute(key, value) {
+        this.attributes.set(key, value);
+    }
+    addEvent(name, attributes) {
+        this.events.push({
+            name,
+            timestamp: Date.now(),
+            attributes,
+        });
+    }
+    end() {
+        this.endTime = Date.now();
+    }
+    get duration() {
+        return (this.endTime ?? Date.now()) - this.startTime;
+    }
+}

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

@@ -0,0 +1,15 @@
+import type { Span, TraceExporter } from '../types/observability';
+import { SpanImpl } from './span-impl';
+/** @public No-op trace exporter that silently discards all spans. */
+export declare class NoopExporter implements TraceExporter {
+    export(_spans: Span[]): Promise<void>;
+}
+/** @public Collects SpanImpl instances for test assertions and diagnostics. Non-SpanImpl spans are filtered out. */
+export declare class InMemoryExporter implements TraceExporter {
+    readonly spans: SpanImpl[];
+    export(spans: Span[]): Promise<void>;
+    clear(): void;
+    getSpansByName(name: string): SpanImpl[];
+    getChildSpans(parentSpanId: string): SpanImpl[];
+    getTraceTree(traceId: string): SpanImpl[];
+}

package/dist/observability/trace-exporter.js

@@ -0,0 +1,26 @@
+import { SpanImpl } from './span-impl';
+/** @public No-op trace exporter that silently discards all spans. */
+export class NoopExporter {
+    async export(_spans) {
+        // No-op
+    }
+}
+/** @public Collects SpanImpl instances for test assertions and diagnostics. Non-SpanImpl spans are filtered out. */
+export class InMemoryExporter {
+    spans = [];
+    async export(spans) {
+        this.spans.push(...spans.filter((s) => s instanceof SpanImpl));
+    }
+    clear() {
+        this.spans.length = 0;
+    }
+    getSpansByName(name) {
+        return this.spans.filter((s) => s.name === name);
+    }
+    getChildSpans(parentSpanId) {
+        return this.spans.filter((s) => s.parentSpanId === parentSpanId);
+    }
+    getTraceTree(traceId) {
+        return this.spans.filter((s) => s.traceId === traceId);
+    }
+}

package/dist/patterns/flow.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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 {};

package/dist/patterns/flow.js

@@ -0,0 +1,103 @@
+/**
+ * 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

package/dist/patterns/interview.d.ts

@@ -0,0 +1,53 @@
+import type { ZodType } from 'zod';
+import type { ContextMemory } from '../types/memory';
+import type { Step } from '../types/step';
+/** @public Answer captured by the host for a single interview question. */
+export interface InterviewQuestionAnswer {
+    questionId: string;
+    question: string;
+    answer: string | string[];
+    notes?: string;
+}
+/** @public Result of running an `interview()` step. */
+export type InterviewResult<Q, C> = {
+    status: 'complete';
+    envelope: C;
+} | {
+    status: 'maxQuestions';
+    lastQuestion?: Q;
+};
+/** @public Configuration for the `interview()` pattern. */
+export interface InterviewOpts<Q, C> {
+    /** System prompt instructing the model on how to interview the user. */
+    systemPrompt: string;
+    /** Model identifier passed to `step.llm`. */
+    model: string;
+    /** Zod schema for the `data` payload of a `question` envelope. */
+    questionSchema: ZodType<Q>;
+    /** Zod schema for the `data` payload of a `complete` envelope. */
+    completeSchema: ZodType<C>;
+    /** Host renders the question (e.g. via AskUserService) and returns the answer. */
+    askQuestion: (envelope: Q) => Promise<InterviewQuestionAnswer>;
+    /** Called once when the model emits the complete envelope. */
+    onComplete: (envelope: C) => Promise<void>;
+    /** Hard cap on question/complete turns before the loop exits with `maxQuestions`. Default 8. */
+    maxQuestions?: number;
+    /**
+     * Override how a captured answer becomes the next user message. Default emits a
+     * compact, machine-readable JSON line that the model can parse to build context.
+     */
+    formatAnswer?: (answer: InterviewQuestionAnswer) => string;
+}
+/**
+ * Creates a host-callback-driven structured interview pattern. Internally a loop over a single
+ * body step that delegates to `step.llm` (with `output: discriminatedUnion('type', [...])`) and
+ * then hands the envelope to the host. `askQuestion` renders questions and returns answers fed
+ * back as the next user message; `onComplete` fires once when the model emits `complete`.
+ * Termination via `until.verified(complete) || until.maxSteps(maxQuestions)`.
+ *
+ * @public
+ * @param opts - System prompt, model, question/complete schemas, host callbacks, optional caps.
+ * @returns A `Step` whose output is `InterviewResult<Q, C>` — either the completion envelope or
+ *          `maxQuestions` when the budget is exhausted before the model emits `complete`.
+ */
+export declare function interview<Q, C>(opts: InterviewOpts<Q, C>): Step<ContextMemory, string, InterviewResult<Q, C>>;

package/dist/patterns/interview.js

@@ -0,0 +1,113 @@
+import { z } from 'zod';
+import { loop } from '../builders/loop-builder';
+import { step } from '../builders/step-builders';
+import { frameworkCast } from '../interpreter/framework-cast';
+import { any } from '../until/combinators';
+import { until } from '../until/predicates';
+//#endregion
+//#region Helpers
+const DEFAULT_MAX_QUESTIONS = 8;
+function defaultFormatAnswer(answer) {
+    return JSON.stringify({
+        questionId: answer.questionId,
+        question: answer.question,
+        answer: answer.answer,
+        notes: answer.notes,
+    });
+}
+function isCompleteIterState(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    if (!('status' in value)) {
+        return false;
+    }
+    return value.status === 'complete';
+}
+function buildEnvelopeSchema(questionSchema, completeSchema) {
+    const schema = z.discriminatedUnion('type', [
+        z.object({
+            type: z.literal('question'),
+            data: questionSchema,
+        }),
+        z.object({
+            type: z.literal('complete'),
+            data: completeSchema,
+        }),
+    ]);
+    // ZodDiscriminatedUnion narrows to a non-generic ZodType<Envelope> shape, but
+    // step.llm's `output` field is typed as ZodType<O> for the generic O.
+    return frameworkCast(schema);
+}
+//#endregion
+//#region Public API
+/**
+ * Creates a host-callback-driven structured interview pattern. Internally a loop over a single
+ * body step that delegates to `step.llm` (with `output: discriminatedUnion('type', [...])`) and
+ * then hands the envelope to the host. `askQuestion` renders questions and returns answers fed
+ * back as the next user message; `onComplete` fires once when the model emits `complete`.
+ * Termination via `until.verified(complete) || until.maxSteps(maxQuestions)`.
+ *
+ * @public
+ * @param opts - System prompt, model, question/complete schemas, host callbacks, optional caps.
+ * @returns A `Step` whose output is `InterviewResult<Q, C>` — either the completion envelope or
+ *          `maxQuestions` when the budget is exhausted before the model emits `complete`.
+ */
+export function interview(opts) {
+    const maxQuestions = opts.maxQuestions ?? DEFAULT_MAX_QUESTIONS;
+    const formatAnswer = opts.formatAnswer ?? defaultFormatAnswer;
+    const envelopeSchema = buildEnvelopeSchema(opts.questionSchema, opts.completeSchema);
+    const llmStep = step.llm({
+        id: 'interview-llm',
+        model: opts.model,
+        instructions: opts.systemPrompt,
+        output: envelopeSchema,
+    });
+    const turnStep = step.run({
+        id: 'interview-turn',
+        execute: async (input, ctx) => {
+            const envelope = await ctx.harness.run(llmStep, input, ctx);
+            if (envelope.type === 'complete') {
+                await opts.onComplete(envelope.data);
+                return {
+                    status: 'complete',
+                    envelope: envelope.data,
+                    nextInput: '',
+                };
+            }
+            const answer = await opts.askQuestion(envelope.data);
+            return {
+                status: 'inProgress',
+                lastQuestion: envelope.data,
+                nextInput: formatAnswer(answer),
+            };
+        },
+    });
+    const loopStep = loop({
+        id: 'interview-loop',
+        steps: [
+            turnStep,
+        ],
+        until: any(until.verified(async (out) => ({
+            pass: isCompleteIterState(out),
+        })), until.maxSteps(maxQuestions)),
+        prepareNext: (output) => output.nextInput,
+    });
+    return step.run({
+        id: 'interview',
+        execute: async (input, ctx) => {
+            const final = await ctx.harness.run(loopStep, input, ctx);
+            if (final.status === 'complete') {
+                return {
+                    status: 'complete',
+                    envelope: final.envelope,
+                };
+            }
+            return {
+                status: 'maxQuestions',
+                lastQuestion: final.lastQuestion,
+            };
+        },
+    });
+}
+//#endregion

package/dist/patterns/plans.d.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import type { Context } from '../types/context';
+import type { ContextMemory } from '../types/memory';
+import type { ExecuteStepFn, Step } from '../types/step';
+export interface PlanNode {
+    id: string;
+    description: string;
+    assignee: string;
+    execution: 'sequential' | 'parallel';
+    children?: PlanNode[];
+}
+/** @public Zod schema for recursive `PlanNode` validation. */
+export declare const PlanNodeSchema: z.ZodType<PlanNode>;
+export interface PlanConstraints {
+    toolAllowlist?: Record<string, string[]>;
+    maxStepsPerNode?: number;
+    requireApproval?: string[];
+    validate?: (taskId: string, input: unknown, ctx: Context) => Promise<boolean>;
+}
+/**
+ * Compiles a `PlanNode` tree into an executable step graph using the provided agent factories.
+ *
+ * @public
+ * @param plan - Root plan node describing the task tree.
+ * @param agents - Map of agent names to factory functions producing steps.
+ * @param constraints - Optional constraints for tool allowlists and approval.
+ * @param executeStep - Optional step executor for non-run step kinds.
+ * @returns A compiled `Step` ready for execution.
+ */
+export declare function compilePlan<O>(plan: PlanNode, agents: Record<string, (prompt: string) => Step<ContextMemory, string, unknown>>, constraints?: PlanConstraints, executeStep?: ExecuteStepFn): Step<ContextMemory, string, O>;
+/**
+ * Creates a step that dynamically generates a plan via a planner step and executes it,
+ * retrying with error feedback up to `maxRevisions` times on failure.
+ *
+ * @public
+ * @param opts - Planner step, agent factories, optional constraints, max revision count, and step executor.
+ * @returns A `Step` that adaptively plans and executes.
+ */
+export declare function adaptivePlan<O>(opts: {
+    planner: Step<ContextMemory, string, PlanNode>;
+    agents: Record<string, (prompt: string) => Step<ContextMemory, string, unknown>>;
+    constraints?: PlanConstraints;
+    maxRevisions: number;
+    executeStep?: ExecuteStepFn;
+}): Step<ContextMemory, string, O>;

package/dist/patterns/plans.js

@@ -0,0 +1,125 @@
+import { z } from 'zod';
+import { fork } from '../builders/control-flow-builders';
+import { frameworkCast } from '../interpreter/framework-cast';
+// PlanNode schema — the variable annotation provides the recursive type;
+// z.lazy() returns a compatible type that TypeScript checks against it.
+/** @public Zod schema for recursive `PlanNode` validation. */
+export const PlanNodeSchema = z.lazy(() => z.object({
+    id: z.string(),
+    description: z.string(),
+    assignee: z.string(),
+    execution: z.enum([
+        'sequential',
+        'parallel',
+    ]),
+    children: z.array(PlanNodeSchema).optional(),
+}));
+/**
+ * Compiles a `PlanNode` tree into an executable step graph using the provided agent factories.
+ *
+ * @public
+ * @param plan - Root plan node describing the task tree.
+ * @param agents - Map of agent names to factory functions producing steps.
+ * @param constraints - Optional constraints for tool allowlists and approval.
+ * @param executeStep - Optional step executor for non-run step kinds.
+ * @returns A compiled `Step` ready for execution.
+ */
+export function compilePlan(plan, agents, constraints, executeStep) {
+    return frameworkCast(compileNode(plan, {
+        agents,
+        constraints,
+        executeStep,
+    }));
+}
+function compileNode(node, opts) {
+    const agentFactory = opts.agents[node.assignee];
+    if (!agentFactory) {
+        throw new Error(`Unknown agent: ${node.assignee}`);
+    }
+    // Leaf node - return the step directly from the factory
+    if (!node.children || node.children.length === 0) {
+        return agentFactory(node.description);
+    }
+    // Has children - compile them
+    const childSteps = node.children.map((child) => compileNode(child, opts));
+    if (node.execution === 'parallel') {
+        return fork({
+            id: `plan-fork-${node.id}`,
+            mode: 'all',
+            paths: () => childSteps,
+            merge: (results) => results[results.length - 1],
+        });
+    }
+    // Sequential - chain steps via a run step that uses executeStep
+    return {
+        kind: 'run',
+        id: `plan-seq-${node.id}`,
+        execute: async (input, ctx) => {
+            let currentOutput = input;
+            for (const child of childSteps) {
+                const childInput = typeof currentOutput === 'string' ? currentOutput : JSON.stringify(currentOutput);
+                if (opts.executeStep) {
+                    currentOutput = await opts.executeStep(child, childInput, ctx);
+                }
+                else if (child.kind === 'run') {
+                    currentOutput = await child.execute(childInput, ctx);
+                }
+                else {
+                    throw new Error(`No executeStep provided and child step kind '${child.kind}' cannot be executed directly`);
+                }
+            }
+            return currentOutput;
+        },
+    };
+}
+/**
+ * Creates a step that dynamically generates a plan via a planner step and executes it,
+ * retrying with error feedback up to `maxRevisions` times on failure.
+ *
+ * @public
+ * @param opts - Planner step, agent factories, optional constraints, max revision count, and step executor.
+ * @returns A `Step` that adaptively plans and executes.
+ */
+export function adaptivePlan(opts) {
+    return {
+        kind: 'run',
+        id: 'adaptive-plan',
+        execute: async (input, ctx) => {
+            let lastError = null;
+            for (let revision = 0; revision < opts.maxRevisions; revision++) {
+                // Generate plan
+                const planInput = lastError
+                    ? `${input}\n\nPrevious plan failed: ${lastError.message}`
+                    : input;
+                let plan;
+                if (opts.executeStep) {
+                    plan = PlanNodeSchema.parse(await opts.executeStep(opts.planner, planInput, ctx));
+                }
+                else if (opts.planner.kind === 'run') {
+                    plan = PlanNodeSchema.parse(await opts.planner.execute(planInput, ctx));
+                }
+                else {
+                    throw new Error('Planner must be a run step when no executeStep provided');
+                }
+                // Compile and execute
+                try {
+                    const compiled = compilePlan(plan, opts.agents, opts.constraints, opts.executeStep);
+                    if (opts.executeStep) {
+                        return frameworkCast(await opts.executeStep(compiled, input, ctx));
+                    }
+                    if (compiled.kind === 'run') {
+                        return frameworkCast(await compiled.execute(input, ctx));
+                    }
+                    throw new Error(`No executeStep provided and compiled plan kind '${compiled.kind}' cannot be executed directly`);
+                }
+                catch (e) {
+                    lastError = e instanceof Error ? e : new Error(String(e));
+                    if (revision === opts.maxRevisions - 1) {
+                        throw lastError;
+                    }
+                }
+            }
+            throw lastError;
+        },
+    };
+}

package/dist/patterns/ralph-wiggum.d.ts

@@ -0,0 +1,20 @@
+import type { Tool } from '../types/common';
+import type { ContextMemory } from '../types/memory';
+import type { StepLoop } from '../types/step';
+import type { VerifyFn } from '../until/predicates';
+/**
+ * Creates a retry-with-feedback loop wrapping a ReAct agent. Each iteration spawns an inner agent
+ * and retries with verification feedback until the verifier passes or max iterations is reached.
+ *
+ * @public
+ * @param opts - Model, tools, instructions, verify function, and optional iteration/step limits.
+ * @returns A `StepLoop` that retries the inner agent with feedback.
+ */
+export declare function ralphWiggum(opts: {
+    model: string;
+    instructions: string;
+    tools: Tool[];
+    verify: VerifyFn;
+    maxIterations?: number;
+    innerMaxSteps?: number;
+}): StepLoop<ContextMemory, string, string>;

package/dist/patterns/ralph-wiggum.js

@@ -0,0 +1,37 @@
+import { loop } from '../builders/loop-builder';
+import { spawn } from '../builders/spawn-builder';
+import { any } from '../until/combinators';
+import { until } from '../until/predicates';
+import { react } from './react';
+/**
+ * Creates a retry-with-feedback loop wrapping a ReAct agent. Each iteration spawns an inner agent
+ * and retries with verification feedback until the verifier passes or max iterations is reached.
+ *
+ * @public
+ * @param opts - Model, tools, instructions, verify function, and optional iteration/step limits.
+ * @returns A `StepLoop` that retries the inner agent with feedback.
+ */
+export function ralphWiggum(opts) {
+    const inner = react({
+        model: opts.model,
+        instructions: opts.instructions,
+        tools: opts.tools,
+        maxSteps: opts.innerMaxSteps ?? 20,
+    });
+    return loop({
+        id: 'ralph-wiggum-loop',
+        steps: [
+            spawn({
+                id: 'ralph-iteration',
+                child: inner,
+            }),
+        ],
+        until: any(until.verified(opts.verify), until.maxSteps(opts.maxIterations ?? 50)),
+        prepareNext: (_output, verdict) => {
+            if (verdict.feedback) {
+                return `Previous attempt feedback: ${verdict.feedback}\nContinue working.`;
+            }
+            return 'Continue working on the task.';
+        },
+    });
+}

package/dist/patterns/react.d.ts

@@ -0,0 +1,18 @@
+import type { Tool } from '../types/common';
+import type { ContextMemory, MemoryConfig, MemoryLayer } from '../types/memory';
+import type { StepLoop, StepSpawn } from '../types/step';
+/**
+ * Creates a ReAct (Reason + Act) agent loop: an LLM step with tools iterated until no tool calls or limits are hit.
+ *
+ * @public
+ * @param opts - Model, tools, optional instructions, step/cost limits, and memory layers.
+ * @returns A `StepLoop` (no memory) or `StepSpawn` wrapping a loop (with memory).
+ */
+export declare function react(opts: {
+    model: string;
+    instructions?: string;
+    tools: Tool[];
+    maxSteps?: number;
+    maxCost?: number;
+    memory?: MemoryConfig | MemoryLayer[];
+}): StepLoop<ContextMemory, string, string> | StepSpawn<ContextMemory, string, string>;