@noetic-tools/context 1.0.0 → 1.1.0

package/dist/context/layers/plan-context.d.ts

@@ -1,4 +1,6 @@
 import type { ContextLayer, ContextScope, WorkflowDocument, WorkflowNode } from '@noetic-tools/types';
+import { PlanStyle } from './plan-prompts.js';
+export { PlanStyle } from './plan-prompts.js';
 export declare const PlanPhase: {
     readonly Idle: 'idle';
     readonly Planning: 'planning';
@@ -51,6 +53,20 @@ export interface PlanContextConfig {
      * must include `'subflow'` for named workflows to be referenceable.
      */
     allowedNodeKinds?: WorkflowNode['kind'][];
+    /**
+     * How the planning briefing shapes the turn. `phased` (default) marches
+     * through explore → design → review → write → exit; `interview` loops
+     * explore → write → ask, which suits requests whose requirements are still
+     * vague.
+     */
+    style?: PlanStyle;
+    /**
+     * Name of the host's sub-agent tool, when it has one (e.g. `'agent'`). The
+     * layer ships no such tool, so the briefing's parallel-exploration guidance
+     * stays out until a host names one — telling the model to call a tool that is
+     * not registered costs a turn and teaches it nothing.
+     */
+    subAgentTool?: string;
     /** Extra free-form instructions appended to the planning-phase recall payload. */
     additionalPlanInstructions?: string;
     /** Called once when the layer transitions Idle → Planning. */

package/dist/context/layers/plan-context.js

@@ -1,6 +1,8 @@
 import { createMessage, estimateTokens, Slot, SteeringAction, WorkflowDocumentSchema, walkWorkflow, workflowDepth, } from '@noetic-tools/types';
 import { z } from 'zod';
 import { layerData, layerFn } from '../layer-provides.js';
+import { nodeKindList, PlanStyle, renderExecuting, renderPlanning, renderTerminal, } from './plan-prompts.js';
+export { PlanStyle } from './plan-prompts.js';
 //#region Constants
 const MAX_PRD_LENGTH = 5e4;
 const MAX_DEPTH = 5;
@@ -224,103 +226,19 @@ function trimExecutionLog(log) {
     }
     return log.slice(log.length - MAX_EXECUTION_LOG_ENTRIES);
 }
-/** One-line summary of a workflow: node count and a kind histogram. */
-function summarizeWorkflow(name, doc) {
-    const counts = new Map();
-    let total = 0;
-    for (const node of walkWorkflow(doc.root)) {
-        total++;
-        counts.set(node.kind, (counts.get(node.kind) ?? 0) + 1);
-    }
-    const histogram = [
-        ...counts.entries(),
-    ]
-        .map(([kind, n]) => `${kind} x${n}`)
-        .join(', ');
-    return `- ${name}: ${total} node${total === 1 ? '' : 's'} (${histogram})`;
-}
-function renderWorkflowSummaries(state) {
-    const entries = Object.entries(state.workflows).sort(([a], [b]) => a.localeCompare(b));
-    if (entries.length === 0) {
-        return [];
-    }
-    return [
-        '',
-        '## Named Workflows',
-        '',
-        ...entries.map(([name, doc]) => summarizeWorkflow(name, doc)),
-        "(Use plan/getWorkflow to review a workflow's JSON before revising it.)",
-    ];
-}
-//#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 `{ "document": { "version": 1, "root": <WorkflowNode> } }` — a JSON workflow conforming to ' +
-            SCHEMA_URL +
-            '. Node kinds: `llm` (model turn), `tool` (single tool call), `sequence`, `fork` (parallel paths), `branch` (substring routing), `loop` (body + until predicate), `spawn` (isolated child), `subflow` (reference to a named workflow), and coding-agent nodes (`claude-code`, `codex`, `opencode`, `pi`). Every node needs a unique `id`. **Keep the tree SMALL** — aim for at most ~7 top-level nodes the user can review at a glance. Factor detailed mechanics (multi-step verification, retries, fan-out) into NAMED workflows: define each with `plan/setWorkflow` `{ "name": "<slug>", "document": {...} }` and reference it from the tree with `{ "kind": "subflow", "id": "...", "ref": "<slug>" }`. Named workflows may reference other named workflows but must not form cycles.',
-        '5. **Exit** — Call `plan/exitPlanMode` with `{ action: "execute" }` to request approval. Every subflow ref must name a defined workflow or the exit is rejected. 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 reviewed plan as a JSON workflow document',
-        '- `plan/setWorkflow` — create or replace a named workflow (referenced via subflow nodes)',
-        '- `plan/removeWorkflow` — delete a named workflow',
-        "- `plan/getWorkflow` — read back a named workflow's JSON",
-        '- `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 the plan/* actions).',
-        '- 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(...renderWorkflowSummaries(state));
-    sections.push('</plan_mode>');
-    return sections.join('\n');
-}
-function recallExecuting(state) {
-    const sections = [
-        '<active_plan>',
-        '## PRD',
-        '',
-        state.prd ?? '',
-    ];
-    if (state.planTree) {
-        sections.push('', '## Execution Plan', '', JSON.stringify(state.planTree, null, 2));
-    }
-    sections.push(...renderWorkflowSummaries(state));
-    sections.push('</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,
+    [PlanPhase.Planning]: (state, options) => renderPlanning(state, {
+        style: options.style,
+        schemaUrl: SCHEMA_URL,
+        allowedTools: options.allowedTools,
+        allowedNodeKinds: options.allowedNodeKinds,
+        subAgentTool: options.subAgentTool,
+        extra: options.extra,
+        maxChars: options.maxChars,
+    }),
+    [PlanPhase.Executing]: (state, options) => renderExecuting(state, options.maxChars),
+    [PlanPhase.Completed]: (state, options) => renderTerminal(state, options.maxChars),
+    [PlanPhase.Failed]: (state, options) => renderTerminal(state, options.maxChars),
 };
 //#endregion
 //#region Public API
@@ -346,6 +264,8 @@ export function planContext(config) {
         allowedNodeKinds: config?.allowedNodeKinds,
     };
     const allowedTools = buildAllowedTools(config);
+    const style = config?.style ?? PlanStyle.Phased;
+    const subAgentTool = config?.subAgentTool;
     const additionalPlanInstructions = config?.additionalPlanInstructions;
     const onEnterSession = config?.onEnterSession;
     const onExit = config?.onExit;
@@ -427,7 +347,9 @@ export function planContext(config) {
             }),
             setPlanTree: layerFn({
                 description: 'Set the execution plan as a JSON workflow document: { "document": { "version": 1, "root": <WorkflowNode> } }. ' +
-                    'WorkflowNode is a discriminated union on "kind" (llm, tool, sequence, fork, branch, loop, spawn, subflow, claude-code, codex, opencode, pi); every node needs a unique "id". ' +
+                    // Drawn from the same table as the briefing's kind list, so the two
+                    // can never disagree about what this plan is allowed to use.
+                    `WorkflowNode is a discriminated union on "kind" (${nodeKindList(config?.allowedNodeKinds)}); every node needs a unique "id". ` +
                     'Keep this tree SMALL — reference named workflows with { "kind": "subflow", "id": "...", "ref": "<workflow-name>" } and define them via plan/setWorkflow. ' +
                     `Schema: ${SCHEMA_URL}`,
                 // The document is validated with WorkflowDocumentSchema inside execute
@@ -682,16 +604,28 @@ export function planContext(config) {
                 if (!renderer) {
                     return null;
                 }
-                const content = renderer(state, additionalPlanInstructions);
-                // Respect the budget: estimateTokens uses ~4 chars/token, so cap the
-                // rendered text at budget*4 chars to keep tokenCount <= budget.
-                const maxChars = budget * 4;
-                const trimmed = content.length > maxChars ? content.slice(0, maxChars) : content;
+                // estimateTokens counts ~4 chars per token, so budget*4 chars is the
+                // ceiling the renderer must fit under.
+                const content = renderer(state, {
+                    style,
+                    allowedTools: [
+                        ...allowedTools,
+                    ].sort(),
+                    allowedNodeKinds: limits.allowedNodeKinds,
+                    subAgentTool,
+                    extra: additionalPlanInstructions,
+                    maxChars: budget * 4,
+                });
+                // A budget too small for even the compact briefing buys nothing but a
+                // fragment of a rule, so the layer sits the turn out.
+                if (content === null) {
+                    return null;
+                }
                 return {
                     items: [
-                        createMessage(trimmed, 'developer'),
+                        createMessage(content, 'developer'),
                     ],
-                    tokenCount: estimateTokens(trimmed),
+                    tokenCount: estimateTokens(content),
                 };
             },
             async beforeToolCall({ toolName, state }) {

package/dist/context/layers/plan-prompts.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The text the plan layer puts in front of the model: the plan-mode briefing
+ * during planning, the active-plan reminder during execution, and the outcome
+ * line after it ends.
+ *
+ * Two planning styles are offered, mirroring how a planning turn is actually
+ * spent. `phased` marches through explore → design → review → write → exit and
+ * suits work whose shape is already known. `interview` loops explore → write →
+ * ask and suits vague requests, where the user is the missing input.
+ *
+ * Rendering is pure: every function takes state and returns a string, or null
+ * when the budget is too small to say anything coherent. The layer owns which
+ * one runs for a given phase.
+ */
+import type { WorkflowNode } from '@noetic-tools/types';
+import type { PlanState } from './plan-context.js';
+/** How the planning briefing shapes the turn. */
+export declare const PlanStyle: {
+    /** Explore → design → review → write → exit. Best when the work's shape is known. */
+    readonly Phased: 'phased';
+    /** Explore → write → ask, on repeat. Best when requirements are still vague. */
+    readonly Interview: 'interview';
+};
+export type PlanStyle = (typeof PlanStyle)[keyof typeof PlanStyle];
+export interface PlanningPromptOptions {
+    style: PlanStyle;
+    schemaUrl: string;
+    /** Every tool the layer will let through, so the briefing names what the host actually permits. */
+    allowedTools: string[];
+    /** Node kinds the layer will accept. Undefined means all of them. */
+    allowedNodeKinds?: WorkflowNode['kind'][];
+    /**
+     * Name of the host's sub-agent tool, when it has one. The layer ships no such
+     * tool, so the parallel-exploration guidance stays out of the briefing until a
+     * host says the tool exists — instructions to call a tool that is not
+     * registered cost a turn and teach the model nothing.
+     */
+    subAgentTool?: string;
+    /** Extra host instructions appended to the briefing. */
+    extra?: string;
+    /** Character budget for the whole block. */
+    maxChars: number;
+}
+/**
+ * The plan-mode briefing: what the model may do, how to spend the turn, and
+ * what it has so far. Returns null when even the compact briefing overflows —
+ * half a rule is worse than no rule.
+ */
+export declare function renderPlanning(state: PlanState, options: PlanningPromptOptions): string | null;
+/** The approved plan, carried into execution so the model works from it rather than from memory. */
+export declare function renderExecuting(state: PlanState, maxChars: number): string | null;
+/** One line saying how the last execution ended. */
+export declare function renderTerminal(state: PlanState, maxChars: number): string | null;
+/**
+ * The node kinds a plan may use, as a prose list. Shared with `setPlanTree`'s
+ * tool description so the briefing and the tool never disagree about what is
+ * allowed.
+ */
+export declare function nodeKindList(allowed?: WorkflowNode['kind'][]): string;

package/dist/context/layers/plan-prompts.js

@@ -0,0 +1,420 @@
+/**
+ * The text the plan layer puts in front of the model: the plan-mode briefing
+ * during planning, the active-plan reminder during execution, and the outcome
+ * line after it ends.
+ *
+ * Two planning styles are offered, mirroring how a planning turn is actually
+ * spent. `phased` marches through explore → design → review → write → exit and
+ * suits work whose shape is already known. `interview` loops explore → write →
+ * ask and suits vague requests, where the user is the missing input.
+ *
+ * Rendering is pure: every function takes state and returns a string, or null
+ * when the budget is too small to say anything coherent. The layer owns which
+ * one runs for a given phase.
+ */
+import { walkWorkflow } from '@noetic-tools/types';
+//#region Types
+/** How the planning briefing shapes the turn. */
+export const PlanStyle = {
+    /** Explore → design → review → write → exit. Best when the work's shape is known. */
+    Phased: 'phased',
+    /** Explore → write → ask, on repeat. Best when requirements are still vague. */
+    Interview: 'interview',
+};
+//#endregion
+//#region Public API
+/**
+ * The plan-mode briefing: what the model may do, how to spend the turn, and
+ * what it has so far. Returns null when even the compact briefing overflows —
+ * half a rule is worse than no rule.
+ */
+export function renderPlanning(state, options) {
+    const turn = options.style === PlanStyle.Interview
+        ? interviewTurn(options.subAgentTool)
+        : phasedTurn(options.subAgentTool);
+    const blocks = [
+        {
+            text: [
+                '<plan_mode>',
+                PREAMBLE,
+                '',
+                tools(options.allowedTools),
+                '',
+                turn,
+                '',
+                PRD_GUIDE,
+                '',
+                treeGuide(options.schemaUrl, options.allowedNodeKinds),
+                '',
+                ACTIONS,
+                '',
+                ENDING_A_TURN,
+            ].join('\n'),
+        },
+    ];
+    if (options.extra) {
+        blocks.push({
+            text: `\n## Additional instructions\n\n${options.extra}`,
+        });
+    }
+    if (state.prd) {
+        blocks.push({
+            text: `\n## Current PRD draft\n\n${state.prd}`,
+            drop: true,
+        });
+    }
+    if (state.planTree) {
+        blocks.push({
+            text: `\n## Current plan tree\n\n${JSON.stringify(state.planTree, null, 2)}`,
+            drop: true,
+        });
+    }
+    const summaries = workflowSummaries(state);
+    if (summaries) {
+        blocks.push({
+            text: `\n${summaries}`,
+            drop: true,
+        });
+    }
+    return fit(blocks, {
+        closingTag: '</plan_mode>',
+        maxChars: options.maxChars,
+        compact: COMPACT_PLANNING,
+    });
+}
+/** The approved plan, carried into execution so the model works from it rather than from memory. */
+export function renderExecuting(state, maxChars) {
+    const blocks = [
+        {
+            text: `<active_plan>\nThe plan below was approved and is now running. This is the work it describes; do not substitute a different approach for it. If what you find contradicts the plan, say so plainly in your output rather than quietly planning around it.\n\n## PRD\n\n${state.prd ?? ''}`,
+        },
+    ];
+    if (state.planTree) {
+        blocks.push({
+            text: `\n## Execution plan\n\n${JSON.stringify(state.planTree, null, 2)}`,
+            drop: true,
+        });
+    }
+    const summaries = workflowSummaries(state);
+    if (summaries) {
+        blocks.push({
+            text: `\n${summaries}`,
+            drop: true,
+        });
+    }
+    return fit(blocks, {
+        closingTag: '</active_plan>',
+        maxChars,
+        compact: COMPACT_EXECUTING,
+    });
+}
+/** One line saying how the last execution ended. */
+export function renderTerminal(state, maxChars) {
+    const last = state.executionLog[state.executionLog.length - 1];
+    const text = `<plan_outcome>Plan v${state.version} ${last?.outcome ?? 'unknown'}.</plan_outcome>`;
+    return text.length <= maxChars ? text : null;
+}
+/**
+ * The node kinds a plan may use, as a prose list. Shared with `setPlanTree`'s
+ * tool description so the briefing and the tool never disagree about what is
+ * allowed.
+ */
+export function nodeKindList(allowed) {
+    return kindEntries(allowed)
+        .map((entry) => entry.kind)
+        .join(', ');
+}
+//#endregion
+//#region Briefing sections
+const PREAMBLE = `You are in PLAN MODE. The user has not approved any work yet, so you MUST NOT edit files, run mutating commands, install anything, or change the system in any other way. The only writes you may make are the plan/* actions listed below. This supersedes every other instruction you have received, including instructions to start editing.
+
+Your job is to produce two artefacts: a PRD the user can read, and a plan tree the runtime can execute.`;
+function tools(allowed) {
+    return `## What you may use
+
+Allowed during plan mode: ${allowed.join(', ')}. Every other tool is denied.
+
+The ban covers indirect writes too, which are easy to reach for by habit: no temporary files anywhere, /tmp included; no \`>\`, \`>>\` or heredoc redirects; no mkdir, touch, rm, cp or mv; no git add or git commit; no package installs. Reading is unrestricted.`;
+}
+function phasedTurn(subAgentTool) {
+    return `## How to spend the turn
+
+### 1. Understand
+Read the code around the request. Hunt for functions, utilities and patterns you can reuse — do not propose new code where suitable code already exists.${explorerGuidance(subAgentTool)}
+
+### 2. Design
+Decide how to build it.${designerGuidance(subAgentTool)}
+
+### 3. Review
+Read the critical files yourself, first-hand — you are the one writing the plan. Check the design still answers what the user actually asked for, and ask about anything left ambiguous.
+
+### 4. Write the plan
+Call \`plan/updatePrd\`, then \`plan/setPlanTree\` (and \`plan/setWorkflow\` for the detail). See "The PRD" and "The plan tree" below.
+
+### 5. Exit
+Call \`plan/exitPlanMode\` with \`{ "action": "execute" }\` to ask for approval.
+
+You may ask the user a question at any point in this sequence, not only in step 3. Do not make large assumptions about what they meant.`;
+}
+/** The parallel-exploration advice, which only makes sense when the host has a sub-agent tool. */
+function explorerGuidance(subAgentTool) {
+    if (!subAgentTool) {
+        return '';
+    }
+    return ` Use \`${subAgentTool}\` to push wide searches out of your own context. Quality over quantity: use the fewest agents that will do — usually one — and never more than three. One agent is right when the request names its files or the change is small and targeted; reach for more only when the scope is uncertain or several areas of the codebase are involved. Give each agent a distinct area so their reports do not overlap.`;
+}
+function designerGuidance(subAgentTool) {
+    if (!subAgentTool) {
+        return ' Weigh the obvious alternatives and pick one. For a large or risky change, write down the trade-off you are making so the user can disagree with it.';
+    }
+    return ` Launch at least one \`${subAgentTool}\` planning agent for anything non-trivial — it validates your understanding and surfaces alternatives you did not consider. Skip it only for typo fixes, single-line changes and simple renames. Up to three in parallel, each with a different perspective, when the task touches several parts of the codebase or has many edge cases: simplicity vs. performance vs. maintainability for a feature; root cause vs. workaround vs. prevention for a bug; minimal change vs. clean architecture for a refactor.
+
+In the agent's prompt: give it the background you gathered, naming the files and the code paths you traced; state the requirements and constraints; ask for a detailed implementation plan that ends with a **Critical Files for Implementation** list of the 3–5 files most central to the work. You will read those files yourself in step 3, so the list is what makes the next step possible.`;
+}
+function interviewTurn(subAgentTool) {
+    const parallel = subAgentTool
+        ? ` Push wide searches out to \`${subAgentTool}\` when they would otherwise fill your context.`
+        : '';
+    return `## How to spend the turn
+
+You are pair-planning with the user. Explore, write down what you learn, and ask when the code cannot tell you. Repeat until the plan is complete.
+
+1. **Explore** — read code. Look for functions, utilities and patterns to reuse.${parallel}
+2. **Write it down** — call \`plan/updatePrd\` after each round of discovery. Do not save it all for the end; the PRD grows from a skeleton into the finished document.
+3. **Ask** — when you hit a decision the code cannot settle, call AskUserQuestion, then go back to step 1.
+
+Start by scanning a few key files, writing a skeleton PRD (headers and rough notes), and asking your first round of questions. Do not explore exhaustively before involving the user.
+
+**Asking well.** Never ask what you could find out by reading. Batch related questions into one call. Ask only about things the user owns: requirements, preferences, trade-offs, which edge cases matter. Scale the number of rounds to the request — a vague feature needs several, a focused bug fix may need none.
+
+**Converging.** The plan is ready when nothing is ambiguous and it says what changes, which files change, what existing code it reuses, and how to verify it. Then set the plan tree and call \`plan/exitPlanMode\` with \`{ "action": "execute" }\`.`;
+}
+const PRD_GUIDE = `## The PRD
+
+Write it with \`plan/updatePrd\` as markdown, structured with headers:
+
+- Open with **Context**: why this change is being made — the problem it solves and the outcome intended.
+- Give your recommended approach only. The alternatives you rejected are not the user's problem.
+- List the paths of the files to be modified.
+- Name the existing functions and utilities to reuse, with their paths.
+- Close with **Verification**: how to prove the change works end to end — the command to run, the tests to run, the tools to drive.
+
+Keep it scannable but executable. A reader should be able to skim the headers and know the shape of the work.`;
+/** One line per node kind, split into the work itself and the shape it runs in. */
+const KIND_ENTRIES = [
+    {
+        kind: 'llm',
+        group: 'leaf',
+        line: '`llm` — a model turn, driven by `instructions`; give it `tools` if it needs them',
+    },
+    {
+        kind: 'tool',
+        group: 'leaf',
+        line: '`tool` — one deterministic tool call: `toolName` plus `args`',
+    },
+    {
+        kind: 'run',
+        group: 'leaf',
+        line: '`run` — code in `execute`, run by a subprocess adapter the host must provide',
+    },
+    {
+        kind: 'claude-code',
+        group: 'leaf',
+        line: '`claude-code`, `codex`, `opencode`, `pi` — hand a `prompt` to a coding agent',
+    },
+    {
+        kind: 'sequence',
+        group: 'structure',
+        line: '`sequence` — `steps` run in order, each fed the one before',
+    },
+    {
+        kind: 'fork',
+        group: 'structure',
+        line: '`fork` — `paths` run at once (or `each` over a runtime array); `mode` is `all`, `race` or `settle`, and `merge` says how the outputs of an `all` come back together',
+    },
+    {
+        kind: 'branch',
+        group: 'structure',
+        line: '`branch` — the FIRST route whose `match` appears in the input wins, case-insensitively, so order the routes narrowest first; `default` catches the rest',
+    },
+    {
+        kind: 'loop',
+        group: 'structure',
+        line: '`loop` — run `body`, then repeat while the `until` predicate does not hold; the body always runs at least once',
+    },
+    {
+        kind: 'every',
+        group: 'structure',
+        line: '`every` — run `step` on an interval of `ms`, forever; nothing after it ever runs, so put it last',
+    },
+    {
+        kind: 'spawn',
+        group: 'structure',
+        line: '`spawn` — run `child` in an isolated context, so its work does not crowd this one',
+    },
+    {
+        kind: 'provide',
+        group: 'structure',
+        line: '`provide` — run `child` with a named set of memory layers the host must have registered',
+    },
+    {
+        kind: 'subflow',
+        group: 'structure',
+        line: '`subflow` — run a named workflow by `ref`',
+    },
+];
+/** The harness kinds share one line, so they are folded into the `claude-code` entry. */
+const HARNESS_KINDS = [
+    'claude-code',
+    'codex',
+    'opencode',
+    'pi',
+];
+function kindEntries(allowed) {
+    if (!allowed) {
+        return KIND_ENTRIES;
+    }
+    const permitted = new Set(allowed);
+    return KIND_ENTRIES.filter((entry) => entry.kind === 'claude-code'
+        ? HARNESS_KINDS.some((kind) => permitted.has(kind))
+        : permitted.has(entry.kind));
+}
+function treeGuide(schemaUrl, allowed) {
+    const entries = kindEntries(allowed);
+    const group = (name) => entries.filter((entry) => entry.group === name).map((entry) => `- ${entry.line}`);
+    const leaves = group('leaf');
+    const structure = group('structure');
+    const restricted = allowed
+        ? '\n\nThis plan is restricted to the kinds listed above. Any other kind is rejected.'
+        : '';
+    return `## The plan tree
+
+Set it with \`plan/setPlanTree\` as \`{ "document": { "version": 1, "root": <node> } }\`, conforming to ${schemaUrl}. Every node needs a unique \`id\` and a \`kind\`.${restricted}
+
+**Leaves — the work itself**
+${leaves.join('\n')}
+
+**Structure — how the leaves are arranged**
+${structure.join('\n')}
+
+**Shaping it**
+- Keep the tree the user reviews SMALL — about seven top-level nodes, readable at a glance. Push the mechanics down.
+- Factor detail into named workflows: define each with \`plan/setWorkflow\` \`{ "name": "<slug>", "document": {...} }\` and point at it with \`{ "kind": "subflow", "id": "...", "ref": "<slug>" }\`. Named workflows may reference each other but must not form a cycle, and every ref must resolve or the exit is rejected.
+- Fork work that is genuinely independent; sequence work where one step needs the last one's output. Do not fork for the look of it.
+- Prefer \`tool\` over \`llm\` wherever the step is deterministic. A model turn that always does the same thing is a slow, expensive tool call.
+- Always give a \`loop\` a \`maxIterations\`. Without one it stops at a hard ceiling of 1000 and fails the step.`;
+}
+const ACTIONS = `## Actions
+
+- \`plan/updatePrd\` — set the PRD markdown
+- \`plan/setPlanTree\` — set the plan tree
+- \`plan/setWorkflow\` — create or replace a named workflow
+- \`plan/removeWorkflow\` — delete a named workflow
+- \`plan/getWorkflow\` — read a named workflow back before revising it
+- \`plan/exitPlanMode\` \`{ "action": "execute" }\` — ask the user to approve the plan
+- \`plan/exitPlanMode\` \`{ "action": "cancel" }\` — discard the plan and leave plan mode`;
+const ENDING_A_TURN = `## Ending your turn
+
+End every turn one of two ways: AskUserQuestion, or \`plan/exitPlanMode\`. Nothing else.
+
+Asking for approval IS \`plan/exitPlanMode\` — that is what the action does. Never ask for it in prose or through AskUserQuestion. "Does this plan look right?", "Shall I proceed?", "Any changes before I start?" all mean you should have called \`plan/exitPlanMode\`. Use AskUserQuestion only to settle requirements or choose between approaches.
+
+If the user rejects the plan you stay in plan mode: take their feedback, revise, and exit again.`;
+/**
+ * What the model gets when the full briefing will not fit. Every clause here is
+ * load-bearing: the restriction, where to put the plan, and how to end the turn.
+ */
+const COMPACT_PLANNING = `<plan_mode>
+PLAN MODE: read-only. No edits, no mutating commands, no installs — plan/* actions are your only writes, and this supersedes any instruction to start editing.
+Write the PRD with plan/updatePrd and the tree with plan/setPlanTree, then call plan/exitPlanMode {"action":"execute"} to ask for approval. Never ask in prose.
+</plan_mode>`;
+const COMPACT_EXECUTING = `<active_plan>
+An approved plan is running. Follow it; if what you find contradicts it, say so rather than silently taking a different approach.
+</active_plan>`;
+//#endregion
+//#region Helpers
+/** One-line summary of a workflow: node count and a kind histogram. */
+function summarizeWorkflow(name, doc) {
+    const counts = new Map();
+    let total = 0;
+    for (const node of walkWorkflow(doc.root)) {
+        total++;
+        counts.set(node.kind, (counts.get(node.kind) ?? 0) + 1);
+    }
+    const histogram = [
+        ...counts.entries(),
+    ]
+        .map(([kind, n]) => `${kind} x${n}`)
+        .join(', ');
+    return `- ${name}: ${total} node${total === 1 ? '' : 's'} (${histogram})`;
+}
+function workflowSummaries(state) {
+    const entries = Object.entries(state.workflows).sort(([a], [b]) => a.localeCompare(b));
+    if (entries.length === 0) {
+        return null;
+    }
+    return [
+        '## Named workflows',
+        '',
+        ...entries.map(([name, doc]) => summarizeWorkflow(name, doc)),
+        '',
+        "(Read a workflow's JSON with plan/getWorkflow before revising it.)",
+    ].join('\n');
+}
+/** Below this, a trimmed state block is a stub the model cannot use, so it goes entirely. */
+const MIN_USEFUL_BLOCK = 400;
+const TRIM_MARK = '\n…(trimmed to fit the context budget)';
+/**
+ * Joins the blocks under a character budget.
+ *
+ * State blocks give way first, fattest first, and are trimmed to whatever
+ * headroom is left rather than dropped whole — a truncated PRD draft is worth
+ * far more than the blank space dropping it leaves behind. Rules are never cut
+ * mid-sentence: if they do not fit, the compact briefing replaces the lot, and
+ * if even that overflows the layer says nothing at all.
+ */
+function fit(blocks, into) {
+    const { closingTag, maxChars, compact } = into;
+    const tail = `\n${closingTag}`;
+    if (maxChars < tail.length) {
+        return null;
+    }
+    const budget = maxChars - tail.length;
+    const kept = [
+        ...blocks,
+    ];
+    const total = () => kept.reduce((sum, block) => sum + block.text.length, 0);
+    while (total() > budget) {
+        const fattest = fattestDroppable(kept);
+        if (fattest < 0) {
+            return compact.length <= maxChars ? compact : null;
+        }
+        const block = kept[fattest];
+        const headroom = budget - (total() - block.text.length);
+        if (headroom >= MIN_USEFUL_BLOCK) {
+            block.text = `${truncate(block.text, headroom - TRIM_MARK.length)}${TRIM_MARK}`;
+            break;
+        }
+        kept.splice(fattest, 1);
+    }
+    return `${kept.map((block) => block.text).join('')}${tail}`;
+}
+function fattestDroppable(blocks) {
+    let fattest = -1;
+    for (const [index, block] of blocks.entries()) {
+        if (block.drop && (fattest < 0 || block.text.length > blocks[fattest].text.length)) {
+            fattest = index;
+        }
+    }
+    return fattest;
+}
+/** Cuts to `max` characters without splitting a surrogate pair in half. */
+function truncate(text, max) {
+    if (text.length <= max) {
+        return text;
+    }
+    const code = text.charCodeAt(max - 1);
+    const isHighSurrogate = code >= 0xd800 && code <= 0xdbff;
+    return text.slice(0, isHighSurrogate ? max - 1 : max);
+}
+//#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/context",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "description": "Context layer system for Noetic agents: the ContextLayer contract, lifecycle, budget/projection machinery, and built-in layer implementations.",
   "license": "Apache-2.0",
@@ -44,7 +44,7 @@
     "zod": "^4.0.0"
   },
   "dependencies": {
-    "@noetic-tools/types": "^2.3.0",
+    "@noetic-tools/types": "^3.0.0",
     "zod": "^4.0.0"
   },
   "scripts": {