@noetic-tools/types 3.6.0 → 3.7.0

package/dist/errors/noetic-config-error.d.ts

@@ -22,8 +22,8 @@ export declare class NoeticConfigError extends Error {
     readonly code: string;
     /** Complete sentence describing what the user should do next. */
     readonly hint: string;
-    /** Link to the relevant docs page, if available. */
-    readonly docsUrl?: string;
+    /** Link to the docs explaining this code; defaults to its section of the error reference. */
+    readonly docsUrl: string;
     constructor(opts: {
         code: string;
         message: string;
@@ -31,6 +31,16 @@ export declare class NoeticConfigError extends Error {
         docsUrl?: string;
     });
 }
+/**
+ * @public
+ * The error reference section for a config error `code`. Each code has a
+ * heading of its own name on that page, and the docs site slugs headings to
+ * lower case, so the code in lower case is the anchor.
+ *
+ * @param code - A `NoeticConfigError` code, e.g. `'MISSING_API_KEY'`.
+ * @returns The URL of the code's section, e.g. `…/errors#missing_api_key`.
+ */
+export declare function configErrorDocsUrl(code: string): string;
 /**
  * @public
  * Type guard for `NoeticConfigError`.

package/dist/errors/noetic-config-error.js

@@ -22,16 +22,29 @@ export class NoeticConfigError extends Error {
     code;
     /** Complete sentence describing what the user should do next. */
     hint;
-    /** Link to the relevant docs page, if available. */
+    /** Link to the docs explaining this code; defaults to its section of the error reference. */
     docsUrl;
     constructor(opts) {
         super(opts.message);
         this.name = 'NoeticConfigError';
         this.code = opts.code;
         this.hint = opts.hint;
-        this.docsUrl = opts.docsUrl;
+        this.docsUrl = opts.docsUrl ?? configErrorDocsUrl(opts.code);
     }
 }
+const ERROR_REFERENCE_URL = 'https://noetic.tools/docs/framework/errors';
+/**
+ * @public
+ * The error reference section for a config error `code`. Each code has a
+ * heading of its own name on that page, and the docs site slugs headings to
+ * lower case, so the code in lower case is the anchor.
+ *
+ * @param code - A `NoeticConfigError` code, e.g. `'MISSING_API_KEY'`.
+ * @returns The URL of the code's section, e.g. `…/errors#missing_api_key`.
+ */
+export function configErrorDocsUrl(code) {
+    return `${ERROR_REFERENCE_URL}#${code.toLowerCase()}`;
+}
 /**
  * @public
  * Type guard for `NoeticConfigError`.

package/dist/errors/noetic-error.js

@@ -51,6 +51,8 @@ function formatMessage(error) {
             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 'spawn_summary_failed':
+            return `Spawn '${error.stepId}' summary failed: ${error.summaryCause.message}`;
         case 'channel_timeout':
             return `Channel '${error.channelName}' timed out after ${error.timeout}ms`;
         case 'channel_closed':

package/dist/schemas/workflow.d.ts

@@ -181,6 +181,16 @@ declare const AcpSessionPolicySchema: z.ZodObject<{
     }>>;
     load: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+/**
+ * @public
+ * Which part of a node's input names the work it does, so a resumed run replays the
+ * node by content rather than by position. `true` keys on the whole input. `from`
+ * keys on those top-level properties of the input parsed as a JSON object — the same
+ * lookup an `inParallel` node's `over` does. See spec 26 § Replay keys.
+ */
+export type WorkflowReplayKey = true | {
+    from: string[];
+};
 interface WorkflowNodeBase {
     id: string;
     /**
@@ -188,6 +198,8 @@ interface WorkflowNodeBase {
      * `false` makes the node run again on every resume. See spec 23a § Identity.
      */
     durable?: boolean;
+    /** Replay this node by its input instead of its position. Ignored when `durable` is `false`. */
+    replayKey?: WorkflowReplayKey;
 }
 /**
  * A reference to a streaming `OutputCodec` for a `callModel` node's structured

package/dist/schemas/workflow.js

@@ -209,9 +209,16 @@ const AcpSessionPolicySchema = z.object({
 //#endregion
 //#region Workflow Node Schema
 const WorkflowNodeRef = z.lazy(() => WorkflowNodeSchema);
+const WorkflowReplayKeySchema = z.union([
+    z.literal(true),
+    z.object({
+        from: z.array(z.string().min(1)).min(1),
+    }),
+]);
 const SHARED_FIELDS = {
     id: z.string().min(1),
     durable: z.boolean().optional(),
+    replayKey: WorkflowReplayKeySchema.optional(),
 };
 const OutputCodecRefSchema = z.object({
     codec: z.literal('openui'),

package/dist/types/error.d.ts

@@ -32,6 +32,17 @@ export type NoeticError = {
         stepId: string;
         error: NoeticError;
     }>;
+} | {
+    /**
+     * A spawn's child succeeded but a context layer's `onReturn` hook (for
+     * example a summarizer) failed. The runtime does not throw this: the
+     * spawn returns `childOutput` and reports this error as a layer
+     * diagnostic and a span event, so the child's work is never discarded.
+     */
+    kind: 'spawn_summary_failed';
+    stepId: string;
+    childOutput: unknown;
+    summaryCause: Error;
 } | {
     kind: 'channel_timeout';
     channelName: string;

package/dist/types/runtime.d.ts

@@ -319,7 +319,9 @@ export interface AgentHarnessContract<TParams extends Record<string, unknown> =
     disposeLayers(layers: ContextLayer[], ctx: Context): Promise<void>;
     checkpoint(ctx: Context): Promise<void>;
     /**
-     * Rebuild a `Context` from a persisted snapshot. `opts` carries the wiring
+     * Rebuild a `Context` from a persisted snapshot, or from the step-completion
+     * ledger alone when no snapshot was saved (recorded steps replay, the rest run
+     * fresh). Resolves `null` when neither is recorded. `opts` carries the wiring
      * the host attached when it created the original context — without it a
      * decorated context is silently replaced by a bare one on resume.
      */

package/package.json

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