@genesislcap/ai-assistant 15.19.0 → 15.19.1

package/src/config/config.ts

@@ -1,608 +0,0 @@
-import type {
-  CachePolicy,
-  ChatFallback,
-  ChatInputDuringExecutionMode,
-  ChatMessage,
-  ChatThinkingPolicy,
-  ChatToolChoice,
-  ChatToolDefinition,
-  ChatToolHandlers,
-} from '@genesislcap/foundation-ai';
-
-export type {
-  CachePolicy,
-  ChatFallback,
-  ChatInputDuringExecutionMode,
-  ChatThinkingPolicy,
-  ChatToolChoice,
-};
-
-/**
- * Context passed to `onActivate` / `onDeactivate` lifecycle hooks on an agent.
- *
- * @beta
- */
-export interface AgentLifecycleContext {
-  /** The agent the hook is firing for. */
-  agentName: string;
-  /** The assistant session key — stable across reloads, unique per assistant instance. */
-  sessionKey: string;
-  /** The agent that was active immediately before this one, if any. Only set on `onActivate`. */
-  previousAgentName?: string;
-  /** Aborted if the session disconnects mid-activation. */
-  signal: AbortSignal;
-  /**
-   * A previously-serialized state image for this agent (from the agent's
-   * `serialize`), passed only on `onActivate` when resuming a persisted
-   * session. A stateful
-   * agent's `init` rebuilds from it — e.g. via `restoreMachine` — or starts
-   * fresh when it is `undefined`.
-   */
-  restored?: unknown;
-}
-
-/**
- * Context passed to an agent's `resumable` predicate (GENC-1351 §5.9), evaluated
- * at session-save time on the active agent (which, for a locked guided flow, is
- * the flow-owner).
- *
- * @beta
- */
-export interface AgentPersistenceContext {
-  /** The agent being consulted. */
-  agentName: string;
-  /** The assistant session key — stable across reloads. */
-  sessionKey: string;
-  /**
-   * This agent's just-serialized state image — the value its `serialize()`
-   * returned for this save (or the carried-forward image). Inspect the machine
-   * step here. Derive the decision from this (not live closure state): the
-   * predicate must be a pure function of the state so a resumable snapshot stays
-   * resumable when re-evaluated on restore.
-   */
-  state: unknown;
-  /** Full conversation transcript at save time. */
-  messages: ReadonlyArray<ChatMessage>;
-  /** True when this agent currently owns the guided flow (`name === flowOwnerAgentName`). */
-  isFlowOwner: boolean;
-}
-
-/**
- * Context passed to the function form of `systemPrompt` / `toolDefinitions`.
- * Resolved each tool-loop iteration so the agent can vary what the LLM sees per turn.
- *
- * @beta
- */
-export interface SystemPromptContext {
-  /** The active agent's name. */
-  agentName: string;
-  /** Full conversation history up to (but not including) the message being processed. */
-  history: ReadonlyArray<ChatMessage>;
-  /** 0 = first LLM call this turn; > 0 = retry or subsequent tool-loop iteration. */
-  turnIndex: number;
-  /** Aborted if the turn is cancelled. */
-  signal: AbortSignal;
-}
-
-/**
- * System prompt for an agent. Either a static string (resolved once) or a function
- * resolved each tool-loop iteration. The function form lets the agent compute the
- * prompt from external state — e.g. a state machine's current step.
- *
- * @beta
- */
-export type SystemPromptInput = string | ((ctx: SystemPromptContext) => string | Promise<string>);
-
-/**
- * Tool definitions for an agent. Either a static array (the conventional shape) or
- * a function resolved each tool-loop iteration. The function form lets the agent
- * narrow the tool surface per turn — e.g. expose only the tools valid in the
- * current state of a state machine.
- *
- * @beta
- */
-export type ToolDefinitionsInput =
-  | ChatToolDefinition[]
-  | ((ctx: SystemPromptContext) => ChatToolDefinition[] | Promise<ChatToolDefinition[]>);
-
-/**
- * Tool handlers for an agent. Either a static map (the conventional shape) or a
- * function resolved each tool-loop iteration. The function form lets the agent
- * narrow the dispatchable handler set per turn — pair it with the function form
- * of `toolDefinitions` so the LLM-visible tools and the dispatchable handlers
- * stay in lockstep, and handlers don't have to defend themselves against being
- * dispatched in states where their tool isn't advertised.
- *
- * @beta
- */
-export type ToolHandlersInput =
-  | ChatToolHandlers
-  | ((ctx: SystemPromptContext) => ChatToolHandlers | Promise<ChatToolHandlers>);
-
-/**
- * Names which registered `AIProviderRegistry` entry an agent uses. Either
- * a static string (resolved once at agent registration) or a function resolved
- * each tool-loop iteration — pick the function form to vary the provider by
- * current state (e.g. a stateful agent that switches providers between
- * machine states).
- *
- * Unknown provider names hard-error: static names at agent registration time,
- * function-resolved names on first resolution.
- *
- * @beta
- */
-export type ProviderInput = string | ((ctx: SystemPromptContext) => string | Promise<string>);
-
-/**
- * Sampling temperature for an agent, normalized to `0`–`1` (`0` = deterministic,
- * `1` = the most random the active provider allows). Either a static number
- * (resolved once) or a function resolved each tool-loop iteration — pick the
- * function form to vary it by current state (e.g. a lower temperature for a
- * precise extraction step, higher for brainstorming). Each transport translates
- * the normalized value into its own native range. Omit to use the
- * provider/model default. See `ChatRequestOptions.temperature`.
- *
- * @beta
- */
-export type TemperatureInput = number | ((ctx: SystemPromptContext) => number | Promise<number>);
-
-/**
- * Tool-call mode for an agent. Either a static `ChatToolChoice` (resolved
- * once) or a function resolved each tool-loop iteration — pick the function form
- * to vary it by current state (e.g. force a classifier tool in an intake step,
- * then `'auto'` everywhere multi-step work happens). Omit to use the default
- * (`'auto'`, except sub-agent turns which force `'required'`).
- *
- * @beta
- */
-export type ToolChoiceInput =
-  | ChatToolChoice
-  | ((ctx: SystemPromptContext) => ChatToolChoice | Promise<ChatToolChoice>);
-
-/**
- * Prompt-cache policy for an agent. Either a static `CachePolicy` (resolved once) or a
- * function resolved each tool-loop iteration — pick the function form to vary it by current state
- * (e.g. cache `'history'` in a long generating phase, `'default'` in short low-touch ones). Omit
- * to request no caching. Resolved and applied the same way as {@link TemperatureInput}.
- *
- * @beta
- */
-export type CachePolicyInput =
-  | CachePolicy
-  | ((ctx: SystemPromptContext) => CachePolicy | Promise<CachePolicy>);
-
-/**
- * Extended-thinking posture for an agent — whether the model reasons before answering. Either a
- * static `ChatThinkingPolicy` or a function resolved **once per user turn**, at the start of the
- * tool loop. Pick the function form to vary it by current state: reason in the state that makes a
- * real decision, and drop it in states that only step a known sequence, where reasoning bills at
- * the full output rate to re-derive what the state machine already knows.
- *
- * Note the resolution point, which differs from every other per-turn input here: a tool-use loop
- * is a single assistant turn and its thinking mode must hold for the whole of it, so this resolver
- * is consulted on the first model call of a turn and its answer reused for the rest. A resolver
- * that returns a different value part-way through a loop will not see it applied until the next
- * user turn.
- *
- * **Omit — or return `undefined` from the function — to keep the model's own default**, which is
- * a distinct third state rather than a synonym for either value: Sonnet 5 and Fable 5 think by
- * default, the rest do not. So an agent that leaves this unset, or a resolver that answers
- * `undefined` on some turns, behaves and prices exactly as it did before this option existed.
- *
- * A request, not a guarantee — transports clamp what a model cannot honour (Fable 5 and Gemini
- * 2.5 Pro always think) and warn once instead of failing the turn. Resolved and applied the same
- * way as {@link TemperatureInput}. See `ChatThinkingPolicy`.
- *
- * @beta
- */
-export type ThinkingPolicyInput =
-  | ChatThinkingPolicy
-  | ((
-      ctx: SystemPromptContext,
-    ) => ChatThinkingPolicy | undefined | Promise<ChatThinkingPolicy | undefined>);
-
-/**
- * Per-turn tail context for an agent — volatile content (current file/spec, diagnostics, live
- * state) injected at the tail of every model-call so the model sees it without invalidating the
- * cached prefix. Either a static string or a function resolved each tool-loop iteration. **Provide
- * raw content** — the framework frames it (wraps it in a `<system-reminder>` marker) so the model
- * reads it as ambient context, not user input. Omit, or return an empty string, for none.
- *
- * @beta
- */
-export type TailContextInput = string | ((ctx: SystemPromptContext) => string | Promise<string>);
-
-/**
- * Structured-output schema for an agent. When set, the model's final (non-tool) answer is
- * constrained to this JSON Schema instead of free text. Either a static schema or a function
- * resolved each tool-loop iteration — return the schema on the turn(s) it should apply and
- * `undefined` otherwise, so "whole-loop" vs "finalize-turn" enforcement is just what the
- * resolver returns (e.g. `({ state }) => state.machine.matches('finalizing') ? schema : undefined`).
- *
- * Orthogonal to {@link ToolChoiceInput}: an agent can carry both `tools` and a `responseSchema`.
- * Each provider applies it natively where possible (Anthropic `output_config.format`, Gemini
- * JSON mode) and degrades gracefully otherwise. The schema is a plain JSON Schema object; keep to
- * the portable subset providers share (`additionalProperties: false`, explicit `required`, enums,
- * `anyOf` for nullables — no numeric/string constraints or recursion).
- *
- * @beta
- */
-export type ResponseSchemaInput =
-  | object
-  | ((ctx: SystemPromptContext) => object | undefined | Promise<object | undefined>);
-
-/**
- * Context passed to an agent's `onUnresolvedTool` hook when the model calls a
- * tool the driver cannot dispatch.
- *
- * @beta
- */
-export interface UnresolvedToolContext {
-  /** The tool name the model attempted to call. */
-  toolName: string;
-  /**
-   * Why the call could not be dispatched:
-   * - `'stale'` — the tool was advertised earlier this activation but is not
-   *   part of the current step (e.g. a stateful agent has moved on).
-   * - `'unknown'` — the tool was never advertised this activation (a
-   *   hallucinated name).
-   */
-  kind: 'stale' | 'unknown';
-  /**
-   * The tool names dispatchable right now, so the hook can steer the model
-   * back to a valid call.
-   */
-  availableTools: string[];
-}
-
-/**
- * Optional per-agent hook consulted only on the already-failing unresolved-tool
- * path — when the model calls a tool the driver cannot dispatch. Lets the agent
- * replace the framework's default message with a context-aware redirect.
- *
- * Return a non-empty string to override the default tool-result message; return
- * `undefined` (or an empty/whitespace string, or throw) to fall back to the
- * framework default. The happy path is never affected. See
- * {@link UnresolvedToolContext}.
- *
- * @beta
- */
-export type UnresolvedToolInput = (
-  ctx: UnresolvedToolContext,
-) => string | undefined | Promise<string | undefined>;
-
-/**
- * Opts an agent in to manual selection from the assistant's agent picker.
- *
- * Only applies to top-level agents — sub-agents are never user-selectable.
- * Has no effect unless the assistant's `agentPicker` is also enabled.
- *
- * @beta
- */
-export interface ManualSelectionConfig {
-  /**
-   * Whether this agent appears in the picker.
-   */
-  enabled: boolean;
-  /**
-   * Optional short description shown as a tooltip on the picker entry, and as
-   * a secondary line in the dropdown variant.
-   */
-  hint?: string;
-}
-
-interface BaseAgentConfig {
-  /**
-   * Stable identity for this agent. Used for classifier routing, manual
-   * pinning, and history filtering — must not vary per turn. For a per-turn
-   * display label (e.g. "Guided Booking (Counterparties)"), supply
-   * {@link BaseAgentConfig.displayName}.
-   */
-  name: string;
-  /**
-   * Optional per-turn display label. Resolved each tool-loop iteration and
-   * stamped onto outgoing messages (`agentLabel`) and the debug-log timeline.
-   * Renderers fall back to `name` when this is unset. Use the function form
-   * to vary the label by current state (e.g. a state machine's step).
-   *
-   * Identity stays on `name` — this is for UX only.
-   */
-  displayName?: SystemPromptInput;
-  /**
-   * System prompt injected into every conversation turn for this agent.
-   *
-   * Either a string (resolved once) or a function resolved each tool-loop
-   * iteration — pick the function form when the prompt depends on per-turn state
-   * (e.g. a state machine's current step). See {@link SystemPromptInput}.
-   */
-  systemPrompt?: SystemPromptInput;
-  /**
-   * Tool definitions (JSON Schema) passed to the AI provider for this agent.
-   *
-   * Either a static array or a function resolved each tool-loop iteration —
-   * pick the function form to narrow the tool surface per turn (e.g. expose
-   * only the tools valid in the current state of a state machine).
-   * See {@link ToolDefinitionsInput}.
-   */
-  toolDefinitions?: ToolDefinitionsInput;
-  /**
-   * Tool handler implementations for this agent.
-   *
-   * Either a static map or a function resolved each tool-loop iteration —
-   * pick the function form to narrow the dispatchable handler set per turn,
-   * matching the function form of `toolDefinitions`.
-   * See {@link ToolHandlersInput}.
-   */
-  toolHandlers?: ToolHandlersInput;
-  /**
-   * Which registered AI provider this agent uses, by name. Either a static
-   * string (resolved once at agent registration) or a function resolved each
-   * tool-loop iteration — pick the function form to vary the provider by
-   * current state (e.g. a stateful agent that switches providers between
-   * machine states).
-   *
-   * Omit to use the registry's default provider. Unknown names hard-error:
-   * static names at registration time, function-resolved names on first
-   * resolution.
-   *
-   * Known limitation: switching provider mid-conversation can blow the
-   * smaller provider's context window if history accumulated under a
-   * larger one. No automatic trimming is performed.
-   *
-   * @beta
-   */
-  provider?: ProviderInput;
-  /**
-   * Sampling temperature for this agent, normalized to `0`–`1`. Either a static
-   * number or a function resolved each tool-loop iteration — pick the function
-   * form to vary it by current state. Omit to use the provider/model default.
-   * Resolved and applied the same way as {@link BaseAgentConfig.provider}.
-   * See {@link TemperatureInput}.
-   *
-   * @beta
-   */
-  temperature?: TemperatureInput;
-  /**
-   * Tool-call mode for this agent — whether the model may, must, or must not
-   * call a tool this turn (and optionally which one). Either a static value or
-   * a function resolved each tool-loop iteration — pick the function form to
-   * vary it by current state (e.g. force a single tool at a known juncture).
-   * Omit to use the default (`'auto'`, except sub-agent turns which force
-   * `'required'`). See {@link ToolChoiceInput}.
-   *
-   * @beta
-   */
-  toolChoice?: ToolChoiceInput;
-  /**
-   * Prompt-cache policy for this agent — whether to emit cache breakpoints and how far up the
-   * prefix. Either a static value or a function resolved each tool-loop iteration (vary by state).
-   * Resolved and applied the same way as {@link BaseAgentConfig.temperature}. Omit to request no
-   * caching. Provider-neutral — see {@link CachePolicyInput} / `CachePolicy` for the
-   * Anthropic-vs-Gemini behaviour. See {@link CachePolicyInput}.
-   *
-   * @beta
-   */
-  cachePolicy?: CachePolicyInput;
-  /**
-   * Extended-thinking posture for this agent — whether the model reasons before answering. Either
-   * a static value or a function resolved **once per user turn** and held for that turn's whole
-   * tool loop (vary by state: `'auto'` where the turn is a genuine decision, `'off'` where it only
-   * steps a known sequence and reasoning is billed at the full output rate for no benefit). Omit —
-   * or return `undefined` — to keep the model's own default, which is neither `'auto'` nor `'off'`
-   * uniformly. Provider-neutral; transports clamp models that cannot honour it.
-   * See {@link ThinkingPolicyInput}.
-   *
-   * @beta
-   */
-  thinkingPolicy?: ThinkingPolicyInput;
-  /**
-   * Volatile per-turn context injected at the tail of every model-call (after the history and any
-   * cache breakpoint), so it is seen each turn without busting the cached prefix — the place to put
-   * the changing parts (current file/spec, diagnostics, live state) that would otherwise
-   * destabilize a cached system prompt. Provide *raw* content; the framework frames it (wraps it in
-   * a `<system-reminder>` marker). Resolved per turn like {@link BaseAgentConfig.temperature}. See
-   * {@link TailContextInput}.
-   *
-   * @beta
-   */
-  tailContext?: TailContextInput;
-  /**
-   * Structured-output schema for this agent. When resolved to a schema on a turn, the model's
-   * final (non-tool) answer is constrained to it instead of free text. Composes with `tools`;
-   * resolved per turn like {@link BaseAgentConfig.cachePolicy}, so returning `undefined` on
-   * working turns and the schema on the finalize turn gives finalize-turn enforcement for free.
-   * See {@link ResponseSchemaInput}.
-   *
-   * @beta
-   */
-  responseSchema?: ResponseSchemaInput;
-  /**
-   * Refusal-fallback chain for this agent (provider-neutral). If the model declines a turn
-   * (`stop_reason: 'refusal'` — e.g. Fable 5 safety classifiers), the provider re-runs it on the
-   * next listed model. Typical use: a Fable 5 agent with `[{ model: 'claude-opus-4-8' }]`. Static
-   * (not per-turn); providers that support it apply it server-side, others ignore it.
-   *
-   * @beta
-   */
-  fallbacks?: ChatFallback[];
-  /**
-   * Optional hook consulted when the model calls a tool the driver cannot
-   * dispatch — either a *stale* tool (advertised earlier this activation but
-   * not part of the current step) or an *unknown* one (never advertised this
-   * activation). Return a context-aware redirect string to replace the
-   * framework's default message, or `undefined` to keep it. Consulted only on
-   * the already-failing unresolved-tool path; the happy path is unaffected.
-   * See {@link UnresolvedToolInput}.
-   *
-   * @beta
-   */
-  onUnresolvedTool?: UnresolvedToolInput;
-  /**
-   * Optional primer history prepended to every call (not visible to the user).
-   * Used to establish agent identity and behavioural rules.
-   */
-  primerHistory?: ChatMessage[];
-  /**
-   * Sub-agents available to this agent's tool handlers via `requestSubAgent`.
-   */
-  subAgents?: AgentConfig[];
-  /**
-   * How the main chat input area behaves while this agent is executing.
-   * Defaults to `'disabled'`. See {@link ChatInputDuringExecutionMode}.
-   */
-  chatInputDuringExecution?: ChatInputDuringExecutionMode;
-  /**
-   * Opts this agent in to manual selection from the assistant's agent picker.
-   * Has no effect on sub-agents or when the assistant's `agentPicker` is
-   * disabled. See {@link ManualSelectionConfig}.
-   */
-  manualSelection?: ManualSelectionConfig;
-  /**
-   * Fires when this agent becomes the active specialist (including being pinned).
-   * Use to instantiate per-agent state that should outlive a single turn — e.g.
-   * a state machine the agent owns across the conversation. Awaited before the
-   * agent's first turn runs.
-   *
-   * Capture dependencies (services, redux store refs, etc.) via closure on the
-   * host element rather than expecting them on the context.
-   *
-   * @beta
-   */
-  onActivate?: (ctx: AgentLifecycleContext) => void | Promise<void>;
-  /**
-   * Fires when this agent is being deactivated (the user switches to another
-   * agent, the session is torn down, or the agent is unpinned and replaced).
-   * Use to dispose per-agent state created in `onActivate`. Awaited before the
-   * incoming agent's `onActivate` runs.
-   *
-   * @beta
-   */
-  onDeactivate?: (ctx: AgentLifecycleContext) => void | Promise<void>;
-  /**
-   * Returns an agent-supplied debug payload for the export log. Called once per
-   * LLM call by the driver (alongside the resolved prompt and tool list) and
-   * once at log-export time for the latest snapshot. Stateful agents should
-   * return their machine state and captured context so the exported timeline
-   * captures what drove each turn.
-   *
-   * Return value must be JSON-serializable. {@link defineStatefulAgent} wires a
-   * sensible default that snapshots any machine-shaped state automatically.
-   *
-   * @beta
-   */
-  getDebugSnapshot?: () => unknown;
-  /**
-   * Returns a lossless, JSON-serializable image of the agent's state for session
-   * persistence — distinct from `getDebugSnapshot`, which may abbreviate for
-   * readability. Pass the value back to the agent on restore (as
-   * `ctx.restored` in its `init`) to resume. {@link defineStatefulAgent} wires a
-   * default that snapshots any machine-shaped state via `getPersistedSnapshot()`
-   * and returns plain state as-is.
-   *
-   * @beta
-   */
-  serialize?: () => unknown;
-  /**
-   * Whether the agent's current state is resumable — i.e. worth persisting so the
-   * session can be restored mid-flow (GENC-1351 §5.9). Consulted at save time on
-   * the active agent (the flow-owner during a locked flow). Return `true`
-   * (or leave the field absent) to persist and resume normally; return `false`
-   * for a point that shouldn't be resumed — the session is not persisted, and on
-   * return the assistant shows {@link AgentConfig.notResumableMessage} (or a
-   * default) and pre-fills the composer with the prompt that started the flow so
-   * the user can re-run it.
-   *
-   * Only consulted when the user has persistence enabled. Must be a **pure
-   * function of `ctx.state`** — it may be re-evaluated on a restored snapshot, so
-   * a resumable state must stay resumable. A thrown error is treated as `true`
-   * (fail-safe: never drop a resumable chat on a predicate bug).
-   *
-   * @beta
-   */
-  resumable?: (ctx: AgentPersistenceContext) => boolean | Promise<boolean>;
-  /**
-   * Message shown on return when {@link AgentConfig.resumable} returned `false`
-   * and the user comes back to a non-resumable session (GENC-1351 §5.9). Falls
-   * back to a built-in default when omitted.
-   *
-   * @beta
-   */
-  notResumableMessage?: string;
-}
-
-/**
- * Configuration for a specialist agent.
- *
- * Specialist agents are offered to the classifier for intent routing. The
- * `description` is used to auto-generate the classifier prompt — no manual
- * routing prompt authoring required.
- *
- * @beta
- */
-export interface SpecialistAgentConfig extends BaseAgentConfig {
-  /**
-   * Plain-language description of what this agent handles.
-   * Used by the classifier to auto-generate its routing prompt.
-   */
-  description: string;
-  fallback?: never;
-  /**
-   * When `true`, the classifier never auto-routes to this agent. The user can
-   * still select it manually via the picker, provided both prerequisites are
-   * met: this agent has `manualSelection.enabled` set to `true`, *and* the
-   * assistant has the picker enabled via `chatConfig.picker.mode`.
-   *
-   * Use this for agents that overlap heavily with a sibling (e.g. a guided
-   * wizard sitting next to a free-form agent in the same domain) and should
-   * only be reached intentionally rather than via classifier routing.
-   *
-   * @beta
-   */
-  excludeFromClassifier?: boolean;
-}
-
-/**
- * Configuration for a fallback agent.
- *
- * Invoked when the classifier returns no match. Excluded from the classifier
- * prompt. Only one fallback is permitted per agents array.
- *
- * @beta
- */
-export interface FallbackAgentConfig extends BaseAgentConfig {
-  /**
-   * Marks this agent as the fallback for unrecognised requests.
-   */
-  fallback: true;
-  description?: never;
-}
-
-/**
- * Configuration for an agent passed to `FoundationAiAssistant`.
- *
- * Either a specialist (requires `description`) or a fallback (requires
- * `fallback: true`). Passing both or neither is a compile error.
- *
- * @beta
- */
-export type AgentConfig = SpecialistAgentConfig | FallbackAgentConfig;
-
-/**
- * Identity helper that infers the narrowest possible type for an agent config,
- * preserving string literal types (including `name`) without requiring `as const`.
- *
- * Use this when you need `typeof myAgent` to carry the literal `name` type —
- * for example, when wiring `ChatToolHandlers<typeof myAgent>`.
- *
- * ```ts
- * const myAgent = defineAgent({ name: 'my_agent', ... });
- * type Handlers = ChatToolHandlers<typeof myAgent>;
- * // requestSubAgent name param is now typed as 'my_agent'
- * ```
- *
- * @beta
- */
-
-export function defineAgent<const T extends AgentConfig>(config: T): T {
-  return config;
-}

