@noetic-tools/core 0.0.1

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

@@ -0,0 +1,53 @@
+export interface ObservationalState {
+    observations: string[];
+    buffer: string[];
+    bufferTokens: number;
+    version: number;
+}
+export type ObserverFn = (buffer: string[]) => Promise<string[]>;
+export interface ObservationalMemoryConfig {
+    bufferThreshold?: number;
+    maxObservations?: number;
+    scope?: 'thread' | 'resource';
+    observer?: ObserverFn;
+}
+/**
+ * Creates a memory layer that buffers raw items and distills them into observations when a token threshold is reached.
+ *
+ * @public
+ * @param config - Optional configuration for buffer threshold, max observations, scope, and observer function.
+ * @returns A `MemoryLayer` that accumulates and summarizes observations over time.
+ */
+export declare function observationalMemory(config?: ObservationalMemoryConfig): {
+    id: "observational-memory";
+    name: string;
+    slot: 200;
+    scope: "thread" | "resource";
+    budget: {
+        min: number;
+        max: number;
+    };
+    timeouts: {
+        store: number;
+    };
+    hooks: {
+        init({ storage }: import("../..").InitParams): Promise<{
+            state: ObservationalState;
+        }>;
+        recall({ state }: import("../..").RecallParams<ObservationalState>): Promise<{
+            items: import("../..").InputMessageItem[];
+            tokenCount: number;
+        } | null>;
+        store({ newItems, state }: import("../..").StoreParams<ObservationalState>): Promise<{
+            state: {
+                buffer: string[];
+                bufferTokens: number;
+                observations: string[];
+                version: number;
+            };
+        }>;
+        onSpawn({ parentState }: import("../..").SpawnParams<ObservationalState>): Promise<{
+            childState: ObservationalState;
+        }>;
+    };
+};

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

@@ -0,0 +1,110 @@
+import { createMessage, estimateTokens } from '../../interpreter/message-helpers';
+import { isOutputText } from '../../interpreter/typeguards';
+import { Slot } from '../../types/memory';
+const DEFAULT_BUFFER_THRESHOLD_TOKENS = 2_000;
+const DEFAULT_MAX_OBSERVATIONS = 50;
+/**
+ * Creates a memory layer that buffers raw items and distills them into observations when a token threshold is reached.
+ *
+ * @public
+ * @param config - Optional configuration for buffer threshold, max observations, scope, and observer function.
+ * @returns A `MemoryLayer` that accumulates and summarizes observations over time.
+ */
+export function observationalMemory(config) {
+    const maxObs = config?.maxObservations ?? DEFAULT_MAX_OBSERVATIONS;
+    const threshold = config?.bufferThreshold ?? DEFAULT_BUFFER_THRESHOLD_TOKENS;
+    const observer = config?.observer;
+    return {
+        id: 'observational-memory',
+        name: 'Observational Memory',
+        slot: Slot.OBSERVATIONS,
+        scope: config?.scope ?? 'resource',
+        budget: {
+            min: 500,
+            max: 2_500,
+        },
+        timeouts: {
+            store: 60_000,
+        },
+        hooks: {
+            async init({ storage }) {
+                const saved = await storage.get('state');
+                return {
+                    state: saved ?? {
+                        observations: [],
+                        buffer: [],
+                        bufferTokens: 0,
+                        version: 0,
+                    },
+                };
+            },
+            async recall({ state }) {
+                if (!state?.observations?.length) {
+                    return null;
+                }
+                const bullets = state.observations.map((o) => `- ${o}`).join('\n');
+                const text = `<observations>\n${bullets}\n</observations>`;
+                return {
+                    items: [
+                        createMessage(text, 'developer'),
+                    ],
+                    tokenCount: estimateTokens(text),
+                };
+            },
+            async store({ newItems, state }) {
+                const s = state ?? {
+                    observations: [],
+                    buffer: [],
+                    bufferTokens: 0,
+                    version: 0,
+                };
+                // Accumulate new items into buffer
+                const textItems = newItems
+                    .filter((i) => i.type === 'message')
+                    .map((i) => i.content
+                    .filter(isOutputText)
+                    .map((c) => c.text)
+                    .join(''))
+                    .filter((t) => t.length > 0);
+                const newBuffer = [
+                    ...s.buffer,
+                    ...textItems,
+                ];
+                // Token-based threshold: accumulate incrementally
+                const newTokens = textItems.reduce((sum, t) => sum + estimateTokens(t), 0);
+                const totalBufferTokens = s.bufferTokens + newTokens;
+                if (totalBufferTokens >= threshold) {
+                    const distilled = observer
+                        ? await observer(newBuffer)
+                        : [
+                            `Processed ${newBuffer.length} items`,
+                        ];
+                    const newObservations = [
+                        ...s.observations,
+                        ...distilled,
+                    ].slice(-maxObs);
+                    return {
+                        state: {
+                            observations: newObservations,
+                            buffer: [],
+                            bufferTokens: 0,
+                            version: s.version + 1,
+                        },
+                    };
+                }
+                return {
+                    state: {
+                        ...s,
+                        buffer: newBuffer,
+                        bufferTokens: totalBufferTokens,
+                    },
+                };
+            },
+            async onSpawn({ parentState }) {
+                return {
+                    childState: structuredClone(parentState),
+                };
+            },
+        },
+    };
+}

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

