@genesislcap/ai-assistant 15.19.0 → 15.19.1

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

@@ -1,642 +0,0 @@
-import type {
-  CachePolicy,
-  ChatMessage,
-  ChatThinkingPolicy,
-  ChatToolChoice,
-  ChatToolDefinition,
-  ChatToolHandlers,
-} from '@genesislcap/foundation-ai';
-import { TOOL_FOLD_SYMBOL } from '../utils/tool-fold';
-import type {
-  AgentConfig,
-  AgentLifecycleContext,
-  AgentPersistenceContext,
-  CachePolicyInput,
-  ChatInputDuringExecutionMode,
-  ManualSelectionConfig,
-  ProviderInput,
-  SystemPromptContext,
-  SystemPromptInput,
-  TailContextInput,
-  TemperatureInput,
-  ThinkingPolicyInput,
-  ToolChoiceInput,
-  ToolDefinitionsInput,
-  ToolHandlersInput,
-  UnresolvedToolContext,
-  UnresolvedToolInput,
-} from './config';
-
-/**
- * Context passed to per-turn resolvers on a stateful agent — the standard
- * {@link SystemPromptContext} plus the live `state` value. Used by
- * `systemPrompt`, `displayName`, and the function form of `toolDefinitions`.
- *
- * Exported so consumers can lift resolvers into separate files without
- * re-deriving the shape.
- *
- * @beta
- */
-export type StatefulAgentContext<S> = SystemPromptContext & { state: S };
-
-/**
- * Context passed to a stateful agent's `resumable` predicate (GENC-1351 §5.9) —
- * the standard {@link AgentPersistenceContext} but with `state` as the **live**
- * state bag `S` (not the serialized image), so a machine agent can gate on its
- * current step directly.
- *
- * @beta
- */
-export type StatefulAgentPersistenceContext<S> = Omit<AgentPersistenceContext, 'state'> & {
-  state: S;
-};
-
-/**
- * Init options for {@link defineStatefulAgent}. Generic over the state shape `S`
- * the agent owns (a state machine, an observable controller, anything).
- *
- * The helper threads `state` through `systemPrompt`, `toolDefinitions`, and the
- * `toolHandlers` factory so consumer code never has to reach for a closure or
- * a module-level mutable.
- *
- * @beta
- */
-export interface StatefulAgentInit<S> {
-  /** Display name — must be unique within the agents array. */
-  name: string;
-  /** Plain-language description used by the classifier. Required: stateful agents are always specialists. */
-  description: string;
-  /**
-   * Hide this agent from the classifier — only reachable via manual pinning.
-   * Stateful agents are always specialists; they cannot be the fallback (a
-   * fallback is a leaf invoked when no specialist matches, with no flow to
-   * own state for).
-   */
-  excludeFromClassifier?: boolean;
-  /** Static primer history prepended to every call (not visible to the user). */
-  primerHistory?: ChatMessage[];
-  /** Sub-agents available to this agent's tool handlers via `requestSubAgent`. */
-  subAgents?: AgentConfig[];
-  /** Opt this agent in to manual picker selection. */
-  manualSelection?: ManualSelectionConfig;
-  /** How the main chat input behaves while this agent is executing. */
-  chatInputDuringExecution?: ChatInputDuringExecutionMode;
-
-  /**
-   * Construct the agent-scoped state. Called by the framework when this agent
-   * becomes active (`onActivate`). Awaited before the agent's first turn runs.
-   *
-   * On a persisted-session restore, `ctx.restored` carries this agent's previous
-   * `serialize` output — rebuild from it (e.g. via `restoreMachine`), or start
-   * fresh when it is `undefined`.
-   */
-  init: (ctx: AgentLifecycleContext) => S | Promise<S>;
-
-  /**
-   * Tear down the agent-scoped state. Called when the agent is being replaced.
-   * Awaited before the incoming agent's `init` runs.
-   */
-  dispose?: (ctx: AgentLifecycleContext & { state: S }) => void | Promise<void>;
-
-  /**
-   * System prompt composed from current state. Resolved each tool-loop
-   * iteration. Use this to feed the LLM whatever the current state implies
-   * (e.g. a state machine's `meta.systemPrompt` plus captured context).
-   */
-  systemPrompt?: (ctx: StatefulAgentContext<S>) => string | Promise<string>;
-
-  /**
-   * Per-turn display label, e.g. "Guided Booking (Counterparties)". Resolved
-   * each tool-loop iteration and stamped onto outgoing messages and the
-   * debug-log timeline — display only. The agent's `name` stays as the
-   * canonical identity used for routing/history filtering.
-   */
-  displayName?: (ctx: StatefulAgentContext<S>) => string | Promise<string>;
-
-  /**
-   * Tool definitions the LLM sees. Either a static array (resolved once) or a
-   * function resolved each tool-loop iteration. The function form is how a
-   * machine-driven agent narrows the surface per state.
-   *
-   * **Constraint:** the resolved handlers (returned from {@link StatefulAgentInit.toolHandlers})
-   * must not include fold facades. Folds are an LLM-driven UX optimisation
-   * that competes with the machine for control of the tool view; one of them
-   * has to be in charge. Helper throws at init time if a fold-tagged handler
-   * is detected.
-   */
-  toolDefinitions?:
-    | ChatToolDefinition[]
-    | ((ctx: StatefulAgentContext<S>) => ChatToolDefinition[] | Promise<ChatToolDefinition[]>);
-
-  /**
-   * Factory returning the handler map for the **current state**. Called each
-   * tool-loop iteration with the live `state` value, so the handler set the
-   * driver dispatches against matches what `toolDefinitions` exposes to the
-   * LLM that turn. Return only the handlers valid right now — no need to
-   * advertise every handler the agent might ever expose, and no defensive
-   * `if (!machine.matches(...))` guards inside each handler.
-   *
-   * Pair with the function form of `toolDefinitions` so the visible tools and
-   * the dispatchable handlers stay in lockstep.
-   *
-   * **Constraint:** resolved handlers must not include fold facades. Folds and
-   * state-machine-driven tool filtering both try to control the LLM's tool
-   * view — pick one. Helper samples once on activation (init state) and
-   * throws if a fold-tagged handler is detected; subsequent resolves also
-   * validate, so misuse on a non-init state surfaces when that state is
-   * reached.
-   */
-  toolHandlers?: (state: S) => ChatToolHandlers | Promise<ChatToolHandlers>;
-
-  /**
-   * Which registered AI provider this agent uses, by name. Either a static
-   * string or a function resolved each tool-loop iteration with the current
-   * `state` — pick the function form to vary provider per machine state
-   * (e.g. swap to a heavier model only for the planning step).
-   *
-   * Omit to use the registry's default provider. Unknown names hard-error.
-   */
-  provider?: string | ((ctx: StatefulAgentContext<S>) => string | Promise<string>);
-
-  /**
-   * Sampling temperature, normalized to `0`–`1`. Either a static number or a
-   * function resolved each tool-loop iteration with the current `state` — pick
-   * the function form to vary it per machine state (e.g. low for a precise
-   * extraction step, higher for free-form drafting). Omit for the default.
-   */
-  temperature?: number | ((ctx: StatefulAgentContext<S>) => number | Promise<number>);
-
-  /**
-   * Tool-call mode. Either a static `ChatToolChoice` or a function
-   * resolved each tool-loop iteration with the current `state` — pick the
-   * function form to force a specific tool in one state (e.g. a classifier in
-   * intake) and leave `'auto'` in states where multi-step work happens. Omit
-   * for the default.
-   */
-  toolChoice?:
-    | ChatToolChoice
-    | ((ctx: StatefulAgentContext<S>) => ChatToolChoice | Promise<ChatToolChoice>);
-
-  /**
-   * Prompt-cache policy. Either a static `CachePolicy` or a function resolved each tool-loop
-   * iteration with the current `state` — pick the function form to vary it per machine state
-   * (e.g. `'history'` in a long generating phase, `'default'` in short low-touch ones). Omit to
-   * request no caching.
-   */
-  cachePolicy?:
-    | CachePolicy
-    | ((ctx: StatefulAgentContext<S>) => CachePolicy | Promise<CachePolicy>);
-
-  /**
-   * Extended-thinking posture. Either a static `ChatThinkingPolicy` or a function resolved with
-   * the current `state` **once per user turn** — the function form is the point of this option on
-   * a machine agent: `'auto'` in the state that makes a real decision, `'off'` in the states that
-   * only step a known sequence, where reasoning is billed at the full output rate to re-derive
-   * what the machine already knows. Omit, or return `undefined` from the function, to keep the
-   * model's own default for that turn.
-   *
-   * Resolved once per turn rather than per tool-loop iteration (unlike `temperature` and
-   * `toolChoice`): a tool-use loop is one assistant turn and its thinking mode must hold for the
-   * whole of it. A state transition part-way through a loop therefore takes effect on the next
-   * user turn, not immediately.
-   */
-  thinkingPolicy?:
-    | ChatThinkingPolicy
-    | ((
-        ctx: StatefulAgentContext<S>,
-      ) => ChatThinkingPolicy | undefined | Promise<ChatThinkingPolicy | undefined>);
-
-  /**
-   * Volatile per-turn tail context (current file/spec, diagnostics, live state). Either a static
-   * string or a function resolved each tool-loop iteration with the current `state`. Provide raw
-   * content; the framework frames it. Omit, or return an empty string, for none.
-   */
-  tailContext?: string | ((ctx: StatefulAgentContext<S>) => string | Promise<string>);
-
-  /**
-   * Hook consulted when the model calls a tool that isn't dispatchable in the
-   * current state — a *stale* tool (valid in an earlier state of this agent) or
-   * an *unknown* one. Receives the current `state` alongside the attempted tool
-   * name and the currently dispatchable tools, so a machine-driven agent can
-   * return a step-aware redirect (e.g. "that belongs to a later step — finish
-   * this one first"). Return `undefined` to keep the framework default; a
-   * pre-init call also degrades to the default rather than throwing.
-   * See {@link UnresolvedToolContext}.
-   */
-  onUnresolvedTool?: (
-    ctx: UnresolvedToolContext & { state: S },
-  ) => string | undefined | Promise<string | undefined>;
-
-  /**
-   * Optional getter for the debug-log snapshot. Defaults to auto-snapshotting
-   * any property on `state` that looks like a foundation-state-machine
-   * instance (has `state`, `context`, and `complete` fields). Override when
-   * the default doesn't capture what you need — e.g. multiple machines, or
-   * non-machine state worth recording.
-   *
-   * Return value must be JSON-serializable.
-   */
-  getDebugSnapshot?: (state: S) => unknown;
-
-  /**
-   * Lossless serializer for session persistence — infra-agnostic. Return any
-   * JSON/structured-clone-safe image of `state`.
-   *   • Machine agents (`{ machine }`): omit — the default snapshots every
-   *     machine-shaped property via `getPersistedSnapshot()`.
-   *   • Plain-data agents (e.g. `{ plan, cursor }`): omit too — the default
-   *     returns plain state as-is. Provide one only when the state holds
-   *     something the default can't capture.
-   * Distinct from `getDebugSnapshot` (which may be lossy by design). Pair with
-   * `init` reading `ctx.restored` to rebuild.
-   */
-  serialize?: (state: S) => unknown;
-
-  /**
-   * Whether the agent's current state is resumable — worth persisting so the
-   * session restores mid-flow (GENC-1351 §5.9). Receives the **live** state bag
-   * `S` (like the other per-turn resolvers), so a machine agent gates on its step
-   * directly: `resumable: ({ state }) => state.machine.state !== 'confirm'`.
-   * Return `false` for a point that shouldn't resume — the session isn't persisted,
-   * and on return the assistant shows {@link StatefulAgentInit.notResumableMessage}
-   * (or a default) and pre-fills the composer with the prompt that started the flow.
-   * Only consulted with persistence enabled; a thrown error is treated as `true`
-   * (fail-safe — never drop a resumable chat on a predicate bug).
-   */
-  resumable?: (ctx: StatefulAgentPersistenceContext<S>) => boolean | Promise<boolean>;
-  /**
-   * Message shown on return when {@link StatefulAgentInit.resumable} returned
-   * `false`. Falls back to a built-in default when omitted.
-   */
-  notResumableMessage?: string;
-}
-
-/**
- * Walk a state object and snapshot any machine-shaped values found on it.
- * Recognises foundation-state-machine instances by structural shape rather
- * than `instanceof`, so the helper stays free of a runtime dep on
- * foundation-state-machine.
- *
- * Strips the `errors`/`error` framework noise from each machine's context —
- * these are foundation-state-machine internals (an ErrorMap instance and its
- * last-error pointer) that bloat the debug payload without aiding debugging.
- */
-function defaultStatefulDebugSnapshot(state: unknown): unknown {
-  if (!state || typeof state !== 'object') return state;
-  const result: Record<string, unknown> = {};
-  for (const [key, val] of Object.entries(state as Record<string, unknown>)) {
-    if (val && typeof val === 'object' && 'state' in val && 'context' in val && 'complete' in val) {
-      const m = val as {
-        state: unknown;
-        context: Record<string, unknown>;
-        complete: unknown;
-        output?: unknown;
-      };
-      const ctx = m.context ?? {};
-      const { errors: _e, error: _err, ...userContext } = ctx;
-      result[key] = {
-        state: m.state,
-        context: userContext,
-        complete: m.complete,
-        output: m.output,
-      };
-    }
-  }
-  return Object.keys(result).length
-    ? result
-    : '<no auto-snapshot — state has no machine-shaped properties; provide getDebugSnapshot>';
-}
-
-/**
- * Build a restore-ready snapshot of agent state. Each property exposing a
- * `getPersistedSnapshot()` method (a foundation-state-machine `AbstractMachine`)
- * is replaced by its persisted snapshot — the lossless, JSON-safe image
- * {@link restoreMachine} feeds back via `start({ state })`. Every other property
- * is kept as-is, so plain serializable state (e.g. a planner's `{ plan, cursor }`)
- * round-trips directly with no per-agent `serialize`.
- *
- * Distinct from `defaultStatefulDebugSnapshot`, which abbreviates for the debug
- * log and is not guaranteed lossless.
- */
-function defaultStatefulSerialize(state: unknown): unknown {
-  if (!state || typeof state !== 'object') return state;
-  const result: Record<string, unknown> = {};
-  for (const [key, val] of Object.entries(state as Record<string, unknown>)) {
-    result[key] =
-      val &&
-      typeof val === 'object' &&
-      typeof (val as { getPersistedSnapshot?: unknown }).getPersistedSnapshot === 'function'
-        ? (val as { getPersistedSnapshot: () => unknown }).getPersistedSnapshot()
-        : val;
-  }
-  return result;
-}
-
-/**
- * Restore a foundation-state-machine instance from a snapshot produced by the
- * default serializer (or `machine.getPersistedSnapshot()`). Call inside a
- * stateful agent's `init` to resume the machine in its exact prior place:
- *
- * ```ts
- * init: ({ restored }) => {
- *   const machine = new MyMachine();
- *   restoreMachine(machine, restored); // resume, or no-op on a fresh start
- *   return { machine };
- * }
- * ```
- *
- * No-ops when there is nothing to restore (a fresh session), leaving the
- * freshly-constructed machine in its initial state.
- *
- * @param machine - the machine to restore (already constructed/started).
- * @param restored - the agent's serialized image (`ctx.restored` in `init`).
- * @param key - the property the machine occupies in the snapshot; defaults to
- *   `'machine'` to match the conventional `{ machine }` state bag.
- * @beta
- */
-export function restoreMachine(
-  machine: { stop: () => void; start: (options?: { state?: unknown }) => void },
-  restored: unknown,
-  key = 'machine',
-): void {
-  const snapshot = (restored as Record<string, unknown> | undefined)?.[key];
-  if (snapshot === undefined || snapshot === null) {
-    return;
-  }
-  machine.stop();
-  machine.start({ state: snapshot });
-}
-
-/**
- * Build an `AgentConfig` whose `systemPrompt`, `toolDefinitions`, and tool
- * handlers all close over a long-lived state object created on activation.
- *
- * The framework wires the lifecycle: `init` on `onActivate`, `dispose` on
- * `onDeactivate`. State is held inside the helper's closure — never exposed on
- * the resulting `AgentConfig` — so the redux serializer doesn't see it.
- *
- * @example
- * ```ts
- * const guidedBooking = defineStatefulAgent<{ machine: GuidedBookingMachine }>({
- *   name: 'Guided Booking',
- *   description: 'Books a trade via a guided wizard.',
- *   excludeFromClassifier: true,
- *   manualSelection: { enabled: true, hint: 'Step-by-step trade booking' },
- *   init: () => ({ machine: new GuidedBookingMachine() }),
- *   dispose: ({ state }) => state.machine.stop(),
- *   systemPrompt: ({ state }) => composeFromMachine(state.machine),
- *   toolDefinitions: ({ state }) => toolsForState(state.machine.state),
- *   toolHandlers: ({ machine }) => ({ ... }),
- * });
- * ```
- *
- * @beta
- */
-export function defineStatefulAgent<S>(opts: StatefulAgentInit<S>): AgentConfig {
-  let state: S | undefined;
-
-  const assertNoFolds = (handlers: ChatToolHandlers): void => {
-    for (const [name, handler] of Object.entries(handlers)) {
-      if ((handler as any)[TOOL_FOLD_SYMBOL]) {
-        throw new Error(
-          `Stateful agent "${opts.name}" tool "${name}" carries fold metadata. ` +
-            `Folds and state-machine-driven tool filtering both try to control the ` +
-            `LLM's tool view — pick one. Remove the fold or migrate this agent to ` +
-            `a non-stateful AgentConfig.`,
-        );
-      }
-    }
-  };
-
-  // Wrap the optional dynamic-tools factory so it threads `state` in and asserts
-  // we never accidentally resolved a fold-tagged tool. Static arrays are passed
-  // through unchanged.
-  const wrappedTools: ToolDefinitionsInput | undefined = (() => {
-    const td = opts.toolDefinitions;
-    if (typeof td === 'function') {
-      return async (ctx: SystemPromptContext) => {
-        if (!state) {
-          throw new Error(`Stateful agent "${opts.name}" tools called before init`);
-        }
-        return td({ ...ctx, state });
-      };
-    }
-    return td;
-  })();
-
-  // Wrap the handler factory into the ctx-shaped form the driver expects, and
-  // validate folds on each resolve. The driver re-resolves this per tool-loop
-  // iteration, so the handler set the driver dispatches against always
-  // matches the LLM-visible tools for the current state — handlers don't need
-  // defensive `if (!machine.matches(...))` guards.
-  const wrappedHandlers: ToolHandlersInput | undefined = opts.toolHandlers
-    ? async () => {
-        if (!state) {
-          throw new Error(`Stateful agent "${opts.name}" handlers called before init`);
-        }
-        const handlers = await opts.toolHandlers!(state);
-        assertNoFolds(handlers);
-        return handlers;
-      }
-    : undefined;
-
-  const wrappedDisplayName: SystemPromptInput | undefined = opts.displayName
-    ? async (ctx: SystemPromptContext) => {
-        if (!state) {
-          throw new Error(`Stateful agent "${opts.name}" displayName called before init`);
-        }
-        return opts.displayName!({ ...ctx, state });
-      }
-    : undefined;
-
-  // Function-form `provider` needs `state` injected the same way the other
-  // per-turn resolvers do; the static-string form is passed through unchanged
-  // and validated up-front by OrchestratingDriver.
-  const wrappedProvider: ProviderInput | undefined =
-    typeof opts.provider === 'function'
-      ? async (ctx: SystemPromptContext) => {
-          if (!state) {
-            throw new Error(`Stateful agent "${opts.name}" provider called before init`);
-          }
-          return (opts.provider as (ctx: StatefulAgentContext<S>) => string | Promise<string>)({
-            ...ctx,
-            state,
-          });
-        }
-      : opts.provider;
-
-  // `temperature` and `toolChoice` thread `state` in exactly like `provider`;
-  // static values pass through unchanged.
-  const wrappedTemperature: TemperatureInput | undefined =
-    typeof opts.temperature === 'function'
-      ? async (ctx: SystemPromptContext) => {
-          if (!state) {
-            throw new Error(`Stateful agent "${opts.name}" temperature called before init`);
-          }
-          return (opts.temperature as (ctx: StatefulAgentContext<S>) => number | Promise<number>)({
-            ...ctx,
-            state,
-          });
-        }
-      : opts.temperature;
-
-  const wrappedToolChoice: ToolChoiceInput | undefined =
-    typeof opts.toolChoice === 'function'
-      ? async (ctx: SystemPromptContext) => {
-          if (!state) {
-            throw new Error(`Stateful agent "${opts.name}" toolChoice called before init`);
-          }
-          return (
-            opts.toolChoice as (
-              ctx: StatefulAgentContext<S>,
-            ) => ChatToolChoice | Promise<ChatToolChoice>
-          )({ ...ctx, state });
-        }
-      : opts.toolChoice;
-
-  const wrappedCachePolicy: CachePolicyInput | undefined =
-    typeof opts.cachePolicy === 'function'
-      ? async (ctx: SystemPromptContext) => {
-          if (!state) {
-            throw new Error(`Stateful agent "${opts.name}" cachePolicy called before init`);
-          }
-          return (
-            opts.cachePolicy as (ctx: StatefulAgentContext<S>) => CachePolicy | Promise<CachePolicy>
-          )({ ...ctx, state });
-        }
-      : opts.cachePolicy;
-
-  // Unlike the resolvers above, a pre-init call returns `undefined` rather than throwing: that is
-  // this option's "model default" state, so degrading to it costs a turn its thinking preference
-  // instead of breaking the turn outright.
-  const wrappedThinkingPolicy: ThinkingPolicyInput | undefined =
-    typeof opts.thinkingPolicy === 'function'
-      ? async (ctx: SystemPromptContext) => {
-          if (!state) return undefined;
-          return (
-            opts.thinkingPolicy as (
-              ctx: StatefulAgentContext<S>,
-            ) => ChatThinkingPolicy | undefined | Promise<ChatThinkingPolicy | undefined>
-          )({ ...ctx, state });
-        }
-      : opts.thinkingPolicy;
-
-  const wrappedTailContext: TailContextInput | undefined =
-    typeof opts.tailContext === 'function'
-      ? async (ctx: SystemPromptContext) => {
-          if (!state) {
-            throw new Error(`Stateful agent "${opts.name}" tailContext called before init`);
-          }
-          return (opts.tailContext as (ctx: StatefulAgentContext<S>) => string | Promise<string>)({
-            ...ctx,
-            state,
-          });
-        }
-      : opts.tailContext;
-
-  // `onUnresolvedTool` threads `state` in like the resolvers above, but unlike
-  // them returns `undefined` before init rather than throwing: it fires on the
-  // tool-dispatch path, so a pre-init call must degrade to the framework
-  // default instead of breaking dispatch.
-  const wrappedOnUnresolvedTool: UnresolvedToolInput | undefined =
-    typeof opts.onUnresolvedTool === 'function'
-      ? async (ctx) => {
-          if (!state) {
-            return undefined;
-          }
-          return opts.onUnresolvedTool!({ ...ctx, state });
-        }
-      : opts.onUnresolvedTool;
-
-  // `resumable` threads the LIVE state bag in (like the resolvers above) rather
-  // than the serialized image the raw `AgentConfig` form receives — so a machine
-  // agent gates on `state.machine.state` directly. Consulted only while active
-  // (state is set); a pre-init call degrades to `true` (resumable, fail-safe).
-  const wrappedResumable: AgentConfig['resumable'] | undefined = opts.resumable
-    ? async (ctx: AgentPersistenceContext): Promise<boolean> => {
-        if (state === undefined) return true;
-        return opts.resumable!({
-          agentName: ctx.agentName,
-          sessionKey: ctx.sessionKey,
-          messages: ctx.messages,
-          isFlowOwner: ctx.isFlowOwner,
-          state,
-        });
-      }
-    : undefined;
-
-  const base = {
-    name: opts.name,
-    displayName: wrappedDisplayName,
-    primerHistory: opts.primerHistory,
-    subAgents: opts.subAgents,
-    manualSelection: opts.manualSelection,
-    chatInputDuringExecution: opts.chatInputDuringExecution,
-    toolDefinitions: wrappedTools,
-    toolHandlers: wrappedHandlers,
-    provider: wrappedProvider,
-    temperature: wrappedTemperature,
-    toolChoice: wrappedToolChoice,
-    cachePolicy: wrappedCachePolicy,
-    thinkingPolicy: wrappedThinkingPolicy,
-    tailContext: wrappedTailContext,
-    onUnresolvedTool: wrappedOnUnresolvedTool,
-    resumable: wrappedResumable,
-    notResumableMessage: opts.notResumableMessage,
-
-    onActivate: async (ctx: AgentLifecycleContext) => {
-      state = await opts.init(ctx);
-      // Sample once with the init state to fail loud on fold misuse at the
-      // agent-switch boundary instead of waiting for the first tool call.
-      // The driver re-resolves the factory each iteration, so misuse on
-      // handlers gated behind a non-init state surfaces when that state is
-      // reached — same loud failure mode, narrower coverage.
-      if (opts.toolHandlers) {
-        const sampled = await opts.toolHandlers(state);
-        assertNoFolds(sampled);
-      }
-    },
-
-    onDeactivate: async (ctx: AgentLifecycleContext) => {
-      if (state !== undefined && opts.dispose) {
-        await opts.dispose({ ...ctx, state });
-      }
-      // Orchestrator serializes onActivate/onDeactivate; concurrent calls
-      // cannot interleave the read-then-write of `state`.
-      // eslint-disable-next-line require-atomic-updates
-      state = undefined;
-    },
-
-    systemPrompt: opts.systemPrompt
-      ? async (ctx: SystemPromptContext) => {
-          if (!state) {
-            throw new Error(`Stateful agent "${opts.name}" systemPrompt called before init`);
-          }
-          return opts.systemPrompt!({ ...ctx, state });
-        }
-      : undefined,
-
-    // Called per LLM call by ChatDriver, and once at debug-log export time.
-    // Returns `undefined` before activation (state hasn't been built yet) and
-    // after deactivation (state was disposed) — the snapshotter is best-effort
-    // and the driver tolerates undefined.
-    getDebugSnapshot: () => {
-      if (!state) return undefined;
-      return opts.getDebugSnapshot
-        ? opts.getDebugSnapshot(state)
-        : defaultStatefulDebugSnapshot(state);
-    },
-
-    // Lossless restore image for session persistence (see `serialize` on the
-    // config). Returns undefined before activation / after disposal.
-    serialize: () => {
-      if (state === undefined) return undefined;
-      return opts.serialize ? opts.serialize(state) : defaultStatefulSerialize(state);
-    },
-  };
-
-  return {
-    ...base,
-    description: opts.description,
-    excludeFromClassifier: opts.excludeFromClassifier,
-  } as AgentConfig;
-}