package/src/config/define-stateful-agent.test.ts

@@ -1,64 +0,0 @@
-import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
-import type { AgentLifecycleContext } from './config';
-import { defineStatefulAgent } from './define-stateful-agent';
-
-// A minimal lifecycle context — `onActivate`/`onDeactivate` only read what the
-// helper passes through, so the agent name, session key, and a live signal are
-// enough to drive init/dispose in a Node-runnable test.
-const lifecycleCtx = (): AgentLifecycleContext => ({
-  agentName: 'wizard',
-  sessionKey: 'test-session',
-  signal: new AbortController().signal,
-});
-
-const onUnresolvedTool = createLogicSuite('defineStatefulAgent onUnresolvedTool');
-
-onUnresolvedTool('threads the live state into the hook after init', async () => {
-  const config = defineStatefulAgent<{ step: string }>({
-    name: 'wizard',
-    description: 'guided wizard',
-    init: () => ({ step: 'intake' }),
-    onUnresolvedTool: ({ state, toolName, kind, availableTools }) =>
-      `step=${state.step} tool=${toolName} kind=${kind} avail=${availableTools.join(',')}`,
-  });
-
-  await config.onActivate!(lifecycleCtx());
-
-  const result = await config.onUnresolvedTool!({
-    toolName: 'generate_view',
-    kind: 'stale',
-    availableTools: ['ask_user', 'validate'],
-  });
-  assert.is(result, 'step=intake tool=generate_view kind=stale avail=ask_user,validate');
-});
-
-onUnresolvedTool('returns undefined before init rather than throwing', async () => {
-  const config = defineStatefulAgent<{ step: string }>({
-    name: 'wizard',
-    description: 'guided wizard',
-    init: () => ({ step: 'intake' }),
-    // Would throw if it were ever reached without state — proves the wrapper
-    // short-circuits before delegating.
-    onUnresolvedTool: ({ state }) => `step=${state.step}`,
-  });
-
-  // No `onActivate` call — state has not been built yet.
-  const result = await config.onUnresolvedTool!({
-    toolName: 'generate_view',
-    kind: 'unknown',
-    availableTools: [],
-  });
-  assert.is(result, undefined, 'a pre-init call must degrade to the framework default');
-});
-
-onUnresolvedTool('omits the hook from the config when not supplied', () => {
-  const config = defineStatefulAgent<{ step: string }>({
-    name: 'wizard',
-    description: 'guided wizard',
-    init: () => ({ step: 'intake' }),
-  });
-
-  assert.is(config.onUnresolvedTool, undefined);
-});
-
-onUnresolvedTool.run();