@@ -0,0 +1,55 @@
+import type { FlowNode } from '../../patterns/flow';
+import type { MemoryLayer, MemoryScope } from '../../types/memory';
+export declare const PlanPhase: {
+    readonly Idle: "idle";
+    readonly Planning: "planning";
+    readonly Executing: "executing";
+    readonly Completed: "completed";
+    readonly Failed: "failed";
+};
+export type PlanPhase = (typeof PlanPhase)[keyof typeof PlanPhase];
+export interface PlanExecutionEntry {
+    timestamp: number;
+    version: number;
+    outcome: 'success' | 'failure' | 'aborted';
+}
+export interface PlanState {
+    phase: PlanPhase;
+    prd: string | null;
+    planTree: FlowNode | null;
+    executionLog: PlanExecutionEntry[];
+    version: number;
+    /** Identifier of the on-disk plan session (set by `onEnterSession` host callback). */
+    planSlug?: string | null;
+}
+/** Host-supplied callback invoked when entering plan mode. Returns a session identifier the host owns (e.g. on-disk dir slug). */
+export type PlanEnterSessionCallback = () => Promise<{
+    slug: string;
+}>;
+/**
+ * Host-supplied callback invoked when the model requests `exitPlanMode` with `action: 'execute'`.
+ * Return `{ approved: false }` to keep the layer in `Planning` (e.g. user rejected the plan in the UI).
+ */
+export type PlanExitCallback = (state: PlanState) => Promise<{
+    approved: boolean;
+}>;
+export interface PlanMemoryConfig {
+    scope?: MemoryScope;
+    additionalAllowedTools?: string[];
+    maxPrdLength?: number;
+    maxTreeDepth?: number;
+    /** Extra free-form instructions appended to the planning-phase recall payload. */
+    additionalPlanInstructions?: string;
+    /** Called once when the layer transitions Idle → Planning. */
+    onEnterSession?: PlanEnterSessionCallback;
+    /** Called when `exitPlanMode` is requested with `action: 'execute'`. */
+    onExit?: PlanExitCallback;
+}
+/**
+ * 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 declare function planMemory(config?: PlanMemoryConfig): MemoryLayer<PlanState>;

package/dist/memory/layers/plan.js

@@ -0,0 +1,369 @@
+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';
+//#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',
+    'activateSkill',
+    '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) to explore the codebase.',
+        '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.',
+        '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.',
+        '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`).',
+        '- 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

@@ -0,0 +1,27 @@
+import type { MemoryScope } from '../../types/memory';
+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("../..").RecallParams<string>): Promise<string | null>;
+    };
+};
+export {};

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

@@ -0,0 +1,35 @@
+import { Slot } from '../../types/memory';
+/**
+ * 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;
+            },
+        },
+    };
+}