@noetic-tools/context 1.2.0 → 1.2.2

package/README.md

@@ -11,9 +11,8 @@ provides:
 - The **lifecycle, budget, and projection machinery** that converges layer
   outputs into the assembled LLM context (`assembleView`, `allocateBudgets`,
   layer state stores, scoping).
-- The **built-in layers**: working memory, history window, observational
-  context, plan, temporal, steering, file reference, static content, durable
-  task state, and the tool context layer.
+- The **built-in layers**: instructions, history, scratchpad, observations,
+  temporal, filesystem, plan, task state, tool calls, and steering.
 
 It depends only on [`@noetic-tools/types`](https://www.npmjs.com/package/@noetic-tools/types).
 [`@noetic-tools/core`](https://www.npmjs.com/package/@noetic-tools/core) builds

package/dist/context/layer-provides.d.ts

@@ -21,7 +21,7 @@ export declare function layerData<T, TState>(opts: {
  * @param opts.execute - Async function receiving args, current state, and execution context.
  * @returns A `LayerFunctionDecl` to include in a layer's `provides`.
  */
-export declare function layerFn<TInput, TOutput, TState>(opts: {
+export declare function layerFunction<TInput, TOutput, TState>(opts: {
     description: string;
     input: ZodType<TInput>;
     output: ZodType<TOutput>;

package/dist/context/layer-provides.js

@@ -22,7 +22,7 @@ export function layerData(opts) {
  * @param opts.execute - Async function receiving args, current state, and execution context.
  * @returns A `LayerFunctionDecl` to include in a layer's `provides`.
  */
-export function layerFn(opts) {
+export function layerFunction(opts) {
     return {
         kind: 'function',
         description: opts.description,

package/dist/context/layers/{file-reference.d.ts → filesystem.d.ts}

@@ -51,5 +51,5 @@ interface FileReferenceOptions {
  *
  * @public
  */
-export declare function fileReference(opts?: FileReferenceOptions): ContextLayer<FileReferenceState>;
+export declare function filesystem(opts?: FileReferenceOptions): ContextLayer<FileReferenceState>;
 export {};

package/dist/context/layers/{file-reference.js → filesystem.js}

@@ -757,11 +757,11 @@ async function renderFileReferenceDelta({ prev, next, }) {
  *
  * @public
  */
-export function fileReference(opts) {
+export function filesystem(opts) {
     const runtime = createFileReferenceRuntime(opts);
     return {
-        id: 'file-reference',
-        name: 'File Reference',
+        id: 'filesystem',
+        name: 'Filesystem',
         slot: runtime.slot,
         scope: 'thread',
         budget: 'auto',

package/dist/context/layers/{history-window.d.ts → history.d.ts}

@@ -15,17 +15,17 @@
  *      slice boundary via `stripUnresolvedToolCalls`.
  */
 import type { ContextLayer } from '@noetic-tools/types';
-/** @public Configuration for the {@link historyWindow} layer. */
-export interface HistoryWindowConfig {
+/** @public Configuration for the {@link history} layer. */
+export interface HistoryConfig {
     /** Cap on the number of trailing items projected to the LLM. Defaults to 40. */
     maxItems?: number;
 }
 /**
- * Creates a history-window context layer that caps the trailing items projected
+ * Creates a history context layer that caps the trailing items projected
  * to the LLM. Storage stays unbounded; only the wire payload is narrowed.
  *
  * @public
  * @param config - Optional `{ maxItems }`. Defaults to 40.
  * @returns A `ContextLayer` that contributes only a `projectHistory` hook.
  */
-export declare function historyWindow(config?: HistoryWindowConfig): ContextLayer<null>;
+export declare function history(config?: HistoryConfig): ContextLayer<null>;

package/dist/context/layers/{history-window.js → history.js}

@@ -32,8 +32,8 @@ const ANCHOR_SCAN_LIMIT = 4;
 function validateMaxItems(value) {
     if (!Number.isInteger(value) || value < MIN_MAX_ITEMS || value > MAX_MAX_ITEMS) {
         throw new NoeticConfigError({
-            code: 'INVALID_HISTORY_WINDOW_MAX_ITEMS',
-            message: `historyWindow: maxItems must be an integer in [${MIN_MAX_ITEMS}, ${MAX_MAX_ITEMS}], got ${value}`,
+            code: 'INVALID_HISTORY_MAX_ITEMS',
+            message: `history: maxItems must be an integer in [${MIN_MAX_ITEMS}, ${MAX_MAX_ITEMS}], got ${value}`,
             hint: 'Pass a sensible cap such as { maxItems: 40 }, or omit the layer to keep history uncapped.',
         });
     }
@@ -94,19 +94,19 @@ function findHeadAnchor(items, windowStart) {
 //#endregion
 //#region Public API
 /**
- * Creates a history-window context layer that caps the trailing items projected
+ * Creates a history context layer that caps the trailing items projected
  * to the LLM. Storage stays unbounded; only the wire payload is narrowed.
  *
  * @public
  * @param config - Optional `{ maxItems }`. Defaults to 40.
  * @returns A `ContextLayer` that contributes only a `projectHistory` hook.
  */
-export function historyWindow(config) {
+export function history(config) {
     const maxItems = config?.maxItems ?? DEFAULT_MAX_ITEMS;
     validateMaxItems(maxItems);
     return {
-        id: 'history-window',
-        name: 'History Window',
+        id: 'history',
+        name: 'History',
         slot: HISTORY_WINDOW_SLOT,
         scope: 'execution',
         hooks: {

package/dist/context/layers/{static-content.d.ts → instructions.d.ts}

@@ -1,5 +1,5 @@
 import type { ContextScope } from '@noetic-tools/types';
-interface StaticContentOpts {
+interface InstructionsOptions {
     id?: string;
     slot?: number;
     scope?: ContextScope;
@@ -13,7 +13,7 @@ interface StaticContentOpts {
  * @param opts - Configuration with a `load` function and optional id, slot, scope, and XML tag name.
  * @returns A `ContextLayer` that provides static instructional content to the model.
  */
-export declare function staticContent(opts: StaticContentOpts): {
+export declare function instructions(opts: InstructionsOptions): {
     id: string;
     slot: number;
     scope: ContextScope;

package/dist/context/layers/{static-content.js → instructions.js}

@@ -6,10 +6,10 @@ import { estimateTokens, Slot } from '@noetic-tools/types';
  * @param opts - Configuration with a `load` function and optional id, slot, scope, and XML tag name.
  * @returns A `ContextLayer` that provides static instructional content to the model.
  */
-export function staticContent(opts) {
+export function instructions(opts) {
     const tag = opts.tag ?? 'instructions';
     return {
-        id: opts.id ?? 'static-content',
+        id: opts.id ?? 'instructions',
         slot: opts.slot ?? Slot.WORKING_MEMORY + 5,
         scope: opts.scope ?? 'resource',
         // Loaded once in `init` and never rewritten, so it can be pinned outright

package/dist/context/layers/{observational-context.d.ts → observations.d.ts}

@@ -1,11 +1,11 @@
-export interface ObservationalState {
+export interface ObservationsState {
     observations: string[];
     buffer: string[];
     bufferTokens: number;
     version: number;
 }
 export type ObserverFn = (buffer: string[]) => Promise<string[]>;
-export interface ObservationalContextConfig {
+export interface ObservationsConfig {
     bufferThreshold?: number;
     maxObservations?: number;
     scope?: 'thread' | 'resource';
@@ -18,8 +18,8 @@ export interface ObservationalContextConfig {
  * @param config - Optional configuration for buffer threshold, max observations, scope, and observer function.
  * @returns A `ContextLayer` that accumulates and summarizes observations over time.
  */
-export declare function observationalContext(config?: ObservationalContextConfig): {
-    id: 'observational-context';
+export declare function observations(config?: ObservationsConfig): {
+    id: 'observations';
     name: string;
     slot: 200;
     scope: "resource" | "thread";
@@ -33,24 +33,24 @@ export declare function observationalContext(config?: ObservationalContextConfig
     };
     hooks: {
         init({ storage }: import("@noetic-tools/types").InitParams): Promise<{
-            state: ObservationalState;
+            state: ObservationsState;
         }>;
-        recall({ state, budget }: import("@noetic-tools/types").RecallParams<ObservationalState>): Promise<{
+        recall({ state, budget }: import("@noetic-tools/types").RecallParams<ObservationsState>): Promise<{
             items: import("@noetic-tools/types").InputMessageItem[];
             tokenCount: number;
         } | null>;
-        store({ newItems, state }: import("@noetic-tools/types").StoreParams<ObservationalState>): Promise<{
-            state: ObservationalState;
+        store({ newItems, state }: import("@noetic-tools/types").StoreParams<ObservationsState>): Promise<{
+            state: ObservationsState;
         }>;
-        onItemAppend({ items, state }: import("@noetic-tools/types").OnItemAppendParams<ObservationalState>): Promise<{
+        onItemAppend({ items, state }: import("@noetic-tools/types").OnItemAppendParams<ObservationsState>): Promise<{
             items: import("@noetic-tools/types").Item[];
             state?: undefined;
         } | {
             items: import("@noetic-tools/types").Item[];
-            state: ObservationalState;
+            state: ObservationsState;
         }>;
-        onSpawn({ parentState }: import("@noetic-tools/types").SpawnParams<ObservationalState>): Promise<{
-            childState: ObservationalState;
+        onSpawn({ parentState }: import("@noetic-tools/types").SpawnParams<ObservationsState>): Promise<{
+            childState: ObservationsState;
         }>;
     };
 };

package/dist/context/layers/{observational-context.js → observations.js}

@@ -1,7 +1,7 @@
 import { collectInputText, collectOutputText, createMessage, estimateTokens, Slot, } from '@noetic-tools/types';
 const DEFAULT_BUFFER_THRESHOLD_TOKENS = 2_000;
 const DEFAULT_MAX_OBSERVATIONS = 50;
-function emptyObservationalState() {
+function emptyObservationsState() {
     return {
         observations: [],
         buffer: [],
@@ -70,13 +70,13 @@ function renderObservationsWithinBudget(observations, budget) {
  * @param config - Optional configuration for buffer threshold, max observations, scope, and observer function.
  * @returns A `ContextLayer` that accumulates and summarizes observations over time.
  */
-export function observationalContext(config) {
+export function observations(config) {
     const maxObs = config?.maxObservations ?? DEFAULT_MAX_OBSERVATIONS;
     const threshold = config?.bufferThreshold ?? DEFAULT_BUFFER_THRESHOLD_TOKENS;
     const observer = config?.observer;
     return {
-        id: 'observational-context',
-        name: 'Observational Context',
+        id: 'observations',
+        name: 'Observations',
         slot: Slot.OBSERVATIONS,
         scope: config?.scope ?? 'resource',
         budget: {
@@ -93,7 +93,7 @@ export function observationalContext(config) {
             async init({ storage }) {
                 const saved = await storage.get('state');
                 return {
-                    state: saved ?? emptyObservationalState(),
+                    state: saved ?? emptyObservationsState(),
                 };
             },
             async recall({ state, budget }) {
@@ -114,7 +114,7 @@ export function observationalContext(config) {
             },
             // Captures assistant output text.
             async store({ newItems, state }) {
-                const s = state ?? emptyObservationalState();
+                const s = state ?? emptyObservationsState();
                 const texts = collectOutputText(newItems);
                 return {
                     state: await accumulate(s, texts, {
@@ -126,7 +126,7 @@ export function observationalContext(config) {
             },
             // Captures user input and tool output text (pass-through; no transform).
             async onItemAppend({ items, state }) {
-                const s = state ?? emptyObservationalState();
+                const s = state ?? emptyObservationsState();
                 const texts = collectInputText(items);
                 if (texts.length === 0) {
                     return {

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

@@ -13,7 +13,7 @@
  * one runs for a given phase.
  */
 import type { WorkflowNode } from '@noetic-tools/types';
-import type { PlanState } from './plan-context.js';
+import type { PlanState } from './plan-state.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. */

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

@@ -203,24 +203,24 @@ Keep it scannable but executable. A reader should be able to skim the headers an
 /** One line per node kind, split into the work itself and the shape it runs in. */
 const KIND_ENTRIES = [
     {
-        kind: 'llm',
+        kind: 'callModel',
         group: 'leaf',
-        line: '`llm` — a model turn, driven by `instructions`; give it `tools` if it needs them',
+        line: '`callModel` — a model turn, driven by `instructions`; give it `tools` if it needs them',
     },
     {
-        kind: 'tool',
+        kind: 'invokeTool',
         group: 'leaf',
-        line: '`tool` — one deterministic tool call: `toolName` plus `args`',
+        line: '`invokeTool` — one deterministic tool call: `toolName` plus `args`',
     },
     {
-        kind: 'run',
+        kind: 'runCode',
         group: 'leaf',
-        line: '`run` — code in `execute`, run by a subprocess adapter the host must provide',
+        line: '`runCode` — code in `execute`, run by a subprocess adapter the host must provide',
     },
     {
-        kind: 'claude-code',
+        kind: 'acp-agent',
         group: 'leaf',
-        line: '`claude-code`, `codex`, `opencode`, `pi` — hand a `prompt` to a coding agent',
+        line: '`acp-agent` — hand a `prompt` to an external coding agent named by `agent` (e.g. `claude-code`, `codex`, `gemini`)',
     },
     {
         kind: 'sequence',
@@ -228,14 +228,14 @@ const KIND_ENTRIES = [
         line: '`sequence` — `steps` run in order, each fed the one before',
     },
     {
-        kind: 'fork',
+        kind: 'inParallel',
         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',
+        line: '`inParallel` — `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',
+        kind: 'conditional',
         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',
+        line: '`conditional` — the FIRST route whose `match` appears in the input wins, case-insensitively, so order the routes narrowest first; `default` catches the rest',
     },
     {
         kind: 'loop',
@@ -243,9 +243,9 @@ const KIND_ENTRIES = [
         line: '`loop` — run `body`, then repeat while the `until` predicate does not hold; the body always runs at least once',
     },
     {
-        kind: 'every',
+        kind: 'schedule',
         group: 'structure',
-        line: '`every` — run `step` on an interval of `ms`, forever; nothing after it ever runs, so put it last',
+        line: '`schedule` — run `step` on an `interval`, forever; nothing after it ever runs, so put it last',
     },
     {
         kind: 'spawn',
@@ -253,9 +253,9 @@ const KIND_ENTRIES = [
         line: '`spawn` — run `child` in an isolated context, so its work does not crowd this one',
     },
     {
-        kind: 'provide',
+        kind: 'withContext',
         group: 'structure',
-        line: '`provide` — run `child` with a named set of memory layers the host must have registered',
+        line: '`withContext` — run `child` with a named set of context layers the host must have registered',
     },
     {
         kind: 'subflow',
@@ -263,21 +263,12 @@ const KIND_ENTRIES = [
         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));
+    return KIND_ENTRIES.filter((entry) => permitted.has(entry.kind));
 }
 function treeGuide(schemaUrl, allowed) {
     const entries = kindEntries(allowed);
@@ -300,8 +291,8 @@ ${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.
+- Fan out work that is genuinely independent; sequence work where one step needs the last one's output. Do not fan out for the look of it.
+- Prefer \`invokeTool\` over \`callModel\` 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

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

@@ -0,0 +1,31 @@
+import type { WorkflowDocument } from '@noetic-tools/types';
+/**
+ * Persisted state shared by the plan layer (`plan.ts`) and its prompt
+ * renderers (`plan-prompts.ts`). Lives in its own leaf module so the two can
+ * both depend on it without importing each other.
+ */
+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;
+    /** The reviewed plan: a complete JSON workflow document. */
+    planTree: WorkflowDocument | null;
+    /** Named workflows referenced from the tree via `{ kind: 'subflow', ref }` nodes. */
+    workflows: Record<string, WorkflowDocument>;
+    executionLog: PlanExecutionEntry[];
+    version: number;
+    /** Identifier of the on-disk plan session (set by `onEnterSession` host callback). */
+    planSlug?: string | null;
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Persisted state shared by the plan layer (`plan.ts`) and its prompt
+ * renderers (`plan-prompts.ts`). Lives in its own leaf module so the two can
+ * both depend on it without importing each other.
+ */
+export const PlanPhase = {
+    Idle: 'idle',
+    Planning: 'planning',
+    Executing: 'executing',
+    Completed: 'completed',
+    Failed: 'failed',
+};

package/dist/context/layers/{plan-context.d.ts → plan.d.ts}

@@ -1,31 +1,9 @@
-import type { ContextLayer, ContextScope, WorkflowDocument, WorkflowNode } from '@noetic-tools/types';
+import type { ContextLayer, ContextScope, WorkflowNode } from '@noetic-tools/types';
 import { PlanStyle } from './plan-prompts.js';
+import type { PlanState } from './plan-state.js';
 export { PlanStyle } from './plan-prompts.js';
-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;
-    /** The reviewed plan: a complete JSON workflow document. */
-    planTree: WorkflowDocument | null;
-    /** Named workflows referenced from the tree via `{ kind: 'subflow', ref }` nodes. */
-    workflows: Record<string, WorkflowDocument>;
-    executionLog: PlanExecutionEntry[];
-    version: number;
-    /** Identifier of the on-disk plan session (set by `onEnterSession` host callback). */
-    planSlug?: string | null;
-}
+export type { PlanExecutionEntry, PlanState } from './plan-state.js';
+export { PlanPhase } from './plan-state.js';
 /** 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;
@@ -37,7 +15,7 @@ export type PlanEnterSessionCallback = () => Promise<{
 export type PlanExitCallback = (state: PlanState) => Promise<{
     approved: boolean;
 }>;
-export interface PlanContextConfig {
+export interface PlanConfig {
     scope?: ContextScope;
     additionalAllowedTools?: string[];
     maxPrdLength?: number;
@@ -86,4 +64,4 @@ export interface PlanContextConfig {
  * @param config - Optional configuration for scope, allowed tools, and limits.
  * @returns A `ContextLayer` providing plan mode, PRD storage, and execution tracking.
  */
-export declare function planContext(config?: PlanContextConfig): ContextLayer<PlanState>;
+export declare function plan(config?: PlanConfig): ContextLayer<PlanState>;