@noetic-tools/core 0.2.0 → 0.3.0

package/dist/memory/layers/plan.js

@@ -1,374 +0,0 @@
-import { z } from 'zod';
-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;
-const MAX_EXECUTION_LOG_ENTRIES = 10;
-const PLAN_SLOT = Slot.PROCEDURAL - 10; // 240
-const ALLOWED_TOOLS_IN_PLAN_MODE = new Set([
-    'Read',
-    'Grep',
-    'Find',
-    'Ls',
-    'AskUserQuestion',
-    'activateSkill',
-    'agent',
-    'checkAgent',
-    'sendMessage',
-    'requestPlanApproval',
-    'plan/enterPlanMode',
-    'plan/updatePrd',
-    'plan/setPlanTree',
-    'plan/exitPlanMode',
-]);
-//#endregion
-//#region Types
-export const PlanPhase = {
-    Idle: 'idle',
-    Planning: 'planning',
-    Executing: 'executing',
-    Completed: 'completed',
-    Failed: 'failed',
-};
-//#endregion
-//#region Helpers
-function createDefaultState() {
-    return {
-        phase: PlanPhase.Idle,
-        prd: null,
-        planTree: null,
-        executionLog: [],
-        version: 0,
-    };
-}
-function validateTreeDepth(node, maxDepth) {
-    return flowDepth(node) <= maxDepth;
-}
-function buildAllowedTools(config) {
-    if (!config?.additionalAllowedTools?.length) {
-        return ALLOWED_TOOLS_IN_PLAN_MODE;
-    }
-    return new Set([
-        ...ALLOWED_TOOLS_IN_PLAN_MODE,
-        ...config.additionalAllowedTools,
-    ]);
-}
-function trimExecutionLog(log) {
-    if (log.length <= MAX_EXECUTION_LOG_ENTRIES) {
-        return log;
-    }
-    return log.slice(log.length - MAX_EXECUTION_LOG_ENTRIES);
-}
-//#endregion
-//#region Recall Renderers
-function recallPlanning(state, additionalInstructions) {
-    const sections = [
-        '<plan_mode>',
-        '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, 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. 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',
-        '- `plan/updatePrd` — set markdown PRD content',
-        '- `plan/setPlanTree` — set the optional JSON execution plan',
-        '- `plan/exitPlanMode` `{ action: "execute" }` — request approval and exit to executing',
-        '- `plan/exitPlanMode` `{ action: "cancel" }` — discard plan and return to idle',
-        '',
-        '## Constraints',
-        '- 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`.',
-    ];
-    if (additionalInstructions) {
-        sections.push('', '## Additional Instructions', '', additionalInstructions);
-    }
-    if (state.prd) {
-        sections.push('', '## Current PRD Draft', '', state.prd);
-    }
-    if (state.planTree) {
-        sections.push('', '## Current Plan Tree', '', JSON.stringify(state.planTree, null, 2));
-    }
-    sections.push('</plan_mode>');
-    return sections.join('\n');
-}
-function recallExecuting(state) {
-    const sections = [
-        '<active_plan>',
-        '## PRD',
-        '',
-        state.prd ?? '',
-        '',
-        '## Execution Plan',
-        '',
-        JSON.stringify(state.planTree, null, 2),
-        '</active_plan>',
-    ];
-    return sections.join('\n');
-}
-function recallTerminal(state) {
-    const lastEntry = state.executionLog[state.executionLog.length - 1];
-    const outcome = lastEntry?.outcome ?? 'unknown';
-    return `<plan_outcome>Plan v${state.version} ${outcome}.</plan_outcome>`;
-}
-const RECALL_RENDERERS = {
-    [PlanPhase.Planning]: recallPlanning,
-    [PlanPhase.Executing]: recallExecuting,
-    [PlanPhase.Completed]: recallTerminal,
-    [PlanPhase.Failed]: recallTerminal,
-};
-//#endregion
-//#region Public API
-/**
- * Creates a plan memory layer that manages the PRD authoring and plan execution lifecycle.
- *
- * @public
- * @param config - Optional configuration for scope, allowed tools, and limits.
- * @returns A `MemoryLayer` providing plan mode, PRD storage, and execution tracking.
- */
-export function planMemory(config) {
-    const scope = config?.scope ?? 'thread';
-    const maxPrdLength = config?.maxPrdLength ?? MAX_PRD_LENGTH;
-    const maxTreeDepth = config?.maxTreeDepth ?? MAX_TREE_DEPTH;
-    const allowedTools = buildAllowedTools(config);
-    const additionalPlanInstructions = config?.additionalPlanInstructions;
-    const onEnterSession = config?.onEnterSession;
-    const onExit = config?.onExit;
-    return {
-        id: 'plan',
-        name: 'Plan Memory',
-        slot: PLAN_SLOT,
-        scope,
-        budget: {
-            min: 100,
-            max: 3e3,
-        },
-        provides: {
-            status: layerData({
-                read: (state) => ({
-                    phase: state.phase,
-                    hasPrd: state.prd !== null,
-                    hasPlanTree: state.planTree !== null,
-                    version: state.version,
-                }),
-            }),
-            enterPlanMode: layerFn({
-                description: 'Enter plan mode. The agent switches to read-only exploration and PRD authoring.',
-                input: z.object({
-                    goal: z.string().optional(),
-                }),
-                output: z.string(),
-                execute: async (args, state) => {
-                    if (state.phase !== PlanPhase.Idle) {
-                        return {
-                            result: `Cannot enter plan mode: current phase is "${state.phase}".`,
-                            state,
-                        };
-                    }
-                    const session = onEnterSession ? await onEnterSession() : null;
-                    return {
-                        result: 'Plan mode activated. Explore the codebase, then call plan/updatePrd.',
-                        state: {
-                            ...state,
-                            phase: PlanPhase.Planning,
-                            prd: args.goal ? `# Goal\n\n${args.goal}\n` : null,
-                            planTree: null,
-                            version: state.version + 1,
-                            planSlug: session?.slug ?? null,
-                        },
-                    };
-                },
-            }),
-            updatePrd: layerFn({
-                description: 'Update the PRD document with new markdown content.',
-                input: z.object({
-                    content: z.string(),
-                }),
-                output: z.string(),
-                execute: async (args, state) => {
-                    if (state.phase !== PlanPhase.Planning) {
-                        return {
-                            result: `Cannot update PRD: current phase is "${state.phase}". Enter plan mode first.`,
-                            state,
-                        };
-                    }
-                    if (args.content.length > maxPrdLength) {
-                        return {
-                            result: `PRD content exceeds maximum length of ${maxPrdLength} characters.`,
-                            state,
-                        };
-                    }
-                    return {
-                        result: 'PRD updated successfully.',
-                        state: {
-                            ...state,
-                            prd: args.content,
-                        },
-                    };
-                },
-            }),
-            setPlanTree: layerFn({
-                description: 'Set the execution plan tree. Input must be a valid FlowNode — a discriminated union with kind: "llm" | "subagent" | "fork" | "spawn" | "sequence". Structural nodes (sequence, fork, spawn) nest child FlowNodes; leaf nodes (llm, subagent) carry execution instructions.',
-                input: FlowSchema,
-                output: z.string(),
-                execute: async (args, state) => {
-                    if (state.phase !== PlanPhase.Planning) {
-                        return {
-                            result: `Cannot set plan tree: current phase is "${state.phase}". Enter plan mode first.`,
-                            state,
-                        };
-                    }
-                    if (!validateTreeDepth(args, maxTreeDepth)) {
-                        return {
-                            result: `Plan tree exceeds maximum depth of ${maxTreeDepth}.`,
-                            state,
-                        };
-                    }
-                    return {
-                        result: 'Plan tree set successfully. Call plan/exitPlanMode to begin execution.',
-                        state: {
-                            ...state,
-                            planTree: args,
-                        },
-                    };
-                },
-            }),
-            exitPlanMode: layerFn({
-                description: 'Exit plan mode. Use action "execute" to begin executing the plan, or "cancel" to discard it.',
-                input: z.object({
-                    action: z.enum([
-                        'execute',
-                        'cancel',
-                    ]),
-                }),
-                output: z.string(),
-                execute: async (args, state) => {
-                    if (state.phase !== PlanPhase.Planning) {
-                        return {
-                            result: `Cannot exit plan mode: current phase is "${state.phase}".`,
-                            state,
-                        };
-                    }
-                    if (args.action === 'cancel') {
-                        return {
-                            result: 'Plan cancelled. Returned to idle.',
-                            state: createDefaultState(),
-                        };
-                    }
-                    if (!state.prd) {
-                        return {
-                            result: 'Cannot execute: no PRD has been written. Call plan/updatePrd first.',
-                            state,
-                        };
-                    }
-                    if (!state.planTree) {
-                        return {
-                            result: 'Cannot execute: no plan tree has been set. Call plan/setPlanTree first.',
-                            state,
-                        };
-                    }
-                    if (onExit) {
-                        const { approved } = await onExit(state);
-                        if (!approved) {
-                            return {
-                                result: 'User did not approve the plan. Stay in plan mode, address their feedback, and call plan/exitPlanMode again when ready.',
-                                state,
-                            };
-                        }
-                    }
-                    return {
-                        result: 'Plan mode exited. Execution phase begun.',
-                        state: {
-                            ...state,
-                            phase: PlanPhase.Executing,
-                        },
-                    };
-                },
-            }),
-        },
-        hooks: {
-            async init({ storage }) {
-                const saved = await storage.get('state');
-                return {
-                    state: saved ?? createDefaultState(),
-                };
-            },
-            async recall({ state }) {
-                if (state.phase === PlanPhase.Idle) {
-                    return null;
-                }
-                const renderer = RECALL_RENDERERS[state.phase];
-                if (!renderer) {
-                    return null;
-                }
-                const content = renderer(state, additionalPlanInstructions);
-                return {
-                    items: [
-                        createMessage(content, 'developer'),
-                    ],
-                    tokenCount: estimateTokens(content),
-                };
-            },
-            async beforeToolCall({ toolName, state }) {
-                if (state.phase !== PlanPhase.Planning) {
-                    return {
-                        decision: {
-                            action: SteeringAction.Allow,
-                        },
-                        state,
-                    };
-                }
-                if (allowedTools.has(toolName)) {
-                    return {
-                        decision: {
-                            action: SteeringAction.Allow,
-                        },
-                        state,
-                    };
-                }
-                return {
-                    decision: {
-                        action: SteeringAction.Deny,
-                        guidance: `Plan mode is active. "${toolName}" is not allowed during planning. Use read-only tools (Read, Grep, Find, Ls) to explore the codebase, then call plan/updatePrd to write your PRD.`,
-                    },
-                    state,
-                };
-            },
-            async onSpawn({ parentState }) {
-                return {
-                    childState: structuredClone(parentState),
-                };
-            },
-            async onComplete({ state, outcome }) {
-                if (state.phase !== PlanPhase.Executing) {
-                    return;
-                }
-                return {
-                    state: {
-                        ...state,
-                        phase: outcome === 'success' ? PlanPhase.Completed : PlanPhase.Failed,
-                        executionLog: trimExecutionLog([
-                            ...state.executionLog,
-                            {
-                                timestamp: Date.now(),
-                                version: state.version,
-                                outcome,
-                            },
-                        ]),
-                    },
-                };
-            },
-        },
-    };
-}
-//#endregion

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

