@noetic-tools/types 3.6.0 → 3.8.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/common.d.ts

@@ -63,7 +63,12 @@ export interface ModelParams {
     topP?: number;
     /** Maximum number of tokens the model may generate. */
     maxTokens?: number;
-    /** Sequences that cause the model to stop generating. */
+    /**
+     * Sequences that would cause the model to stop generating.
+     * @deprecated Not sent to the model: the OpenRouter Responses API that
+     * `callModel` uses has no stop parameter. Accepted so existing steps and
+     * workflow documents still parse; it will be removed in the next major.
+     */
     stopSequences?: string[];
     /** OpenRouter service tier to request. Omit to use the provider default. */
     serviceTier?: ServiceTier;

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

@@ -94,6 +94,12 @@ interface CallModelRequestBase {
      * each span back to its node in the declared DAG.
      */
     nodeId?: string;
+    /**
+     * @internal Attributes for the first `llm.call` span this request opens. Set
+     * by `callModel` steps to record how the view was banded (the
+     * `noetic.context.*` anchoring attributes).
+     */
+    spanAttributes?: Record<string, string | number | boolean>;
 }
 /** @public Request shape when tools are provided — ctx is required for tool execution callbacks. */
 interface CallModelRequestWithTools extends CallModelRequestBase {
@@ -319,7 +325,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/dist/types/subprocess-adapter.d.ts

@@ -66,6 +66,13 @@ export interface StepSubprocessRequest extends SubprocessRequestBase {
     serializedInput: unknown;
     /** Stable id for the execution — used for handle lookup and durable checkpointing. */
     executionId: string;
+    /**
+     * Id of the context that created this child (`spawn`, `detachedSpawn`).
+     * Durable adapters persist it so a host can `harness.restore()` the parent
+     * after a restart. Absent for a `runCode`, which runs on the dispatching
+     * context itself.
+     */
+    parentExecutionId?: string;
     /** Child-context overrides (thread, resource, cwd). */
     overrides: StepSubprocessOverrides;
     /**
@@ -92,6 +99,8 @@ export interface SubprocessHandleMetadata extends Record<string, unknown> {
     error?: SerializedError;
     /** Execution id echoed from the originating `StepSubprocessRequest`. */
     executionId?: string;
+    /** Parent execution id echoed from the originating `StepSubprocessRequest`. */
+    parentExecutionId?: string;
 }
 /** @public Handle returned by `SubprocessAdapter.spawn()` — a durable reference to a child. */
 export interface SubprocessHandle {

package/dist/types/tool.d.ts

@@ -127,7 +127,11 @@ export interface Tool<I extends StandardSchemaV1 = StandardSchemaV1, O extends S
      * the call site to get a typed handle.
      */
     execute(args: InferSchemaOutput<I>, toolCtx: unknown): ToolExecutionResult<O>;
-    /** When true, execution pauses for human approval before running. */
+    /**
+     * Declares that a call needs human approval before it runs. Core records the
+     * flag on `tool.call` spans but does not pause on it: a `beforeToolCall`
+     * gating layer or the tool's own integration must enforce it.
+     */
     needsApproval?: boolean;
     /** Optional context declaration — the runtime generates a ContextLayer from this. */
     context?: ToolContextDeclaration;

package/package.json

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