@noetic-tools/core 5.2.0 → 5.4.0

package/dist/deprecated.js

@@ -1,28 +0,0 @@
-/**
- * Deprecated aliases from the "memory layer" era of the framework.
- *
- * The layer system assembles the model's *context window* — recall, budget
- * allocation, history projection, the item-append pipeline — so it is named
- * after context, not memory. Every name below still resolves to its
- * replacement; nothing here changes behaviour.
- *
- * Most of these are plain pass-throughs: the alias and its replacement already
- * live in `@noetic-tools/types` / `@noetic-tools/context`, and re-exporting
- * carries each name's `@deprecated` pointer along with it. Only the renaming
- * aliases — where core exports a symbol under a *different* name than its
- * source package does — are declared here.
- *
- * The matching runtime aliases (the `memory:` config key on `provide`/`spawn`/
- * `tool`/`react`/`AgentHarness`, and the `ctx.memory` accessor) are handled at
- * their call sites — see `resolveContextOption`.
- *
- * Scheduled for removal in the next major of `@noetic-tools/core`.
- */
-export { observationalMemory, planMemory, temporalMemory, toolMemoryLayer, workingMemory, } from '@noetic-tools/context';
-export { 
-/**
- * @public
- * @deprecated Renamed to `context`. Declared here rather than re-exported
- * because the builder itself lives in core under its new name.
- */
-context as memory, } from './builders/context-builder.js';

package/dist/patterns/interview.d.ts

@@ -1,53 +0,0 @@
-import type { ContextData } from '@noetic-tools/context';
-import type { Step } from '@noetic-tools/types';
-import type { ZodType } from 'zod';
-/** @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<ContextData, string, InterviewResult<Q, C>>;

package/dist/patterns/interview.js

@@ -1,113 +0,0 @@
-import { frameworkCast } from '@noetic-tools/types';
-import { z } from 'zod';
-import { loop } from '../builders/loop-builder.js';
-import { step } from '../builders/step-builders.js';
-import { any } from '../until/combinators.js';
-import { until } from '../until/predicates.js';
-//#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

@@ -1,44 +0,0 @@
-import type { ContextData } from '@noetic-tools/context';
-import type { Context, ExecuteStepFn, Step } from '@noetic-tools/types';
-import { z } from 'zod';
-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, A = unknown>(plan: PlanNode, agents: Record<string, (prompt: string) => Step<ContextData, string, A>>, constraints?: PlanConstraints, executeStep?: ExecuteStepFn): Step<ContextData, 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, A = unknown>(opts: {
-    planner: Step<ContextData, string, PlanNode>;
-    agents: Record<string, (prompt: string) => Step<ContextData, string, A>>;
-    constraints?: PlanConstraints;
-    maxRevisions: number;
-    executeStep?: ExecuteStepFn;
-}): Step<ContextData, string, O>;

package/dist/patterns/plans.js

@@ -1,125 +0,0 @@
-import { frameworkCast } from '@noetic-tools/types';
-import { z } from 'zod';
-import { fork } from '../builders/control-flow-builders.js';
-// 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) => frameworkCast(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 frameworkCast(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

@@ -1,19 +0,0 @@
-import type { ContextData } from '@noetic-tools/context';
-import type { StepLoop, Tool } from '@noetic-tools/types';
-import type { VerifyFn } from '../until/predicates.js';
-/**
- * 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<ContextData, string, string>;

package/dist/patterns/ralph-wiggum.js

@@ -1,37 +0,0 @@
-import { loop } from '../builders/loop-builder.js';
-import { spawn } from '../builders/spawn-builder.js';
-import { any } from '../until/combinators.js';
-import { until } from '../until/predicates.js';
-import { react } from './react.js';
-/**
- * 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

@@ -1,19 +0,0 @@
-import type { ContextConfig, ContextData, ContextLayer } from '@noetic-tools/context';
-import type { StepLoop, StepSpawn, Tool } from '@noetic-tools/types';
-/**
- * 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 context layers.
- * @returns A `StepLoop` (no context layers) or `StepSpawn` wrapping a loop (with them).
- */
-export declare function react(opts: {
-    model: string;
-    instructions?: string;
-    tools: Tool[];
-    maxSteps?: number;
-    maxCost?: number;
-    context?: ContextConfig | ContextLayer[];
-    /** @deprecated Renamed to `context`. */
-    memory?: ContextConfig | ContextLayer[];
-}): StepLoop<ContextData, string, string> | StepSpawn<ContextData, string, string>;

package/dist/patterns/react.js

@@ -1,41 +0,0 @@
-import { resolveContextOption } from '../builders/context-option.js';
-import { loop } from '../builders/loop-builder.js';
-import { spawn } from '../builders/spawn-builder.js';
-import { step } from '../builders/step-builders.js';
-import { any } from '../until/combinators.js';
-import { until } from '../until/predicates.js';
-/**
- * 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 context layers.
- * @returns A `StepLoop` (no context layers) or `StepSpawn` wrapping a loop (with them).
- */
-export function react(opts) {
-    const llmStep = step.llm({
-        id: 'react-step',
-        model: opts.model,
-        instructions: opts.instructions,
-        tools: opts.tools,
-    });
-    const loopStep = loop({
-        id: 'react-loop',
-        steps: [
-            llmStep,
-        ],
-        until: any(until.noToolCalls(), until.maxSteps(opts.maxSteps ?? 10), ...(opts.maxCost
-            ? [
-                until.maxCost(opts.maxCost),
-            ]
-            : [])),
-    });
-    const layers = resolveContextOption(opts);
-    if (!layers) {
-        return loopStep;
-    }
-    return spawn({
-        id: 'react-agent',
-        child: loopStep,
-        context: layers,
-    });
-}