@@ -1,27 +0,0 @@
-import type { MemoryScope } from '../../types/memory.js';
-interface StaticContentOpts {
-    id?: string;
-    slot?: number;
-    scope?: MemoryScope;
-    load: () => Promise<string>;
-    tag?: string;
-}
-/**
- * Creates a read-only memory layer that loads static content once at init and injects it into recall.
- *
- * @public
- * @param opts - Configuration with a `load` function and optional id, slot, scope, and XML tag name.
- * @returns A `MemoryLayer` that provides static instructional content to the model.
- */
-export declare function staticContent(opts: StaticContentOpts): {
-    id: string;
-    slot: number;
-    scope: MemoryScope;
-    hooks: {
-        init(): Promise<{
-            state: string;
-        }>;
-        recall({ state }: import("../../index.js").RecallParams<string>): Promise<string | null>;
-    };
-};
-export {};

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

@@ -1,35 +0,0 @@
-import { Slot } from '../../types/memory.js';
-/**
- * Creates a read-only memory layer that loads static content once at init and injects it into recall.
- *
- * @public
- * @param opts - Configuration with a `load` function and optional id, slot, scope, and XML tag name.
- * @returns A `MemoryLayer` that provides static instructional content to the model.
- */
-export function staticContent(opts) {
-    const tag = opts.tag ?? 'instructions';
-    return {
-        id: opts.id ?? 'static-content',
-        slot: opts.slot ?? Slot.WORKING_MEMORY + 5,
-        scope: opts.scope ?? 'resource',
-        hooks: {
-            async init() {
-                const raw = await opts.load();
-                if (!raw) {
-                    return {
-                        state: '',
-                    };
-                }
-                return {
-                    state: `<${tag}>\n${raw}\n</${tag}>`,
-                };
-            },
-            async recall({ state }) {
-                if (!state) {
-                    return null;
-                }
-                return state;
-            },
-        },
-    };
-}

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

