@noetic-tools/types 0.1.1 → 0.2.0

package/dist/types/context.d.ts

@@ -8,7 +8,7 @@ import type { DetachedHandle } from './detached.js';
 import type { FsAdapter } from './fs-adapter.js';
 import type { HarnessResponse, StreamEvent, StreamingItem } from './harness-result.js';
 import type { ExecuteInput } from './items.js';
-import type { ContextMemory, MemoryLayer, StorageAdapter } from './memory.js';
+import type { ContextMemory, MemoryLayer, ProjectionPolicy, StorageAdapter } from './memory.js';
 import type { Span } from './observability.js';
 import type { ShellAdapter } from './shell-adapter.js';
 import type { SteeringDecision } from './steering.js';
@@ -98,6 +98,8 @@ export interface ContextHarness {
     readonly config: {
         readonly name: string;
         readonly params: Record<string, unknown>;
+        /** Harness-wide default projection policy; a step's `projection` overrides it. */
+        readonly projection?: ProjectionPolicy;
     };
     readonly fs: FsAdapter;
     readonly shell: ShellAdapter;
@@ -128,6 +130,8 @@ export interface ContextHarness {
     afterModelCall(layers: MemoryLayer[], response: LLMResponse, ctx: Context): Promise<SteeringDecision>;
     runAppendPipeline(layers: MemoryLayer[], items: import('./items.js').Item[], ctx: Context): Promise<ContextAppendPipelineResult>;
     recallLayers(layers: MemoryLayer[], input: string, ctx: Context): Promise<ContextRecallLayerOutput[]>;
+    recallLayersAtomic(layers: MemoryLayer[], input: string, ctx: Context, budgets: Map<string, number>): Promise<ContextRecallLayerOutput[]>;
+    recallLayersEventual(layers: MemoryLayer[], input: string, ctx: Context, budgets: Map<string, number>): Promise<ContextRecallLayerOutput[]>;
     projectHistory(layers: MemoryLayer[], items: ReadonlyArray<import('./items.js').Item>, ctx: Context): Promise<ReadonlyArray<import('./items.js').Item>>;
     storeLayers(layers: MemoryLayer[], response: LLMResponse, ctx: Context): Promise<void>;
     previewRequestItems(scope?: unknown): Promise<ReadonlyArray<import('./items.js').Item>>;

package/dist/types/memory.d.ts

@@ -288,6 +288,26 @@ export interface MemoryLayer<TState = unknown> {
     hooks: MemoryHooks<TState>;
     /** Per-hook timeout overrides in ms. */
     timeouts?: Partial<LayerTimeouts>;
+    /**
+     * What to do when this layer's `init` hook throws.
+     * - `'throw'` (default): surface the error and abort the execution — memory is
+     *   load-bearing, and silent disabling hides failures (and, for the steering
+     *   layer, would fail *open*).
+     * - `'disable'`: log a diagnostic and run the execution without this layer
+     *   (its `recall`/`store`/etc. are skipped). Opt in only for non-critical layers.
+     */
+    onInitError?: 'throw' | 'disable';
+    /**
+     * Recall mode controlling whether this layer's `recall()` blocks the model call.
+     * - `'atomic'` (default): recall runs synchronously in the hot path; the
+     *   harness waits for it before assembling the view.
+     * - `'eventual'`: recall is served from cache and never blocks; the cache
+     *   refreshes after `store()` produces new state, so the next turn sees it.
+     *
+     * A harness configured with `forceAtomicRecall` treats every layer as atomic,
+     * ignoring this field.
+     */
+    recallMode?: 'atomic' | 'eventual';
     /** Typed functions and data exposed to code steps via `ctx.memory['layerId']` and automatically as LLM tools. */
     provides?: LayerProvides;
     /** Optional item schemas contributed by this layer, primarily for developer-role memory items. */

package/dist/types/runtime.d.ts

@@ -6,7 +6,7 @@ import type { DetachedHandle } from './detached.js';
 import type { FsAdapter } from './fs-adapter.js';
 import type { HarnessResponse, StreamEvent, StreamingItem } from './harness-result.js';
 import type { ExecuteInput, Item, ItemSchemaExtensions } from './items.js';
-import type { ContextMemory, MemoryLayer, StorageAdapter } from './memory.js';
+import type { ContextMemory, MemoryLayer, ProjectionPolicy, StorageAdapter } from './memory.js';
 import type { Span } from './observability.js';
 import type { ShellAdapter } from './shell-adapter.js';
 import type { SteeringDecision } from './steering.js';
@@ -28,6 +28,10 @@ export interface AgentConfig<TParams extends Record<string, unknown> = Record<st
     itemSchemas?: ItemSchemaExtensions;
     /** Whether unknown extension item types must match a registered schema. Defaults to true. */
     strictItemSchemas?: boolean;
+    /** Default projection policy for all LLM steps. Individual steps override via `step.projection`. */
+    projection?: ProjectionPolicy;
+    /** When true, every layer is recalled atomically regardless of its `recallMode` (no eventual/cached recall). */
+    forceAtomicRecall?: boolean;
 }
 /** @public How a message submitted during an active turn is delivered to the model.
  *
@@ -199,6 +203,10 @@ export interface AgentHarnessContract<TParams extends Record<string, unknown> =
     getChannelHandle<T>(channel: ExternalChannel<T>, executionId: string): ChannelHandle<T>;
     initLayers(layers: MemoryLayer[], ctx: Context, storage: StorageAdapter): Promise<void>;
     recallLayers(layers: MemoryLayer[], input: string, ctx: Context): Promise<RecallLayerOutput[]>;
+    /** Recall only atomic layers (or all layers when the harness forces atomic recall). Blocks until complete. */
+    recallLayersAtomic(layers: MemoryLayer[], input: string, ctx: Context, budgets: Map<string, number>): Promise<RecallLayerOutput[]>;
+    /** Recall eventual layers from cache (non-blocking); returns nothing when the harness forces atomic recall. */
+    recallLayersEventual(layers: MemoryLayer[], input: string, ctx: Context, budgets: Map<string, number>): Promise<RecallLayerOutput[]>;
     /**
      * Compute the items that would be sent to the model on the next turn for a
      * session — its accumulated history plus the harness's memory-layer recall

package/dist/types/step.d.ts

@@ -3,7 +3,7 @@ import type { Channel } from './channel.js';
 import type { ModelParams, RetryPolicy, StepMeta } from './common.js';
 import type { Context } from './context.js';
 import type { NoeticError } from './error.js';
-import type { ContextMemory, MemoryConfig, MemoryLayer } from './memory.js';
+import type { ContextMemory, MemoryConfig, MemoryLayer, ProjectionPolicy } from './memory.js';
 import type { SubprocessAdapter } from './subprocess-adapter.js';
 import type { Tool } from './tool.js';
 /**
@@ -99,6 +99,8 @@ export interface StepLLM<TMemory = ContextMemory, _I = unknown, O = unknown> {
     params?: ModelParams;
     /** Controls framework event emission for this step. Defaults to `true`. Set `false` to suppress all framework events. A filter function receives `(eventType, data)` and returns `boolean`. */
     emit?: boolean | ((eventType: string, data: Record<string, unknown>) => boolean);
+    /** Projection policy for this step's context window. Overrides the harness-level default. */
+    projection?: ProjectionPolicy;
 }
 /** @public A step that invokes a single tool directly, bypassing the LLM. */
 export interface StepTool<_TMemory = ContextMemory, I = unknown, O = unknown> {

package/dist/util/message-helpers.d.ts

@@ -9,6 +9,22 @@ export declare function isOutputText(part: {
     type: 'output_text';
     text: string;
 };
+/** True for any content part carrying a string `text` field (input_text, output_text, …). */
+export declare function isTextPart(part: {
+    type: string;
+}): part is {
+    type: string;
+    text: string;
+};
+/** Extracts assistant/output text from items for memory buffering (one string per message). */
+export declare function collectOutputText(items: ReadonlyArray<Item>): string[];
+/**
+ * Extracts text from INPUT items for memory buffering: concatenates the text
+ * content parts of message items (user `input_text` and any text parts) and
+ * appends the `output` of `function_call_output` (tool result) items. Empty
+ * strings are dropped.
+ */
+export declare function collectInputText(items: ReadonlyArray<Item>): string[];
 export declare function createMessage(text: string, role: 'user' | 'developer'): InputMessageItem;
 export declare function extractAssistantText(items: ReadonlyArray<Item>): string;
 /** Naive token estimate: ~4 chars per token */

package/dist/util/message-helpers.js

@@ -21,6 +21,47 @@ export function isUserMessage(item) {
 export function isOutputText(part) {
     return part.type === 'output_text';
 }
+/** True for any content part carrying a string `text` field (input_text, output_text, …). */
+export function isTextPart(part) {
+    return 'text' in part && typeof part.text === 'string';
+}
+/** Extracts assistant/output text from items for memory buffering (one string per message). */
+export function collectOutputText(items) {
+    return items
+        .filter((i) => i.type === 'message')
+        .map((i) => i.content
+        .filter(isOutputText)
+        .map((c) => c.text)
+        .join(''))
+        .filter((t) => t.length > 0);
+}
+/**
+ * Extracts text from INPUT items for memory buffering: concatenates the text
+ * content parts of message items (user `input_text` and any text parts) and
+ * appends the `output` of `function_call_output` (tool result) items. Empty
+ * strings are dropped.
+ */
+export function collectInputText(items) {
+    const texts = [];
+    for (const item of items) {
+        if (item.type === 'message') {
+            let text = '';
+            for (const part of item.content) {
+                if (isTextPart(part)) {
+                    text += part.text;
+                }
+            }
+            if (text.length > 0) {
+                texts.push(text);
+            }
+            continue;
+        }
+        if (item.type === 'function_call_output' && item.output.length > 0) {
+            texts.push(item.output);
+        }
+    }
+    return texts;
+}
 export function createMessage(text, role) {
     return {
         id: crypto.randomUUID(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/types",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "description": "Foundational type contracts and primitives shared across the Noetic framework (items, LLM config, adapters, steering, errors).",
   "license": "Apache-2.0",