@noetic-tools/types 3.1.0 → 3.2.1

package/README.md

@@ -8,14 +8,14 @@ on: the conversation `Item` data model, LLM configuration (`LlmProviderConfig`,
 platform adapter interfaces (`FsAdapter`, `ShellAdapter`, `SubprocessAdapter`),
 the error model, and the `Item` schema.
 
-It is consumed by [`@noetic-tools/memory`](https://www.npmjs.com/package/@noetic-tools/memory)
+It is consumed by [`@noetic-tools/context`](https://www.npmjs.com/package/@noetic-tools/context)
 and [`@noetic-tools/core`](https://www.npmjs.com/package/@noetic-tools/core),
 both of which re-export the parts relevant to their public surface. Application
 code normally imports these types from `@noetic-tools/core` rather than from
 this package directly.
 
-The `MemoryLayer` contract is additionally exported at the
-`@noetic-tools/types/contract` subpath for memory-layer authors who want the
+The `ContextLayer` contract is additionally exported at the
+`@noetic-tools/types/contract` subpath for context-layer authors who want the
 contract without the rest of the vocabulary.
 
 ## License

package/dist/errors/noetic-error.js

@@ -43,12 +43,12 @@ function formatMessage(error) {
     switch (error.kind) {
         case 'step_failed':
             return `Step '${error.stepId}' failed: ${error.cause.message}`;
-        case 'llm_refused':
-            return `LLM refused at step '${error.stepId}': ${error.refusal}`;
-        case 'llm_parse_error':
-            return `LLM parse error at step '${error.stepId}': failed to parse output`;
-        case 'llm_rate_limit':
-            return `LLM rate limited at step '${error.stepId}'${error.retryAfter ? ` (retry after ${error.retryAfter}ms)` : ''}`;
+        case 'model_refused':
+            return `Model refused at step '${error.stepId}': ${error.refusal}`;
+        case 'model_parse_error':
+            return `Model parse error at step '${error.stepId}': failed to parse output`;
+        case 'model_rate_limit':
+            return `Model rate limited at step '${error.stepId}'${error.retryAfter ? ` (retry after ${error.retryAfter}ms)` : ''}`;
         case 'fork_partial':
             return `Fork '${error.stepId}' partial failure: ${error.succeeded.length} succeeded, ${error.failed.length} failed`;
         case 'channel_timeout':
@@ -66,7 +66,7 @@ function formatMessage(error) {
                 ? `Item type '${error.itemType}' did not match any registered item extension schema.`
                 : `Item did not match any registered ${error.category} extension schema.`;
         case 'handle_evicted':
-            return `Subprocess handle '${error.handleId}' evicted (step '${error.stepId}'): adapter returned null for ${error.gracePeriodMs}ms`;
+            return `Subprocess handle '${error.handleId}' evicted (step '${error.stepId}'): adapter returned null for ${error.gracePeriod}ms`;
         default: {
             const _exhaustive = error;
             void _exhaustive;

package/dist/index.d.ts

@@ -2,7 +2,6 @@
  * @noetic-tools/types — foundational type contracts and primitives shared
  * across the Noetic framework.
  */
-export * from './deprecated.js';
 export * from './errors/noetic-config-error.js';
 export * from './errors/noetic-error.js';
 export * from './schemas/item.js';
@@ -11,6 +10,7 @@ export * from './types/channel.js';
 export * from './types/common.js';
 export * from './types/context.js';
 export * from './types/context-cache.js';
+export * from './types/context-harness.js';
 export * from './types/context-layer.js';
 export * from './types/context-parts/item-log.js';
 export * from './types/context-parts/layer-usage.js';
@@ -23,6 +23,7 @@ export * from './types/items.js';
 export * from './types/observability.js';
 export * from './types/output-codec.js';
 export * from './types/runtime.js';
+export * from './types/schema.js';
 export * from './types/shell-adapter.js';
 export * from './types/steering.js';
 export * from './types/step.js';

package/dist/index.js

@@ -2,7 +2,6 @@
  * @noetic-tools/types — foundational type contracts and primitives shared
  * across the Noetic framework.
  */
-export * from './deprecated.js';
 export * from './errors/noetic-config-error.js';
 export * from './errors/noetic-error.js';
 export * from './schemas/item.js';
@@ -11,6 +10,7 @@ export * from './types/channel.js';
 export * from './types/common.js';
 export * from './types/context.js';
 export * from './types/context-cache.js';
+export * from './types/context-harness.js';
 export * from './types/context-layer.js';
 export * from './types/context-parts/item-log.js';
 export * from './types/context-parts/layer-usage.js';
@@ -23,6 +23,7 @@ export * from './types/items.js';
 export * from './types/observability.js';
 export * from './types/output-codec.js';
 export * from './types/runtime.js';
+export * from './types/schema.js';
 export * from './types/shell-adapter.js';
 export * from './types/steering.js';
 export * from './types/step.js';

package/dist/schemas/workflow.d.ts

@@ -2,8 +2,8 @@
  * Zod schemas for JSON-serialisable workflow definitions.
  *
  * A `WorkflowDocument` is a portable, JSON-safe representation of a noetic
- * step tree. It covers every step kind. The `run` node carries its body as a
- * code STRING (not an in-process closure) dispatched through a subprocess
+ * step tree. It covers every step kind. The `runCode` node carries its body as
+ * a code STRING (not an in-process closure) dispatched through a subprocess
  * adapter, keeping the document JSON-safe. The hydrator in
  * `@noetic-tools/core` (`builders/workflow-hydrator.ts`) converts a validated
  * document back into live `Step` objects via the existing builders.
@@ -27,9 +27,11 @@ export type UntilPredicate = {
     usd: number;
 } | {
     kind: 'maxDuration';
-    ms: number;
+    duration: number;
 } | {
     kind: 'noToolCalls';
+} | {
+    kind: 'never';
 } | {
     kind: 'outputContains';
     marker: string;
@@ -48,9 +50,9 @@ export declare const MergeStrategy: {
     readonly First: 'first';
     readonly Concat: 'concat';
 };
-/** @public Named merge strategy for fork nodes. */
+/** @public Named merge strategy for inParallel nodes. */
 export type MergeStrategy = (typeof MergeStrategy)[keyof typeof MergeStrategy];
-/** @public Zod schema for the named merge strategy used by `fork` nodes. */
+/** @public Zod schema for the named merge strategy used by `inParallel` nodes. */
 export declare const MergeStrategySchema: z.ZodEnum<{
     concat: "concat";
     first: "first";
@@ -63,7 +65,7 @@ declare const ModelParamsSchema: z.ZodObject<{
     stopSequences: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 /**
- * A uniform tool entry on an `llm` node. Every entry is an object keyed by
+ * A uniform tool entry on a `callModel` node. Every entry is an object keyed by
  * `type`:
  *   - A CLIENT tool is `{ type: "<registered-tool-name>" }`. The hydrator
  *     resolves `type` against the tool registry; `parameters` (if present) is
@@ -76,11 +78,11 @@ declare const ModelParamsSchema: z.ZodObject<{
  * Server vs client is decided by the `type` value (a reserved `openrouter:*`
  * server-tool literal vs an arbitrary tool name), not by the entry's shape.
  */
-declare const LlmToolEntrySchema: z.ZodObject<{
+declare const CallModelToolEntrySchema: z.ZodObject<{
     type: z.ZodString;
     parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
-/** Retry policy for a `run` node, mirroring `RetryPolicy` in `@noetic-tools/types`. */
+/** Retry policy for a `runCode` node, mirroring `RetryPolicy` in `@noetic-tools/types`. */
 declare const RetryPolicySchema: z.ZodObject<{
     maxAttempts: z.ZodNumber;
     backoff: z.ZodEnum<{
@@ -115,7 +117,7 @@ interface WorkflowNodeBase {
     id: string;
 }
 /**
- * A reference to a streaming `OutputCodec` for an `llm` node's structured
+ * A reference to a streaming `OutputCodec` for a `callModel` node's structured
  * output. The hydrator resolves `library` from `HydrationContext.uiLibraries`
  * to a live codec (e.g. `openUi(myLibrary)` from `@noetic-tools/openui`), the
  * same registry-resolution pattern sub-harness nodes use for adapters. Kept a
@@ -127,8 +129,8 @@ export interface OutputCodecRef {
     /** Registry key resolved from `HydrationContext.uiLibraries`. */
     library: string;
 }
-export interface LlmWorkflowNode extends WorkflowNodeBase {
-    kind: 'llm';
+export interface CallModelWorkflowNode extends WorkflowNodeBase {
+    kind: 'callModel';
     model?: string;
     instructions: string;
     /**
@@ -138,26 +140,27 @@ export interface LlmWorkflowNode extends WorkflowNodeBase {
      * parameters?: {...} }` (executed by the provider). Client vs server is
      * decided by the `type` value.
      */
-    tools?: z.infer<typeof LlmToolEntrySchema>[];
+    tools?: z.infer<typeof CallModelToolEntrySchema>[];
     params?: z.infer<typeof ModelParamsSchema>;
     /** Streaming output-codec reference, resolved from `HydrationContext.uiLibraries`. */
     output?: OutputCodecRef;
 }
-export interface ToolWorkflowNode extends WorkflowNodeBase {
-    kind: 'tool';
+export interface InvokeToolWorkflowNode extends WorkflowNodeBase {
+    kind: 'invokeTool';
     toolName: string;
     args?: Record<string, unknown>;
 }
 /**
- * A node that runs a serialised code body. Unlike the programmatic `step.run`
- * (which carries a closure), the JSON form carries `execute` as a code STRING.
+ * A node that runs a serialised code body. Unlike the programmatic
+ * `step.runCode` (which carries a closure), the JSON form carries `execute` as
+ * a code STRING.
  * The code is never eval'd in-process (Cloudflare Workers forbid eval); it is
  * dispatched through a subprocess adapter (`ctx.subprocess`, or a named adapter
  * resolved by ref). Execution therefore requires a subprocess adapter capable
  * of running the code and returning its stdout.
  */
-export interface RunWorkflowNode extends WorkflowNodeBase {
-    kind: 'run';
+export interface RunCodeWorkflowNode extends WorkflowNodeBase {
+    kind: 'runCode';
     /** Source code executed in the subprocess. Receives the step input on stdin. */
     execute: string;
     /** Optional retry policy applied to the step. */
@@ -165,17 +168,17 @@ export interface RunWorkflowNode extends WorkflowNodeBase {
     /** Named subprocess adapter ref; defaults to `ctx.subprocess` when omitted. */
     subprocess?: string;
 }
-export interface BranchRoute {
+export interface ConditionalRoute {
     match: string;
     target: WorkflowNode;
 }
-export interface BranchWorkflowNode extends WorkflowNodeBase {
-    kind: 'branch';
-    routes: BranchRoute[];
+export interface ConditionalWorkflowNode extends WorkflowNodeBase {
+    kind: 'conditional';
+    routes: ConditionalRoute[];
     default?: WorkflowNode;
 }
-export interface ForkWorkflowNode extends WorkflowNodeBase {
-    kind: 'fork';
+export interface InParallelWorkflowNode extends WorkflowNodeBase {
+    kind: 'inParallel';
     mode: 'race' | 'all' | 'settle';
     /**
      * Static fan-out: one child per entry. Mutually exclusive with `each` —
@@ -188,8 +191,8 @@ export interface ForkWorkflowNode extends WorkflowNodeBase {
      */
     each?: WorkflowNode;
     /**
-     * Selector key into the fork input (parsed as JSON) locating the array to
-     * fan out over. When omitted, the input string itself is parsed as a JSON
+     * Selector key into the inParallel input (parsed as JSON) locating the array
+     * to fan out over. When omitted, the input string itself is parsed as a JSON
      * array. Only meaningful with `each`.
      */
     over?: string;
@@ -202,14 +205,14 @@ export interface SpawnWorkflowNode extends WorkflowNodeBase {
     timeout?: number;
     /**
      * Memory layers the child runs with, by registered name (resolved from
-     * `HydrationContext.layers`, like `provide`). Omit to inherit the parent's
-     * layers — the default spawn behaviour. Naming layers here REPLACES the
-     * inherited set for the child, so list every layer the child needs.
+     * `HydrationContext.layers`, like `withContext`). Omit to inherit the
+     * parent's layers — the default spawn behaviour. Naming layers here REPLACES
+     * the inherited set for the child, so list every layer the child needs.
      */
     layers?: string[];
 }
-export interface ProvideWorkflowNode extends WorkflowNodeBase {
-    kind: 'provide';
+export interface WithContextWorkflowNode extends WorkflowNodeBase {
+    kind: 'withContext';
     child: WorkflowNode;
     layers: string[];
 }
@@ -223,10 +226,10 @@ export interface SequenceWorkflowNode extends WorkflowNodeBase {
     kind: 'sequence';
     steps: WorkflowNode[];
 }
-export interface EveryWorkflowNode extends WorkflowNodeBase {
-    kind: 'every';
+export interface ScheduleWorkflowNode extends WorkflowNodeBase {
+    kind: 'schedule';
     step: WorkflowNode;
-    ms: number;
+    interval: number;
     onError?: 'continue' | 'fail';
 }
 /**
@@ -256,7 +259,7 @@ export interface SubflowWorkflowNode extends WorkflowNodeBase {
     input?: string;
 }
 /** @public Discriminated union of all JSON-serialisable workflow node kinds. */
-export type WorkflowNode = LlmWorkflowNode | ToolWorkflowNode | RunWorkflowNode | BranchWorkflowNode | ForkWorkflowNode | SpawnWorkflowNode | ProvideWorkflowNode | LoopWorkflowNode | SequenceWorkflowNode | EveryWorkflowNode | SubflowWorkflowNode | SubHarnessWorkflowNode;
+export type WorkflowNode = CallModelWorkflowNode | InvokeToolWorkflowNode | RunCodeWorkflowNode | ConditionalWorkflowNode | InParallelWorkflowNode | SpawnWorkflowNode | WithContextWorkflowNode | LoopWorkflowNode | SequenceWorkflowNode | ScheduleWorkflowNode | SubflowWorkflowNode | SubHarnessWorkflowNode;
 /** @public Zod schema validating a single `WorkflowNode` (any JSON-safe kind). */
 export declare const WorkflowNodeSchema: z.ZodType<WorkflowNode>;
 /** @public Top-level envelope for a JSON workflow definition. */
@@ -290,7 +293,7 @@ export interface WorkflowGraph {
 export declare function workflowGraph(root: WorkflowNode): WorkflowGraph;
 /**
  * Returns the maximum depth of a workflow tree.
- * Leaf nodes (`llm`, `tool`) have depth 0. Structural nodes add +1.
+ * Leaf nodes (`callModel`, `invokeTool`) have depth 0. Structural nodes add +1.
  * A `subflow` ref counts as a leaf — depth does not see through named refs.
  */
 export declare function workflowDepth(node: WorkflowNode): number;

package/dist/schemas/workflow.js

@@ -2,8 +2,8 @@
  * Zod schemas for JSON-serialisable workflow definitions.
  *
  * A `WorkflowDocument` is a portable, JSON-safe representation of a noetic
- * step tree. It covers every step kind. The `run` node carries its body as a
- * code STRING (not an in-process closure) dispatched through a subprocess
+ * step tree. It covers every step kind. The `runCode` node carries its body as
+ * a code STRING (not an in-process closure) dispatched through a subprocess
  * adapter, keeping the document JSON-safe. The hydrator in
  * `@noetic-tools/core` (`builders/workflow-hydrator.ts`) converts a validated
  * document back into live `Step` objects via the existing builders.
@@ -21,11 +21,14 @@ const MaxCostPredicateSchema = z.object({
 });
 const MaxDurationPredicateSchema = z.object({
     kind: z.literal('maxDuration'),
-    ms: z.number().positive(),
+    duration: z.number().positive(),
 });
 const NoToolCallsPredicateSchema = z.object({
     kind: z.literal('noToolCalls'),
 });
+const NeverPredicateSchema = z.object({
+    kind: z.literal('never'),
+});
 const OutputContainsPredicateSchema = z.object({
     kind: z.literal('outputContains'),
     marker: z.string().min(1),
@@ -54,6 +57,7 @@ export const UntilPredicateSchema = z
     MaxCostPredicateSchema,
     MaxDurationPredicateSchema,
     NoToolCallsPredicateSchema,
+    NeverPredicateSchema,
     OutputContainsPredicateSchema,
     OutputEqualsPredicateSchema,
     ConvergedPredicateSchema,
@@ -72,7 +76,7 @@ export const MergeStrategy = {
     First: 'first',
     Concat: 'concat',
 };
-/** @public Zod schema for the named merge strategy used by `fork` nodes. */
+/** @public Zod schema for the named merge strategy used by `inParallel` nodes. */
 export const MergeStrategySchema = z.enum([
     'last',
     'first',
@@ -89,7 +93,7 @@ const ModelParamsSchema = z.object({
 //#endregion
 //#region Tool Entries
 /**
- * A uniform tool entry on an `llm` node. Every entry is an object keyed by
+ * A uniform tool entry on a `callModel` node. Every entry is an object keyed by
  * `type`:
  *   - A CLIENT tool is `{ type: "<registered-tool-name>" }`. The hydrator
  *     resolves `type` against the tool registry; `parameters` (if present) is
@@ -102,13 +106,13 @@ const ModelParamsSchema = z.object({
  * Server vs client is decided by the `type` value (a reserved `openrouter:*`
  * server-tool literal vs an arbitrary tool name), not by the entry's shape.
  */
-const LlmToolEntrySchema = z.object({
+const CallModelToolEntrySchema = z.object({
     type: z.string().min(1),
     parameters: z.record(z.string(), z.unknown()).optional(),
 });
 //#endregion
 //#region Retry Policy
-/** Retry policy for a `run` node, mirroring `RetryPolicy` in `@noetic-tools/types`. */
+/** Retry policy for a `runCode` node, mirroring `RetryPolicy` in `@noetic-tools/types`. */
 const RetryPolicySchema = z.object({
     maxAttempts: z.number().int().positive(),
     backoff: z.enum([
@@ -155,41 +159,41 @@ const OutputCodecRefSchema = z.object({
     codec: z.literal('openui'),
     library: z.string().min(1),
 });
-const LlmNodeSchema = z.object({
-    kind: z.literal('llm'),
+const CallModelNodeSchema = z.object({
+    kind: z.literal('callModel'),
     ...SHARED_FIELDS,
     model: z.string().optional(),
     instructions: z.string(),
-    tools: z.array(LlmToolEntrySchema).optional(),
+    tools: z.array(CallModelToolEntrySchema).optional(),
     params: ModelParamsSchema.optional(),
     output: OutputCodecRefSchema.optional(),
 });
-const ToolNodeSchema = z.object({
-    kind: z.literal('tool'),
+const InvokeToolNodeSchema = z.object({
+    kind: z.literal('invokeTool'),
     ...SHARED_FIELDS,
     toolName: z.string().min(1),
     args: z.record(z.string(), z.unknown()).optional(),
 });
-const RunNodeSchema = z.object({
-    kind: z.literal('run'),
+const RunCodeNodeSchema = z.object({
+    kind: z.literal('runCode'),
     ...SHARED_FIELDS,
     execute: z.string().min(1),
     retry: RetryPolicySchema.optional(),
     subprocess: z.string().min(1).optional(),
 });
-const BranchRouteSchema = z.object({
+const ConditionalRouteSchema = z.object({
     match: z.string().min(1),
     target: z.lazy(() => WorkflowNodeSchema),
 });
-const BranchNodeSchema = z.object({
-    kind: z.literal('branch'),
+const ConditionalNodeSchema = z.object({
+    kind: z.literal('conditional'),
     ...SHARED_FIELDS,
-    routes: z.array(BranchRouteSchema).min(1),
+    routes: z.array(ConditionalRouteSchema).min(1),
     default: WorkflowNodeRef.optional(),
 });
-const ForkNodeSchema = z
+const InParallelNodeSchema = z
     .object({
-    kind: z.literal('fork'),
+    kind: z.literal('inParallel'),
     ...SHARED_FIELDS,
     mode: z.enum([
         'race',
@@ -203,7 +207,7 @@ const ForkNodeSchema = z
     concurrency: z.number().int().positive().optional(),
 })
     .refine((node) => (node.paths === undefined) !== (node.each === undefined), {
-    message: "fork node requires exactly one of 'paths' (static) or 'each' (dynamic).",
+    message: "inParallel node requires exactly one of 'paths' (static) or 'each' (dynamic).",
 });
 const SpawnNodeSchema = z.object({
     kind: z.literal('spawn'),
@@ -212,8 +216,8 @@ const SpawnNodeSchema = z.object({
     timeout: z.number().positive().optional(),
     layers: z.array(z.string().min(1)).min(1).optional(),
 });
-const ProvideNodeSchema = z.object({
-    kind: z.literal('provide'),
+const WithContextNodeSchema = z.object({
+    kind: z.literal('withContext'),
     ...SHARED_FIELDS,
     child: WorkflowNodeRef,
     layers: z.array(z.string().min(1)).min(1),
@@ -230,11 +234,11 @@ const SequenceNodeSchema = z.object({
     ...SHARED_FIELDS,
     steps: z.array(WorkflowNodeRef).min(1),
 });
-const EveryNodeSchema = z.object({
-    kind: z.literal('every'),
+const ScheduleNodeSchema = z.object({
+    kind: z.literal('schedule'),
     ...SHARED_FIELDS,
     step: WorkflowNodeRef,
-    ms: z.number().nonnegative(),
+    interval: z.number().nonnegative(),
     onError: z
         .enum([
         'continue',
@@ -272,16 +276,16 @@ const PiNodeSchema = subHarnessNodeSchema('pi');
 /** @public Zod schema validating a single `WorkflowNode` (any JSON-safe kind). */
 export const WorkflowNodeSchema = z
     .discriminatedUnion('kind', [
-    LlmNodeSchema,
-    ToolNodeSchema,
-    RunNodeSchema,
-    BranchNodeSchema,
-    ForkNodeSchema,
+    CallModelNodeSchema,
+    InvokeToolNodeSchema,
+    RunCodeNodeSchema,
+    ConditionalNodeSchema,
+    InParallelNodeSchema,
     SpawnNodeSchema,
-    ProvideNodeSchema,
+    WithContextNodeSchema,
     LoopNodeSchema,
     SequenceNodeSchema,
-    EveryNodeSchema,
+    ScheduleNodeSchema,
     SubflowNodeSchema,
     ClaudeCodeNodeSchema,
     CodexNodeSchema,
@@ -310,7 +314,7 @@ function childNodes(node) {
     switch (node.kind) {
         case 'sequence':
             return node.steps;
-        case 'fork':
+        case 'inParallel':
             if (node.each) {
                 return [
                     node.each,
@@ -318,7 +322,7 @@ function childNodes(node) {
             }
             return node.paths ?? [];
         case 'spawn':
-        case 'provide':
+        case 'withContext':
             return [
                 node.child,
             ];
@@ -326,11 +330,11 @@ function childNodes(node) {
             return [
                 node.body,
             ];
-        case 'every':
+        case 'schedule':
             return [
                 node.step,
             ];
-        case 'branch': {
+        case 'conditional': {
             const children = node.routes.map((r) => r.target);
             if (node.default) {
                 children.push(node.default);
@@ -388,7 +392,7 @@ export function workflowGraph(root) {
 }
 /**
  * Returns the maximum depth of a workflow tree.
- * Leaf nodes (`llm`, `tool`) have depth 0. Structural nodes add +1.
+ * Leaf nodes (`callModel`, `invokeTool`) have depth 0. Structural nodes add +1.
  * A `subflow` ref counts as a leaf — depth does not see through named refs.
  */
 export function workflowDepth(node) {

package/dist/types/common.d.ts

@@ -54,6 +54,12 @@ export interface TokenUsage {
     input: number;
     output: number;
     total: number;
+    /**
+     * Prompt tokens served from the provider's cache, summed across every model
+     * call on this execution. `undefined` — not `0` — while no call has reported a
+     * cache figure, preserving the `RoundUsage` distinction between "nothing was
+     * cached" and "this provider says nothing about caching".
+     */
     cached?: number;
 }
 /**