@noetic-tools/types 3.2.2 → 3.3.0

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

@@ -42,8 +42,10 @@ interface ContextCallModelRequestWithTools extends ContextCallModelRequestBase {
 }
 interface ContextCallModelRequestWithoutTools extends ContextCallModelRequestBase {
     tools?: undefined;
-    ctx?: undefined;
-    layers?: undefined;
+    /** Accepted without tools — it carries the broadcaster for streaming (see `CallModelRequestWithoutTools`). */
+    ctx?: Context;
+    layers?: ContextLayer[];
+    allowedToolNames?: undefined;
 }
 export type ContextCallModelRequest = ContextCallModelRequestWithTools | ContextCallModelRequestWithoutTools;
 export interface ContextDetachedSpawnOverrides {
@@ -118,7 +120,7 @@ export interface ContextHarness {
     setRootCwd(nextCwd: string): void;
     getLayerState<T>(executionId: string, layerId: string): T | undefined;
     setLayerState<T>(executionId: string, layerId: string, state: T): void;
-    beforeToolCall(layers: ContextLayer[], toolName: string, toolArgs: unknown, ctx: Context): Promise<SteeringDecision>;
+    beforeToolCall(layers: ContextLayer[], toolName: string, toolArgs: unknown, ctx: Context, callId?: string): Promise<SteeringDecision>;
     afterModelCall(layers: ContextLayer[], response: LLMResponse, ctx: Context): Promise<SteeringDecision>;
     runAppendPipeline(layers: ContextLayer[], items: Item[], ctx: Context): Promise<ContextAppendPipelineResult>;
     /** Pinned anchor output and epoch bookkeeping for prompt-cache anchoring. Absent on a harness that predates it. */

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

@@ -372,6 +372,16 @@ export interface ContextLayer<TState = unknown> {
      *   (its `recall`/`store`/etc. are skipped). Opt in only for non-critical layers.
      */
     onInitError?: 'throw' | 'disable';
+    /**
+     * What a failed `beforeToolCall` hook (throw or timeout) means for the
+     * pending tool call.
+     * - `'abstain'` (default): log a diagnostic and let the remaining layers /
+     *   the default decide — correct for observational layers, where a bug must
+     *   not block every tool.
+     * - `'deny'`: the call is denied — correct for permission GATES, where a
+     *   failed check must fail closed rather than silently approving.
+     */
+    onBeforeToolCallError?: 'abstain' | 'deny';
     /**
      * Recall mode controlling whether this layer's `recall()` blocks the model call.
      * - `'atomic'` (default): recall runs synchronously in the hot path; the

package/dist/types/runtime.d.ts

@@ -101,12 +101,17 @@ interface CallModelRequestWithTools extends CallModelRequestBase {
     /** When set, restricts which tools the model may invoke for this call. */
     allowedToolNames?: string[];
 }
-/** @public Request shape when no tools are provided — ctx is only needed for tool
- *  execution callbacks in convertTools, so it is omitted here. */
+/**
+ * @public Request shape when no tools are provided. `ctx` is still accepted —
+ * it carries the session broadcaster, without which a tool-less call streams
+ * nothing to `getFullStream`/`getTextStream` — it just isn't *required* the
+ * way the tools variant needs it for execution callbacks.
+ */
 interface CallModelRequestWithoutTools extends CallModelRequestBase {
     tools?: undefined;
-    ctx?: undefined;
-    layers?: undefined;
+    ctx?: Context;
+    layers?: ContextLayer[];
+    allowedToolNames?: undefined;
 }
 /** @public Request object for `AgentHarnessContract.callModel()`. Encapsulates all parameters needed for an LLM call using only Noetic types. */
 export type CallModelRequest = CallModelRequestWithTools | CallModelRequestWithoutTools;
@@ -117,6 +122,13 @@ export interface ExecuteOptions {
     state?: unknown;
     /** Context layers to apply to the execution context. Overrides harness-level layers if provided. */
     contextLayers?: ContextLayer[];
+    /**
+     * Additional context layers appended AFTER the effective layer set
+     * (harness-level layers, or `contextLayers` when that override is given).
+     * Use this to inject a per-turn layer — a permission gate, an observer —
+     * without discarding the layers the harness was built with.
+     */
+    extraContextLayers?: ContextLayer[];
     /** Override the harness's default delivery mode for this message only. */
     deliveryMode?: DeliveryMode;
     /**
@@ -244,6 +256,8 @@ export interface AgentHarnessContract<TParams extends Record<string, unknown> =
         threadId?: string;
         resourceId?: string;
         contextLayers?: ContextLayer[];
+        /** Additional layers appended AFTER the effective layer set (see `ExecuteOptions.extraContextLayers`). */
+        extraContextLayers?: ContextLayer[];
         /** Override the new context's initial cwd. */
         cwdInit?: string;
     }): Context;
@@ -318,7 +332,7 @@ export interface AgentHarnessContract<TParams extends Record<string, unknown> =
     createSpan(name: string, parent: Span | null): Span;
     getLayerState<T>(executionId: string, layerId: string): T | undefined;
     setLayerState<T>(executionId: string, layerId: string, state: T): void;
-    beforeToolCall(layers: ContextLayer[], toolName: string, toolArgs: unknown, ctx: Context): Promise<SteeringDecision>;
+    beforeToolCall(layers: ContextLayer[], toolName: string, toolArgs: unknown, ctx: Context, callId?: string): Promise<SteeringDecision>;
     afterModelCall(layers: ContextLayer[], response: LLMResponse, ctx: Context): Promise<SteeringDecision>;
     /**
      * Project the history items through every layer's `projectHistory` hook in

package/dist/types/steering.d.ts

@@ -42,6 +42,15 @@ export interface LedgerEntry {
 export interface BeforeToolCallParams<TState = unknown> {
     toolName: string;
     toolArgs: unknown;
+    /**
+     * Correlation id of the pending call — the same id carried by the
+     * `tool_call_started` framework event (the model's `callId` on model-driven
+     * calls, the step id on a direct `invokeTool`). Lets a gating layer tie its
+     * decision to the call it is reported as, e.g. when forwarding the request
+     * to an external approver. Optional because a custom caller of the gate may
+     * have no call identity; every built-in tool-executing path supplies it.
+     */
+    callId?: string;
     ctx: ExecutionContext;
     state: TState;
 }