@@ -1,51 +0,0 @@
-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.
- *
- * @public
- * @param config - Steering configuration including rules, scope, and max ledger size.
- * @returns A `MemoryLayer` that enforces steering rules via allow/deny/guide decisions.
- */
-export declare function steering(config: SteeringConfig): {
-    id: "steering";
-    name: string;
-    slot: 90;
-    scope: MemoryScope;
-    budget: {
-        min: number;
-        max: number;
-    };
-    timeouts: {
-        beforeToolCall: number;
-        afterModelCall: number;
-    };
-    hooks: {
-        init({ storage }: import("../../index.js").InitParams): Promise<{
-            state: SteeringState;
-        }>;
-        recall({ state }: import("../../index.js").RecallParams<SteeringState>): Promise<{
-            items: import("../../index.js").InputMessageItem[];
-            tokenCount: number;
-            state: SteeringState;
-        } | null>;
-        store(): Promise<undefined>;
-        beforeToolCall({ toolName, toolArgs, ctx, state }: BeforeToolCallParams<SteeringState>): Promise<{
-            decision: SteeringDecision;
-            state: SteeringState;
-        }>;
-        afterModelCall({ response, ctx, state }: AfterModelCallParams<SteeringState>): Promise<{
-            decision: SteeringDecision;
-            state: SteeringState;
-        }>;
-        onSpawn({ parentState }: import("../../index.js").SpawnParams<SteeringState>): Promise<{
-            childState: {
-                ledger: LedgerEntry[];
-                pendingAsync: never[];
-            };
-        }>;
-        onComplete({ state, outcome }: import("../../index.js").CompleteParams<SteeringState>): Promise<{
-            state: SteeringState;
-        }>;
-    };
-};