@noetic-tools/types 3.7.0 → 3.9.0

package/dist/schemas/workflow.d.ts

@@ -9,6 +9,7 @@
  * document back into live `Step` objects via the existing builders.
  */
 import { z } from 'zod';
+import type { ToolChoice } from '../types/common.js';
 import type { DecideQuestion } from '../types/decide.js';
 import type { DecideView } from '../types/step.js';
 interface UntilAnyPredicate {
@@ -226,6 +227,12 @@ export interface CallModelWorkflowNode extends WorkflowNodeBase {
      * decided by the `type` value.
      */
     tools?: z.infer<typeof CallModelToolEntrySchema>[];
+    /**
+     * How the model may use its tools: `"auto"` (default), `"required"`,
+     * `"none"`, or `{ "tool": "<registered-tool-name>" }` to force one client
+     * tool from `tools`.
+     */
+    toolChoice?: ToolChoice;
     params?: z.infer<typeof ModelParamsSchema>;
     /** Streaming output-codec reference, resolved from `HydrationContext.uiLibraries`. */
     output?: OutputCodecRef;

package/dist/schemas/workflow.js

@@ -9,7 +9,7 @@
  * document back into live `Step` objects via the existing builders.
  */
 import { z } from 'zod';
-import { ServiceTier } from '../types/common.js';
+import { ServiceTier, ToolChoiceMode } from '../types/common.js';
 import { DecideQuestionsSchema, routeOutcomes } from '../types/decide.js';
 //#endregion
 //#region Until Predicate Schemas
@@ -93,6 +93,12 @@ const ModelParamsSchema = z.object({
     stopSequences: z.array(z.string()).optional(),
     serviceTier: z.enum(ServiceTier).optional(),
 });
+const ToolChoiceSchema = z.union([
+    z.enum(ToolChoiceMode),
+    z.object({
+        tool: z.string().min(1),
+    }),
+]);
 //#endregion
 //#region Tool Entries
 /**
@@ -230,6 +236,7 @@ const CallModelNodeSchema = z.object({
     model: z.string().optional(),
     instructions: z.string(),
     tools: z.array(CallModelToolEntrySchema).optional(),
+    toolChoice: ToolChoiceSchema.optional(),
     params: ModelParamsSchema.optional(),
     output: OutputCodecRefSchema.optional(),
 });

package/dist/types/common.d.ts

@@ -52,6 +52,25 @@ export declare const ServiceTier: {
 };
 /** @public Union of OpenRouter service tiers. */
 export type ServiceTier = (typeof ServiceTier)[keyof typeof ServiceTier];
+/**
+ * @public How a model call may use its tools. `auto` lets the model decide,
+ * `required` makes it call at least one tool, `none` forbids tool calls.
+ */
+export declare const ToolChoiceMode: {
+    readonly Auto: "auto";
+    readonly Required: "required";
+    readonly None: "none";
+};
+/** @public Union of {@link ToolChoiceMode} values. */
+export type ToolChoiceMode = (typeof ToolChoiceMode)[keyof typeof ToolChoiceMode];
+/**
+ * @public Tool choice for a model call: a {@link ToolChoiceMode}, or
+ * `{ tool: name }` to force a call to one client tool. It combines with the
+ * step's `tools` restriction (spec 02, Unified Tool Set).
+ */
+export type ToolChoice = ToolChoiceMode | {
+    tool: string;
+};
 /**
  * Optional parameters forwarded to the model provider during an LLM step.
  * @public
@@ -63,7 +82,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/common.js

@@ -31,3 +31,12 @@ export const ServiceTier = {
     Scale: 'scale',
     Ultrafast: 'ultrafast',
 };
+/**
+ * @public How a model call may use its tools. `auto` lets the model decide,
+ * `required` makes it call at least one tool, `none` forbids tool calls.
+ */
+export const ToolChoiceMode = {
+    Auto: 'auto',
+    Required: 'required',
+    None: 'none',
+};

package/dist/types/context-harness.d.ts

@@ -1,6 +1,6 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { Channel, ChannelHandle, ExternalChannel } from './channel.js';
-import type { LLMResponse, ModelParams } from './common.js';
+import type { LLMResponse, ModelParams, ToolChoice } from './common.js';
 import type { Context, CwdState, RestoreContextOptions } from './context.js';
 import type { ContextCacheConfig, ContextCacheStore } from './context-cache.js';
 import type { ContextData, ContextLayer, ProjectionPolicy, RecallOptions, StorageAdapter } from './context-layer.js';
@@ -29,6 +29,7 @@ interface ContextCallModelRequestBase {
     items: ReadonlyArray<Item>;
     instructions?: string;
     params?: ModelParams;
+    toolChoice?: ToolChoice;
     outputSchema?: StandardSchemaV1;
     /** Explicit non-Zod override/fallback after StandardJSONSchemaV1 conversion. */
     outputJsonSchema?: Record<string, unknown>;

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

@@ -17,6 +17,7 @@ export interface LayerTimeouts {
     store?: number;
     onSpawn?: number;
     onReturn?: number;
+    onParentUpdate?: number;
     onComplete?: number;
     dispose?: number;
     beforeToolCall?: number;
@@ -246,6 +247,21 @@ export interface ReturnResult<TState> {
     parentState: TState;
     result?: unknown;
 }
+/** @public Parameters passed to a context layer's `onParentUpdate` hook when the parent writes the layer's state while a child runs. */
+export interface ParentUpdateParams<TState> {
+    /** The state the parent just wrote. */
+    parentState: TState;
+    /** The child's state for the layer when the hook starts. */
+    childState: TState;
+    childCtx: ExecutionContext;
+}
+/** @public Value returned by a context layer's `onParentUpdate` hook. */
+export interface ParentUpdateResult<TState> {
+    /** New child state. Detected with `'childState' in result`, so `undefined` clears it. */
+    childState?: TState;
+    /** Items appended to the child's ItemLog. */
+    items?: Item[];
+}
 /** @public Parameters passed to a context layer's `onComplete` hook at execution end. */
 export interface CompleteParams<TState> {
     log: ItemLog;
@@ -325,6 +341,12 @@ export interface ContextLayerHooks<TState = unknown> {
     store?(params: StoreParams<TState>): Promise<StoreResult<TState> | undefined>;
     onSpawn?(params: SpawnParams<TState>): Promise<SpawnResult<TState> | null>;
     onReturn?(params: ReturnParams<TState>): Promise<ReturnResult<TState> | undefined>;
+    /**
+     * Called in a live child when its parent writes this layer's state. Runs in
+     * the background: the parent's write never waits for it or fails because of
+     * it. Return nothing to ignore the update.
+     */
+    onParentUpdate?(params: ParentUpdateParams<TState>): Promise<ParentUpdateResult<TState> | undefined>;
     onComplete?(params: CompleteParams<TState>): Promise<undefined | {
         state: TState;
     }>;

package/dist/types/context-scope.d.ts

@@ -12,6 +12,15 @@ export interface LayerCallModelRequest {
     items: ReadonlyArray<Item>;
     instructions?: string;
 }
+/**
+ * @public Span opened from an `ExecutionContext`. `end()` closes the span and
+ * hands it to the harness's trace exporter; await it so the export finishes.
+ */
+export interface ExecutionSpan {
+    setAttribute(key: string, value: string | number | boolean): void;
+    addEvent(name: string, attributes?: Record<string, string | number | boolean>): void;
+    end(): Promise<void>;
+}
 /** @public Runtime metadata available to context layer hooks during each lifecycle phase. */
 export interface ExecutionContext {
     executionId: string;
@@ -33,6 +42,11 @@ export interface ExecutionContext {
     trace: {
         setAttribute(key: string, value: string | number | boolean): void;
         addEvent(name: string, attributes?: Record<string, string | number | boolean>): void;
+        /**
+         * Opens a span under the context's span. Optional: a context with no span
+         * tree to grow omits it, and callers fall back to `addEvent`.
+         */
+        createSpan?(name: string): ExecutionSpan;
     };
     /** Snapshot a sibling context layer's state by its `layer.id`. */
     readLayerState<T>(layerId: string): T | undefined;

package/dist/types/observability.d.ts

@@ -14,7 +14,7 @@ export interface TraceExporter {
 /** @public Diagnostic span recording a single context layer hook invocation and its outcome. */
 export interface LayerTraceSpan {
     layerId: string;
-    hook: 'init' | 'recall' | 'store' | 'onSpawn' | 'onReturn' | 'onComplete' | 'dispose';
+    hook: 'init' | 'recall' | 'store' | 'onSpawn' | 'onReturn' | 'onParentUpdate' | 'onComplete' | 'dispose' | 'onDecision' | 'beforeToolCall' | 'afterModelCall' | 'projectHistory' | 'onItemAppend';
     /** Duration in milliseconds. */
     duration: number;
     status: 'ok' | 'error' | 'timeout' | 'skipped';

package/dist/types/runtime.d.ts

@@ -1,6 +1,6 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { Channel, ChannelHandle, ExternalChannel } from './channel.js';
-import type { LLMResponse, ModelParams, ServerToolSpec } from './common.js';
+import type { LLMResponse, ModelParams, ServerToolSpec, ToolChoice } from './common.js';
 import type { Context, CwdState, RestoreContextOptions } from './context.js';
 import type { ContextCacheConfig, ContextCacheStore } from './context-cache.js';
 import type { ContextData, ContextLayer, ProjectionPolicy, RecallOptions, StorageAdapter } from './context-layer.js';
@@ -11,6 +11,7 @@ import type { HarnessResponse, StreamEvent, StreamingItem } from './harness-resu
 import type { ExecuteInput, Item, ItemSchemaExtensions } from './items.js';
 import type { Span, TraceExporter } from './observability.js';
 import type { ShellAdapter } from './shell-adapter.js';
+import type { ToolApprover } from './steering.js';
 import type { Step } from './step.js';
 import type { SubprocessAdapter } from './subprocess-adapter.js';
 import type { Tool } from './tool.js';
@@ -42,6 +43,8 @@ export interface AgentConfig<TParams extends Record<string, unknown> = Record<st
     contextCache?: ContextCacheConfig;
     /** Default model for `decide` steps. */
     decisionModel?: string;
+    /** Approves or refuses calls to tools that declare `needsApproval`. Without one, those calls run unapproved. */
+    approveToolCall?: ToolApprover;
 }
 /** @public How a message submitted during an active turn is delivered to the model.
  *
@@ -60,6 +63,12 @@ interface CallModelRequestBase {
     items: ReadonlyArray<Item>;
     instructions?: string;
     params?: ModelParams;
+    /**
+     * How the model may use its tools. Defaults to `'auto'`. Combines with
+     * `allowedToolNames` (spec 02, Unified Tool Set). A `{ tool }` naming a tool
+     * the call cannot run throws `NoeticConfigError` `UNKNOWN_TOOL_CHOICE`.
+     */
+    toolChoice?: ToolChoice;
     /** When provided, the harness sends a JSON Schema constraint to the model so it returns structured JSON. */
     outputSchema?: StandardSchemaV1;
     /**
@@ -94,6 +103,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 {

package/dist/types/steering.d.ts

@@ -1,4 +1,5 @@
 import type { LLMResponse } from './common.js';
+import type { Context } from './context.js';
 import type { ContextScope, ExecutionContext } from './context-scope.js';
 /** @public Enumeration of actions a steering rule can take on a tool call or model response. */
 export declare const SteeringAction: {
@@ -59,6 +60,30 @@ export interface BeforeToolCallResult<TState = unknown> {
     decision: SteeringDecision;
     state?: TState;
 }
+/**
+ * @public Parameters passed to the harness approver for a call to a tool that
+ * declares `needsApproval`.
+ */
+export interface ApproveToolCallParams {
+    toolName: string;
+    /** The validated arguments — exactly what `execute` receives if the call is approved. */
+    toolArgs: unknown;
+    /** Correlation id of the pending call; see `BeforeToolCallParams.callId`. */
+    callId?: string;
+    /**
+     * The calling step's context. An approver that waits on a human passes it
+     * to `ctx.harness.send` / `ctx.harness.recv` to park on a channel.
+     */
+    ctx: Context;
+}
+/**
+ * @public Decides whether a call to a tool that declares `needsApproval` may
+ * run. Configured once per harness (`AgentHarness({ approveToolCall })`) and
+ * consulted after every `beforeToolCall` layer has allowed the call. `allow`
+ * runs the call; any other action refuses it, with `guidance` as the reason.
+ * May be async and may wait — e.g. on a channel a human answers.
+ */
+export type ToolApprover = (params: ApproveToolCallParams) => SteeringDecision | Promise<SteeringDecision>;
 /** @public Parameters passed to a steering rule's `afterModelCall` evaluation. */
 export interface AfterModelCallParams<TState = unknown> {
     response: LLMResponse;

package/dist/types/step.d.ts

@@ -1,7 +1,7 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { AcpAgent, AcpClientCapabilityConfig, AcpContentBlock, AcpMcpServer, AcpPermissionHandler, AcpPermissionPolicy, AcpSessionPolicy } from './acp.js';
 import type { Channel } from './channel.js';
-import type { ModelParams, RetryPolicy, ServerToolSpec, StepMeta } from './common.js';
+import type { ModelParams, RetryPolicy, ServerToolSpec, StepMeta, ToolChoice } from './common.js';
 import type { Context } from './context.js';
 import type { ContextConfig, ContextData, ContextLayer, ProjectionPolicy } from './context-layer.js';
 import type { DecideAnswers, DecideQuestions } from './decide.js';
@@ -138,6 +138,12 @@ export interface StepCallModel<TContext = ContextData, I = unknown, O = unknown>
      * they are resolved per execution.
      */
     tools?: Lazy<(Tool | ServerToolSpec)[] | undefined, TContext>;
+    /**
+     * How the model may use its tools: `'auto'` (default), `'required'`,
+     * `'none'`, or `{ tool: name }` to force one client tool. Applies within the
+     * `tools` restriction; see spec 02, Unified Tool Set.
+     */
+    toolChoice?: ToolChoice;
     /**
      * Structured output: a Standard Schema (assistant text is JSON-parsed and
      * validated) or a streaming `OutputCodec` (fed each text delta, produces

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,12 @@ 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. */
+    /**
+     * Every call needs approval before it runs. The harness asks its
+     * `approveToolCall` approver after the `beforeToolCall` layers allow the
+     * call. With no approver configured the call runs unapproved and the
+     * harness warns once per tool name.
+     */
     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.7.0",
+  "version": "3.9.0",
   "type": "module",
   "description": "Foundational type contracts and primitives shared across the Noetic framework (items, LLM config, adapters, steering, errors).",
   "license": "Apache-2.0",