package/dist/types/tool.d.ts

@@ -1,4 +1,5 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { AcpToolKind } from './acp.js';
 import type { FunctionCallItem, FunctionCallOutputItem, Item, ItemSchemaExtensions, ToolResultExtensionItem } from './items.js';
 import type { InferSchemaOutput } from './schema.js';
 type ToolExecutionResult<O extends StandardSchemaV1> = Promise<InferSchemaOutput<O>> | AsyncGenerator<unknown, InferSchemaOutput<O>>;
@@ -50,6 +51,33 @@ export interface ToolUiDeclaration<I extends StandardSchemaV1 = StandardSchemaV1
     /** Replaces the tool's region when execution throws. */
     error?(err: unknown, args: InferSchemaOutput<I>): UiFragment | null;
 }
+/**
+ * How a tool call presents in an ACP client's UI when the harness is served
+ * as an ACP agent (`toAcpAgent`/`serveAcp` in `@noetic-tools/acp`).
+ *
+ * Presentation only — it never gates anything. An undeclared tool falls back
+ * to kind `other` with its name as the title. Declared as methods (bivariant
+ * params) for the same reason as `ToolUiDeclaration`.
+ * @public
+ */
+export interface ToolAcpDeclaration<I extends StandardSchemaV1 = StandardSchemaV1> {
+    /** ACP tool kind (`read`, `edit`, `execute`, …) for editor rendering. */
+    kind?: AcpToolKind;
+    /** Human-readable title; a function receives the call's parsed args. */
+    title?: string | ToolAcpTitleFn<I>;
+    /** File paths the call affects, surfaced as ACP `locations`. */
+    locations?(args: InferSchemaOutput<I>): string[];
+}
+/**
+ * Bivariant function type for `ToolAcpDeclaration.title` — a union member
+ * cannot use method syntax, so the method-bearing object type is indexed to
+ * recover the same bivariance `ToolUiDeclaration`'s methods get, keeping a
+ * concretely-typed tool assignable to the erased `Tool` form.
+ * @public
+ */
+export type ToolAcpTitleFn<I extends StandardSchemaV1 = StandardSchemaV1> = {
+    bivariant(args: InferSchemaOutput<I>): string;
+}['bivariant'];
 /**
  * A tool definition that an LLM can invoke during execution.
  *
@@ -105,5 +133,7 @@ export interface Tool<I extends StandardSchemaV1 = StandardSchemaV1, O extends S
     context?: ToolContextDeclaration;
     /** Optional UI declaration — the runtime emits the rendered fragments at call/progress/result points. */
     ui?: ToolUiDeclaration<I, O>;
+    /** Optional ACP presentation — how the call renders in an ACP client when the harness is served as an agent. */
+    acp?: ToolAcpDeclaration<I>;
 }
 export {};

package/package.json

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