package/src/config/fallback-agents.ts

@@ -1,29 +0,0 @@
-import type { FallbackAgentConfig } from './config';
-
-/**
- * A warm, conversational fallback agent. Acknowledges it can't help directly,
- * explains what the available specialists can do, and invites the user to retry.
- *
- * The system prompt is generated at runtime by `OrchestratingDriver` from the
- * specialist list — no manual authoring required.
- *
- * @beta
- */
-export const friendlyFallbackAgent: FallbackAgentConfig = {
-  name: 'Assistant',
-  fallback: true,
-  systemPrompt: `You are a warm, friendly assistant. For general conversation like "Hi" or "How are you", you can have a friendly chat. For anything more complex, you cannot directly help, but you can explain what specialists are available. The available specialists are:\n\n{{agents}}\n\nPolitely let the user know what you can help with and invite them to rephrase their request if it is outside your scope.`,
-};
-
-/**
- * A brief, professional fallback agent. States what is available without
- * elaboration. The `{{agents}}` placeholder is replaced at runtime by
- * `OrchestratingDriver` with the generated specialist list.
- *
- * @beta
- */
-export const strictFallbackAgent: FallbackAgentConfig = {
-  name: 'Assistant',
-  fallback: true,
-  systemPrompt: `You are a concise assistant. The user's request is outside your scope. Respond with a single short sentence stating what you can assist with. Do not elaborate. The available specialists are: {{agents}}.`,
-};

package/src/config/index.ts

@@ -1,2 +0,0 @@
-export * from './config';
-export * from './fallback-agents';