@axiom-lattice/core 3.0.3 → 3.0.5

package/dist/index.d.mts

@@ -8,7 +8,7 @@ import { BaseLanguageModelInput, LanguageModelLike } from '@langchain/core/langu
 import { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
 import { ChatResult } from '@langchain/core/outputs';
 import * as _axiom_lattice_protocols from '@axiom-lattice/protocols';
-import { LLMConfig, SemanticMetricsServerConfig, MetricMeta, MetricQueryResult, DataSource, SemanticMetricsQueryRequest, SemanticMetricsQueryResponse, TableQueryRequest, TableQueryResponse, ExecuteSqlQueryRequest, ExecuteSqlQueryResponse, MetricsServerType, MetricsServerConfig, ToolConfig, ToolExecutor, AgentConfig, MiddlewareType, GraphBuildOptions, MessageChunk, MessageChunkType, QueueLatticeProtocol, QueueConfig, QueueClient, QueueResult, ScheduleLatticeProtocol, ScheduleConfig, ScheduleClient, ScheduleStorage, TaskHandler, ScheduleOnceOptions, ScheduleCronOptions, ScheduledTaskDefinition, ScheduledTaskStatus, ScheduleExecutionType, ThreadStore, AssistantStore, SkillStore, CollectionStore, WorkspaceStore, ProjectStore, DatabaseConfigStore, MetricsServerConfigStore, McpServerConfigStore, UserStore, TenantStore, UserTenantLinkStore, WorkflowTrackingStore, EvalStore, ChannelInstallationStore, BindingRegistry, MenuRegistry, A2AApiKeyStore, TaskStore, SharedResourceStore, ConnectionStore, TaskWorkItemStore, VectorStoreProvider, Thread, CreateThreadRequest, Assistant, CreateAssistantRequest, Skill, CreateSkillRequest, SkillStoreContext, DatabaseConfigEntry, CreateDatabaseConfigRequest, UpdateDatabaseConfigRequest, User, CreateUserRequest, UpdateUserRequest, Tenant, CreateTenantRequest, UpdateTenantRequest, UserTenantLink, CreateUserTenantLinkRequest, UpdateUserTenantLinkRequest, ChannelInstallation, ChannelInstallationType, CreateChannelInstallationRequest, UpdateChannelInstallationRequest, Binding, CreateBindingInput, A2AApiKeyRecord, CreateA2AApiKeyInput, A2AApiKeyEntry, CreateTaskRequest, TaskItem, TaskListFilter, UpdateTaskRequest, Collection, CreateCollectionRequest, UpdateCollectionRequest, MenuItem, CreateMenuItemInput, UpdateMenuItemInput, STTModelLatticeProtocol, STTConfig, STTClient, TranscriptionResult, LoggerLatticeProtocol, LoggerConfig, LoggerClient, LoggerContext, SkillConfig, SkillClient, McpTool, ResourceResolver, ResourceAddress, ShareVisibility, CreateShareRequest, ChannelAdapter, PluginMeta, Plugin, PluginMetaOutput, InternalStateField, InternalInput, InternalNode, InternalAgentNode, InternalMapNode, InternalDSL, ConnectionEntry } from '@axiom-lattice/protocols';
+import { LLMConfig, SemanticMetricsServerConfig, MetricMeta, MetricQueryResult, DataSource, SemanticMetricsQueryRequest, SemanticMetricsQueryResponse, TableQueryRequest, TableQueryResponse, ExecuteSqlQueryRequest, ExecuteSqlQueryResponse, MetricsServerType, MetricsServerConfig, ToolConfig, ToolExecutor, AgentConfig, MiddlewareType, GraphBuildOptions, MessageChunk, MessageChunkType, QueueLatticeProtocol, QueueConfig, QueueClient, QueueResult, ScheduleLatticeProtocol, ScheduleConfig, ScheduleClient, ScheduleStorage, TaskHandler, ScheduleOnceOptions, ScheduleCronOptions, ScheduledTaskDefinition, ScheduledTaskStatus, ScheduleExecutionType, ThreadStore, AssistantStore, SkillStore, CollectionStore, WorkspaceStore, ProjectStore, DatabaseConfigStore, MetricsServerConfigStore, McpServerConfigStore, UserStore, TenantStore, UserTenantLinkStore, WorkflowTrackingStore, EvalStore, ChannelInstallationStore, BindingRegistry, MenuRegistry, A2AApiKeyStore, TaskStore, SharedResourceStore, ConnectionStore, TaskWorkItemStore, VectorStoreProvider, Thread, CreateThreadRequest, Assistant, CreateAssistantRequest, Skill, CreateSkillRequest, SkillStoreContext, DatabaseConfigEntry, CreateDatabaseConfigRequest, UpdateDatabaseConfigRequest, User, CreateUserRequest, UpdateUserRequest, Tenant, CreateTenantRequest, UpdateTenantRequest, UserTenantLink, CreateUserTenantLinkRequest, UpdateUserTenantLinkRequest, ChannelInstallation, ChannelInstallationType, CreateChannelInstallationRequest, UpdateChannelInstallationRequest, Binding, CreateBindingInput, A2AApiKeyRecord, CreateA2AApiKeyInput, A2AApiKeyEntry, CreateTaskRequest, TaskItem, TaskListFilter, UpdateTaskRequest, Collection, CreateCollectionRequest, UpdateCollectionRequest, MenuItem, CreateMenuItemInput, UpdateMenuItemInput, STTModelLatticeProtocol, STTConfig, STTClient, TranscriptionResult, LoggerLatticeProtocol, LoggerConfig, LoggerClient, LoggerContext, SkillConfig, SkillClient, McpTool, ResourceResolver, ResourceAddress, ShareVisibility, CreateShareRequest, ChannelAdapter, InterruptPolicy, PluginMeta, Plugin, PluginMetaOutput, InternalStateField, InternalInput, InternalNode, InternalAgentNode, InternalMapNode, InternalDSL, ConnectionEntry } from '@axiom-lattice/protocols';
 export { _axiom_lattice_protocols as Protocols };
 export { AgentConfig, AgentType, GraphBuildOptions, MemoryType } from '@axiom-lattice/protocols';
 import * as langchain from 'langchain';
@@ -5276,100 +5276,6 @@ declare function setBindingRegistry(r: BindingRegistry): void;
  */
 declare function getBindingRegistry(): BindingRegistry;
 
-/**
- * Service contract for controlling evaluation runs.
- *
- * The gateway layer implements this interface and registers it via
- * {@link setEvalRunService} so that agent tools (e.g., `run_eval`) can
- * start, abort, and monitor evaluation runs without knowing the
- * underlying run-time infrastructure.
- *
- * @see {@link setEvalRunService}
- * @see {@link getEvalRunService}
- */
-interface EvalRunService {
-    /**
-     * Start a new evaluation run for the given project.
-     *
-     * @param tenantId - Tenant that owns the project
-     * @param projectId - Project to evaluate
-     * @param suiteIds - Optional suite filter — only these suites run.
-     *   Omit to run all suites. Used to keep the validation suite
-     *   untouched during the fix loop (hold-out isolation).
-     * @param caseIds - Optional case filter — only these cases run (across
-     *   the suites selected by `suiteIds`, or all suites if omitted).
-     *   Suites with no matching cases are skipped; an error is thrown if
-     *   no case matches at all.
-     * @param runConfig - Runtime environment (workspace/project) the eval
-     *   executes in. Comes from the CALLER's runConfig, NOT from the eval
-     *   project's targetServerConfig. Test cases are environment-agnostic;
-     *   the run environment is decided at run time.
-     * @returns The newly created run ID
-     */
-    startRun(tenantId: string, projectId: string, suiteIds?: string[], caseIds?: string[], runConfig?: {
-        workspaceId?: string;
-        projectId?: string;
-    }): Promise<string>;
-    /**
-     * Abort a running evaluation.
-     *
-     * @param runId - The run to abort
-     * @returns `true` if the run was successfully aborted
-     */
-    abortRun(runId: string): Promise<boolean>;
-    /**
-     * Check whether a run's runner process is still alive.
-     *
-     * @param runId - The run to check
-     * @returns `true` if the runner process is still active
-     */
-    isRunning(runId: string): boolean;
-}
-/**
- * Sets the global {@link EvalRunService} instance used by agent evaluation tools.
- *
- * The service enables the `run_eval` tool to start, abort, and monitor evaluation
- * runs. This must be called **at gateway startup** before any agent invocation that
- * expects `run_eval` to be functional.
- *
- * @example
- * ```ts
- * import { setEvalRunService } from "@axiom-lattice/core";
- *
- * const evalSvc: EvalRunService = {
- *   startRun: async (tid, pid) => { ... },
- *   abortRun: async (rid) => { ... },
- *   isRunning: (rid) => { ... },
- * };
- * setEvalRunService(evalSvc);
- * ```
- *
- * @param s - An {@link EvalRunService} implementation
- * @see {@link getEvalRunService}
- */
-declare function setEvalRunService(s: EvalRunService): void;
-/**
- * Returns the globally registered {@link EvalRunService}.
- *
- * Must be called **after** {@link setEvalRunService}. Used by the `run_eval`
- * tool to start, abort, and monitor evaluation runs.
- *
- * @returns The active {@link EvalRunService} instance
- * @throws {Error} If the service has not been initialized
- * @see {@link setEvalRunService}
- */
-declare function getEvalRunService(): EvalRunService;
-/**
- * Resets the global {@link EvalRunService} to `null`.
- *
- * Restricted to the `test` environment for test isolation only. Production
- * code must never call this function.
- *
- * @throws {Error} If `NODE_ENV` is not `"test"`
- * @see {@link setEvalRunService}
- */
-declare function clearEvalRunService(): void;
-
 interface LatticeAgentStepConfig {
     agent_id: string;
     override_message?: string;
@@ -5413,6 +5319,7 @@ interface LatticeEvalBatchReport {
         total_cases: number;
         passed_cases: number;
         failed_cases: number;
+        interrupted_cases: number;
         pass_rate: number;
     };
     suites: Array<{
@@ -5420,11 +5327,13 @@ interface LatticeEvalBatchReport {
         total_cases: number;
         passed_cases: number;
         failed_cases: number;
+        interrupted_cases?: number;
         cases: Array<{
             caseId: string;
             pass?: boolean;
             final_score?: number;
             error?: string;
+            interrupted?: boolean;
         }>;
     }>;
 }
@@ -5451,6 +5360,13 @@ interface LatticeEvalCase {
         content_assertion: string;
         eval_rubrics?: LatticeEvalRubric[];
     };
+    /**
+     * How HITL interrupts are handled for this case. Unset/stop: the case
+     * pauses and the judge evaluates the pause; auto-approve/auto-reject/
+     * canned-response: the runner resumes the agent to test the flow AFTER
+     * the human input.
+     */
+    interruptPolicy?: InterruptPolicy;
 }
 interface LatticeEvalCaseWithTemplate {
     caseId: string;
@@ -5465,6 +5381,7 @@ interface LatticeEvalCaseWithTemplate {
         content_assertion: string;
         eval_rubrics?: LatticeEvalRubric[];
     };
+    interruptPolicy?: InterruptPolicy;
 }
 interface LatticeEvalTemplate {
     templateId: string;
@@ -5489,12 +5406,30 @@ interface LatticeEvalResult {
     }[];
     summary: string;
     error?: string;
+    /**
+     * True when the agent-under-test requested human input (HITL interrupt)
+     * before producing a final answer. Such cases are NOT judged — they are
+     * neither pass nor fail.
+     */
+    interrupted?: boolean;
+    /** The HITL interrupt payload (LangGraph `__interrupt__[0]`). */
+    interrupt?: {
+        id?: string;
+        value?: unknown;
+    };
 }
 interface CaseRunResult {
     caseId: string;
     result?: LatticeEvalResult;
     error?: string;
     error_stack?: string;
+    /** True when the agent-under-test hit a HITL interrupt (case not judged). */
+    interrupted?: boolean;
+    /** The HITL interrupt payload. */
+    interrupt?: {
+        id?: string;
+        value?: unknown;
+    };
     duration_ms?: number;
     thread_id?: string;
     judge_thread_id?: string;
@@ -5508,6 +5443,114 @@ interface CaseRunResult {
     logs: LatticeEvalLogEvent[];
 }
 
+/**
+ * Service contract for controlling evaluation runs.
+ *
+ * The gateway layer implements this interface and registers it via
+ * {@link setEvalRunService} so that agent tools (e.g., `run_eval`) can
+ * start, abort, and monitor evaluation runs without knowing the
+ * underlying run-time infrastructure.
+ *
+ * @see {@link setEvalRunService}
+ * @see {@link getEvalRunService}
+ */
+interface EvalRunService {
+    /**
+     * Start a new evaluation run for the given project.
+     *
+     * @param tenantId - Tenant that owns the project
+     * @param projectId - Project to evaluate
+     * @param suiteIds - Optional suite filter — only these suites run.
+     *   Omit to run all suites. Used to keep the validation suite
+     *   untouched during the fix loop (hold-out isolation).
+     * @param caseIds - Optional case filter — only these cases run (across
+     *   the suites selected by `suiteIds`, or all suites if omitted).
+     *   Suites with no matching cases are skipped; an error is thrown if
+     *   no case matches at all.
+     * @param runConfig - Runtime environment (workspace/project) the eval
+     *   executes in. Comes from the CALLER's runConfig, NOT from the eval
+     *   project's targetServerConfig. Test cases are environment-agnostic;
+     *   the run environment is decided at run time.
+     * @returns The newly created run ID
+     */
+    startRun(tenantId: string, projectId: string, suiteIds?: string[], caseIds?: string[], runConfig?: {
+        workspaceId?: string;
+        projectId?: string;
+    }): Promise<string>;
+    /**
+     * Abort a running evaluation.
+     *
+     * @param runId - The run to abort
+     * @returns `true` if the run was successfully aborted
+     */
+    abortRun(runId: string): Promise<boolean>;
+    /**
+     * Wait for a run to reach a terminal state and return its batch report.
+     *
+     * Resolves when the run finishes (completed, failed, or aborted) and its
+     * status has been persisted to the store — the caller can then read the
+     * run and its results without polling. Enables synchronous tool execution
+     * (`run_eval start` with `wait: true`).
+     *
+     * @param runId - The run to wait for
+     * @returns The final batch report of the run
+     * @throws {Error} If the run is not tracked in this process's memory
+     *   (already finished and cleaned up, or owned by another gateway instance)
+     */
+    waitForRun(runId: string): Promise<LatticeEvalBatchReport>;
+    /**
+     * Check whether a run's runner process is still alive.
+     *
+     * @param runId - The run to check
+     * @returns `true` if the runner process is still active
+     */
+    isRunning(runId: string): boolean;
+}
+/**
+ * Sets the global {@link EvalRunService} instance used by agent evaluation tools.
+ *
+ * The service enables the `run_eval` tool to start, abort, and monitor evaluation
+ * runs. This must be called **at gateway startup** before any agent invocation that
+ * expects `run_eval` to be functional.
+ *
+ * @example
+ * ```ts
+ * import { setEvalRunService } from "@axiom-lattice/core";
+ *
+ * const evalSvc: EvalRunService = {
+ *   startRun: async (tid, pid) => { ... },
+ *   abortRun: async (rid) => { ... },
+ *   isRunning: (rid) => { ... },
+ * };
+ * setEvalRunService(evalSvc);
+ * ```
+ *
+ * @param s - An {@link EvalRunService} implementation
+ * @see {@link getEvalRunService}
+ */
+declare function setEvalRunService(s: EvalRunService): void;
+/**
+ * Returns the globally registered {@link EvalRunService}.
+ *
+ * Must be called **after** {@link setEvalRunService}. Used by the `run_eval`
+ * tool to start, abort, and monitor evaluation runs.
+ *
+ * @returns The active {@link EvalRunService} instance
+ * @throws {Error} If the service has not been initialized
+ * @see {@link setEvalRunService}
+ */
+declare function getEvalRunService(): EvalRunService;
+/**
+ * Resets the global {@link EvalRunService} to `null`.
+ *
+ * Restricted to the `test` environment for test isolation only. Production
+ * code must never call this function.
+ *
+ * @throws {Error} If `NODE_ENV` is not `"test"`
+ * @see {@link setEvalRunService}
+ */
+declare function clearEvalRunService(): void;
+
 interface JudgeVerdict {
     pass?: boolean;
     final_score?: number;
@@ -5547,11 +5590,8 @@ interface LatticeEvalConfig {
      */
     verbose?: boolean;
 }
-/**
- * LatticeEval class for evaluating Lattice evaluation cases.
- * Executes agents in-process via agentInstanceManager.
- */
 declare class LatticeEval {
+    /** Per-message and total budget for the trajectory text (chars). */
     private config;
     private verbose;
     private inMemoryLogs;
@@ -7632,7 +7672,10 @@ declare function createModelSelectorMiddleware(): AgentMiddleware;
  * to generate error ToolMessages and jump back to the model.
  *
  * Key Design Principles:
- * 1. Preserve all tool_calls in AIMessage (keep model's original intent)
+ * 1. Only keep unknown tool_calls in AIMessage (strip valid ones to prevent
+ *    dangling tool_calls — afterModel jumps to "model" and skips ToolNode, so
+ *    any preserved call without a ToolMessage would be rejected by
+ *    OpenAI/OneAPI with 400 "insufficient tool messages following tool_calls")
  * 2. Generate error ToolMessages for unknown tools (preserve tool_call_id mapping)
  * 3. Use jumpTo to loop back to model node (required for agent loop)
  * 4. ToolNode will skip tool calls that already have ToolMessages

package/dist/index.d.ts

@@ -8,7 +8,7 @@ import { BaseLanguageModelInput, LanguageModelLike } from '@langchain/core/langu
 import { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
 import { ChatResult } from '@langchain/core/outputs';
 import * as _axiom_lattice_protocols from '@axiom-lattice/protocols';
-import { LLMConfig, SemanticMetricsServerConfig, MetricMeta, MetricQueryResult, DataSource, SemanticMetricsQueryRequest, SemanticMetricsQueryResponse, TableQueryRequest, TableQueryResponse, ExecuteSqlQueryRequest, ExecuteSqlQueryResponse, MetricsServerType, MetricsServerConfig, ToolConfig, ToolExecutor, AgentConfig, MiddlewareType, GraphBuildOptions, MessageChunk, MessageChunkType, QueueLatticeProtocol, QueueConfig, QueueClient, QueueResult, ScheduleLatticeProtocol, ScheduleConfig, ScheduleClient, ScheduleStorage, TaskHandler, ScheduleOnceOptions, ScheduleCronOptions, ScheduledTaskDefinition, ScheduledTaskStatus, ScheduleExecutionType, ThreadStore, AssistantStore, SkillStore, CollectionStore, WorkspaceStore, ProjectStore, DatabaseConfigStore, MetricsServerConfigStore, McpServerConfigStore, UserStore, TenantStore, UserTenantLinkStore, WorkflowTrackingStore, EvalStore, ChannelInstallationStore, BindingRegistry, MenuRegistry, A2AApiKeyStore, TaskStore, SharedResourceStore, ConnectionStore, TaskWorkItemStore, VectorStoreProvider, Thread, CreateThreadRequest, Assistant, CreateAssistantRequest, Skill, CreateSkillRequest, SkillStoreContext, DatabaseConfigEntry, CreateDatabaseConfigRequest, UpdateDatabaseConfigRequest, User, CreateUserRequest, UpdateUserRequest, Tenant, CreateTenantRequest, UpdateTenantRequest, UserTenantLink, CreateUserTenantLinkRequest, UpdateUserTenantLinkRequest, ChannelInstallation, ChannelInstallationType, CreateChannelInstallationRequest, UpdateChannelInstallationRequest, Binding, CreateBindingInput, A2AApiKeyRecord, CreateA2AApiKeyInput, A2AApiKeyEntry, CreateTaskRequest, TaskItem, TaskListFilter, UpdateTaskRequest, Collection, CreateCollectionRequest, UpdateCollectionRequest, MenuItem, CreateMenuItemInput, UpdateMenuItemInput, STTModelLatticeProtocol, STTConfig, STTClient, TranscriptionResult, LoggerLatticeProtocol, LoggerConfig, LoggerClient, LoggerContext, SkillConfig, SkillClient, McpTool, ResourceResolver, ResourceAddress, ShareVisibility, CreateShareRequest, ChannelAdapter, PluginMeta, Plugin, PluginMetaOutput, InternalStateField, InternalInput, InternalNode, InternalAgentNode, InternalMapNode, InternalDSL, ConnectionEntry } from '@axiom-lattice/protocols';
+import { LLMConfig, SemanticMetricsServerConfig, MetricMeta, MetricQueryResult, DataSource, SemanticMetricsQueryRequest, SemanticMetricsQueryResponse, TableQueryRequest, TableQueryResponse, ExecuteSqlQueryRequest, ExecuteSqlQueryResponse, MetricsServerType, MetricsServerConfig, ToolConfig, ToolExecutor, AgentConfig, MiddlewareType, GraphBuildOptions, MessageChunk, MessageChunkType, QueueLatticeProtocol, QueueConfig, QueueClient, QueueResult, ScheduleLatticeProtocol, ScheduleConfig, ScheduleClient, ScheduleStorage, TaskHandler, ScheduleOnceOptions, ScheduleCronOptions, ScheduledTaskDefinition, ScheduledTaskStatus, ScheduleExecutionType, ThreadStore, AssistantStore, SkillStore, CollectionStore, WorkspaceStore, ProjectStore, DatabaseConfigStore, MetricsServerConfigStore, McpServerConfigStore, UserStore, TenantStore, UserTenantLinkStore, WorkflowTrackingStore, EvalStore, ChannelInstallationStore, BindingRegistry, MenuRegistry, A2AApiKeyStore, TaskStore, SharedResourceStore, ConnectionStore, TaskWorkItemStore, VectorStoreProvider, Thread, CreateThreadRequest, Assistant, CreateAssistantRequest, Skill, CreateSkillRequest, SkillStoreContext, DatabaseConfigEntry, CreateDatabaseConfigRequest, UpdateDatabaseConfigRequest, User, CreateUserRequest, UpdateUserRequest, Tenant, CreateTenantRequest, UpdateTenantRequest, UserTenantLink, CreateUserTenantLinkRequest, UpdateUserTenantLinkRequest, ChannelInstallation, ChannelInstallationType, CreateChannelInstallationRequest, UpdateChannelInstallationRequest, Binding, CreateBindingInput, A2AApiKeyRecord, CreateA2AApiKeyInput, A2AApiKeyEntry, CreateTaskRequest, TaskItem, TaskListFilter, UpdateTaskRequest, Collection, CreateCollectionRequest, UpdateCollectionRequest, MenuItem, CreateMenuItemInput, UpdateMenuItemInput, STTModelLatticeProtocol, STTConfig, STTClient, TranscriptionResult, LoggerLatticeProtocol, LoggerConfig, LoggerClient, LoggerContext, SkillConfig, SkillClient, McpTool, ResourceResolver, ResourceAddress, ShareVisibility, CreateShareRequest, ChannelAdapter, InterruptPolicy, PluginMeta, Plugin, PluginMetaOutput, InternalStateField, InternalInput, InternalNode, InternalAgentNode, InternalMapNode, InternalDSL, ConnectionEntry } from '@axiom-lattice/protocols';
 export { _axiom_lattice_protocols as Protocols };
 export { AgentConfig, AgentType, GraphBuildOptions, MemoryType } from '@axiom-lattice/protocols';
 import * as langchain from 'langchain';
@@ -5276,100 +5276,6 @@ declare function setBindingRegistry(r: BindingRegistry): void;
  */
 declare function getBindingRegistry(): BindingRegistry;
 
-/**
- * Service contract for controlling evaluation runs.
- *
- * The gateway layer implements this interface and registers it via
- * {@link setEvalRunService} so that agent tools (e.g., `run_eval`) can
- * start, abort, and monitor evaluation runs without knowing the
- * underlying run-time infrastructure.
- *
- * @see {@link setEvalRunService}
- * @see {@link getEvalRunService}
- */
-interface EvalRunService {
-    /**
-     * Start a new evaluation run for the given project.
-     *
-     * @param tenantId - Tenant that owns the project
-     * @param projectId - Project to evaluate
-     * @param suiteIds - Optional suite filter — only these suites run.
-     *   Omit to run all suites. Used to keep the validation suite
-     *   untouched during the fix loop (hold-out isolation).
-     * @param caseIds - Optional case filter — only these cases run (across
-     *   the suites selected by `suiteIds`, or all suites if omitted).
-     *   Suites with no matching cases are skipped; an error is thrown if
-     *   no case matches at all.
-     * @param runConfig - Runtime environment (workspace/project) the eval
-     *   executes in. Comes from the CALLER's runConfig, NOT from the eval
-     *   project's targetServerConfig. Test cases are environment-agnostic;
-     *   the run environment is decided at run time.
-     * @returns The newly created run ID
-     */
-    startRun(tenantId: string, projectId: string, suiteIds?: string[], caseIds?: string[], runConfig?: {
-        workspaceId?: string;
-        projectId?: string;
-    }): Promise<string>;
-    /**
-     * Abort a running evaluation.
-     *
-     * @param runId - The run to abort
-     * @returns `true` if the run was successfully aborted
-     */
-    abortRun(runId: string): Promise<boolean>;
-    /**
-     * Check whether a run's runner process is still alive.
-     *
-     * @param runId - The run to check
-     * @returns `true` if the runner process is still active
-     */
-    isRunning(runId: string): boolean;
-}
-/**
- * Sets the global {@link EvalRunService} instance used by agent evaluation tools.
- *
- * The service enables the `run_eval` tool to start, abort, and monitor evaluation
- * runs. This must be called **at gateway startup** before any agent invocation that
- * expects `run_eval` to be functional.
- *
- * @example
- * ```ts
- * import { setEvalRunService } from "@axiom-lattice/core";
- *
- * const evalSvc: EvalRunService = {
- *   startRun: async (tid, pid) => { ... },
- *   abortRun: async (rid) => { ... },
- *   isRunning: (rid) => { ... },
- * };
- * setEvalRunService(evalSvc);
- * ```
- *
- * @param s - An {@link EvalRunService} implementation
- * @see {@link getEvalRunService}
- */
-declare function setEvalRunService(s: EvalRunService): void;
-/**
- * Returns the globally registered {@link EvalRunService}.
- *
- * Must be called **after** {@link setEvalRunService}. Used by the `run_eval`
- * tool to start, abort, and monitor evaluation runs.
- *
- * @returns The active {@link EvalRunService} instance
- * @throws {Error} If the service has not been initialized
- * @see {@link setEvalRunService}
- */
-declare function getEvalRunService(): EvalRunService;
-/**
- * Resets the global {@link EvalRunService} to `null`.
- *
- * Restricted to the `test` environment for test isolation only. Production
- * code must never call this function.
- *
- * @throws {Error} If `NODE_ENV` is not `"test"`
- * @see {@link setEvalRunService}
- */
-declare function clearEvalRunService(): void;
-
 interface LatticeAgentStepConfig {
     agent_id: string;
     override_message?: string;
@@ -5413,6 +5319,7 @@ interface LatticeEvalBatchReport {
         total_cases: number;
         passed_cases: number;
         failed_cases: number;
+        interrupted_cases: number;
         pass_rate: number;
     };
     suites: Array<{
@@ -5420,11 +5327,13 @@ interface LatticeEvalBatchReport {
         total_cases: number;
         passed_cases: number;
         failed_cases: number;
+        interrupted_cases?: number;
         cases: Array<{
             caseId: string;
             pass?: boolean;
             final_score?: number;
             error?: string;
+            interrupted?: boolean;
         }>;
     }>;
 }
@@ -5451,6 +5360,13 @@ interface LatticeEvalCase {
         content_assertion: string;
         eval_rubrics?: LatticeEvalRubric[];
     };
+    /**
+     * How HITL interrupts are handled for this case. Unset/stop: the case
+     * pauses and the judge evaluates the pause; auto-approve/auto-reject/
+     * canned-response: the runner resumes the agent to test the flow AFTER
+     * the human input.
+     */
+    interruptPolicy?: InterruptPolicy;
 }
 interface LatticeEvalCaseWithTemplate {
     caseId: string;
@@ -5465,6 +5381,7 @@ interface LatticeEvalCaseWithTemplate {
         content_assertion: string;
         eval_rubrics?: LatticeEvalRubric[];
     };
+    interruptPolicy?: InterruptPolicy;
 }
 interface LatticeEvalTemplate {
     templateId: string;
@@ -5489,12 +5406,30 @@ interface LatticeEvalResult {
     }[];
     summary: string;
     error?: string;
+    /**
+     * True when the agent-under-test requested human input (HITL interrupt)
+     * before producing a final answer. Such cases are NOT judged — they are
+     * neither pass nor fail.
+     */
+    interrupted?: boolean;
+    /** The HITL interrupt payload (LangGraph `__interrupt__[0]`). */
+    interrupt?: {
+        id?: string;
+        value?: unknown;
+    };
 }
 interface CaseRunResult {
     caseId: string;
     result?: LatticeEvalResult;
     error?: string;
     error_stack?: string;
+    /** True when the agent-under-test hit a HITL interrupt (case not judged). */
+    interrupted?: boolean;
+    /** The HITL interrupt payload. */
+    interrupt?: {
+        id?: string;
+        value?: unknown;
+    };
     duration_ms?: number;
     thread_id?: string;
     judge_thread_id?: string;
@@ -5508,6 +5443,114 @@ interface CaseRunResult {
     logs: LatticeEvalLogEvent[];
 }
 
+/**
+ * Service contract for controlling evaluation runs.
+ *
+ * The gateway layer implements this interface and registers it via
+ * {@link setEvalRunService} so that agent tools (e.g., `run_eval`) can
+ * start, abort, and monitor evaluation runs without knowing the
+ * underlying run-time infrastructure.
+ *
+ * @see {@link setEvalRunService}
+ * @see {@link getEvalRunService}
+ */
+interface EvalRunService {
+    /**
+     * Start a new evaluation run for the given project.
+     *
+     * @param tenantId - Tenant that owns the project
+     * @param projectId - Project to evaluate
+     * @param suiteIds - Optional suite filter — only these suites run.
+     *   Omit to run all suites. Used to keep the validation suite
+     *   untouched during the fix loop (hold-out isolation).
+     * @param caseIds - Optional case filter — only these cases run (across
+     *   the suites selected by `suiteIds`, or all suites if omitted).
+     *   Suites with no matching cases are skipped; an error is thrown if
+     *   no case matches at all.
+     * @param runConfig - Runtime environment (workspace/project) the eval
+     *   executes in. Comes from the CALLER's runConfig, NOT from the eval
+     *   project's targetServerConfig. Test cases are environment-agnostic;
+     *   the run environment is decided at run time.
+     * @returns The newly created run ID
+     */
+    startRun(tenantId: string, projectId: string, suiteIds?: string[], caseIds?: string[], runConfig?: {
+        workspaceId?: string;
+        projectId?: string;
+    }): Promise<string>;
+    /**
+     * Abort a running evaluation.
+     *
+     * @param runId - The run to abort
+     * @returns `true` if the run was successfully aborted
+     */
+    abortRun(runId: string): Promise<boolean>;
+    /**
+     * Wait for a run to reach a terminal state and return its batch report.
+     *
+     * Resolves when the run finishes (completed, failed, or aborted) and its
+     * status has been persisted to the store — the caller can then read the
+     * run and its results without polling. Enables synchronous tool execution
+     * (`run_eval start` with `wait: true`).
+     *
+     * @param runId - The run to wait for
+     * @returns The final batch report of the run
+     * @throws {Error} If the run is not tracked in this process's memory
+     *   (already finished and cleaned up, or owned by another gateway instance)
+     */
+    waitForRun(runId: string): Promise<LatticeEvalBatchReport>;
+    /**
+     * Check whether a run's runner process is still alive.
+     *
+     * @param runId - The run to check
+     * @returns `true` if the runner process is still active
+     */
+    isRunning(runId: string): boolean;
+}
+/**
+ * Sets the global {@link EvalRunService} instance used by agent evaluation tools.
+ *
+ * The service enables the `run_eval` tool to start, abort, and monitor evaluation
+ * runs. This must be called **at gateway startup** before any agent invocation that
+ * expects `run_eval` to be functional.
+ *
+ * @example
+ * ```ts
+ * import { setEvalRunService } from "@axiom-lattice/core";
+ *
+ * const evalSvc: EvalRunService = {
+ *   startRun: async (tid, pid) => { ... },
+ *   abortRun: async (rid) => { ... },
+ *   isRunning: (rid) => { ... },
+ * };
+ * setEvalRunService(evalSvc);
+ * ```
+ *
+ * @param s - An {@link EvalRunService} implementation
+ * @see {@link getEvalRunService}
+ */
+declare function setEvalRunService(s: EvalRunService): void;
+/**
+ * Returns the globally registered {@link EvalRunService}.
+ *
+ * Must be called **after** {@link setEvalRunService}. Used by the `run_eval`
+ * tool to start, abort, and monitor evaluation runs.
+ *
+ * @returns The active {@link EvalRunService} instance
+ * @throws {Error} If the service has not been initialized
+ * @see {@link setEvalRunService}
+ */
+declare function getEvalRunService(): EvalRunService;
+/**
+ * Resets the global {@link EvalRunService} to `null`.
+ *
+ * Restricted to the `test` environment for test isolation only. Production
+ * code must never call this function.
+ *
+ * @throws {Error} If `NODE_ENV` is not `"test"`
+ * @see {@link setEvalRunService}
+ */
+declare function clearEvalRunService(): void;
+
 interface JudgeVerdict {
     pass?: boolean;
     final_score?: number;
@@ -5547,11 +5590,8 @@ interface LatticeEvalConfig {
      */
     verbose?: boolean;
 }
-/**
- * LatticeEval class for evaluating Lattice evaluation cases.
- * Executes agents in-process via agentInstanceManager.
- */
 declare class LatticeEval {
+    /** Per-message and total budget for the trajectory text (chars). */
     private config;
     private verbose;
     private inMemoryLogs;
@@ -7632,7 +7672,10 @@ declare function createModelSelectorMiddleware(): AgentMiddleware;
  * to generate error ToolMessages and jump back to the model.
  *
  * Key Design Principles:
- * 1. Preserve all tool_calls in AIMessage (keep model's original intent)
+ * 1. Only keep unknown tool_calls in AIMessage (strip valid ones to prevent
+ *    dangling tool_calls — afterModel jumps to "model" and skips ToolNode, so
+ *    any preserved call without a ToolMessage would be rejected by
+ *    OpenAI/OneAPI with 400 "insufficient tool messages following tool_calls")
  * 2. Generate error ToolMessages for unknown tools (preserve tool_call_id mapping)
  * 3. Use jumpTo to loop back to model node (required for agent loop)
  * 4. ToolNode will skip tool calls that already have ToolMessages