@ziggs-ai/agent-sdk 0.1.12 → 0.2.1

package/src/AgentHost.ts

@@ -1,814 +0,0 @@
-import type { AgentConfig, Ctx, EffectHandler, Identity, Workflow } from './types.js';
-import { Agent } from './agent/Agent.js';
-import { ClaudeSdkAgent, type CognitionKind } from './agent/ClaudeSdkAgent.js';
-import { CLAUDE_SDK_TOOLS } from './agent/claudeSdkTools.js';
-import { resolveClaudeModel } from './agent/claudeCognition.js';
-
-export type { CognitionKind };
-import { EventQueue } from './server/EventQueue.js';
-import { StateTimers } from './server/StateTimers.js';
-import { createZiggsEffectHandler } from './server/ZiggsEffectHandler.js';
-import { normalizeIncomingEvent, type NormalizedEvent } from './ingress/normalizeIncoming.js';
-import { PromptBuilder } from './runtime/PromptBuilder.js';
-import { InMemoryStore, type MemoryStore } from './memory/MemoryStore.js';
-
-/**
- * Operator-provided FSM session persistence.
- *
- * AgentHost calls load() before each tick when a lane has no in-memory state
- * (e.g. after a container restart) and save() after every successful tick.
- * A null return from load() means "no prior state — start fresh."
- */
-export interface SessionStore {
-  load(laneKey: string): Promise<{ ctx?: Ctx; state?: string } | null | undefined>;
-  save(laneKey: string, session: { ctx?: Ctx; state?: string }): Promise<void>;
-}
-import { ToolManager } from './tools/ToolManager.js';
-import type { ToolDefinition } from './tools/defineTool.js';
-import { PROTOCOL_TOOLS } from './server/tools/tier1/protocolTools.js';
-import { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
-import { AnthropicAdapter } from './adapters/AnthropicAdapter.js';
-import {
-  WebSocketClient,
-  ArtifactsClient,
-  ContextReadClient,
-  TelemetryClient,
-  InboxClient,
-  type MessageMetadata,
-} from '@ziggs-ai/api-client';
-import { TaskService } from './server/tasks/TaskService.js';
-import { AgreementService } from './server/agreements/AgreementService.js';
-import { runInboxCatchUp } from './server/InboxCatchUp.js';
-import { SeenMessages } from './server/SeenMessages.js';
-import { runtimeLog } from './shared/runtimeLog.js';
-
-/**
- * The single fleet-wide default model — the one place the fallback lives.
- * Change this (or set `LLM_MODEL`) to move the whole fleet; nothing hardcodes a
- * model anywhere else. The id also picks the provider: a `claude-*` value routes
- * to AnthropicAdapter (+ ANTHROPIC_API_KEY), anything else to OpenAIAdapter — see
- * the `model?.startsWith('claude')` branch in createBackendServices below.
- */
-export const DEFAULT_MODEL = 'claude-haiku-4-5';
-
-// ConnectionPool lives in a separate module; resolved via a computed-path
-// dynamic import to avoid a circular import with AgentHost.
-async function loadConnectionPool(): Promise<new (opts?: { maxActive?: number; idleTimeoutMs?: number }) => unknown> {
-  const modPath = './server/ConnectionPool.js';
-  const mod = await import(/* @vite-ignore */ modPath) as { ConnectionPool: new (opts?: { maxActive?: number; idleTimeoutMs?: number }) => unknown };
-  return mod.ConnectionPool;
-}
-
-/**
- * Given a normalized event, return the sessionId for this agent. Return
- * `null` to skip processing. Lets each Agent define what "session" means —
- * chat-scoped agents bucket by chatId (the default), task-scoped agents
- * could bucket by taskId, cron agents by schedule id, etc.
- */
-export type SessionResolver = (normalized: NormalizedEvent, ownAgentId: string) => string | null;
-
-const DEFAULT_SESSION_RESOLVER: SessionResolver = (normalized) => normalized.chatId;
-
-interface LlmAdapter {
-  chatMessages(messages: unknown[], tools?: unknown[], options?: Record<string, unknown>): Promise<unknown>;
-}
-
-interface AgentServices {
-  tools?: ToolDefinition[];
-  llm?: { model?: string } | LlmAdapter;
-  [key: string]: unknown;
-}
-
-
-export interface AgentHostOptions {
-  openaiKey?: string;
-  anthropicKey?: string;
-  model?: string;
-  operatorKey?: string;
-  agentId?: string;
-  name?: string | null;
-  wsUrl?: string;
-  description?: string;
-  specialization?: string | null;
-  tools?: ToolDefinition[];
-  taskTools?: 'all' | 'none' | string[];
-  /** Cognition runtime: FSM (default) or Claude Agent SDK headless delegate. */
-  cognition?: CognitionKind;
-  /** Max agentic turns per Claude SDK wake. Default 30. */
-  claudeMaxTurns?: number;
-  services?: AgentServices;
-  workflow?: Workflow;
-  // Convenience: states + initial without an explicit workflow.
-  states?: Workflow['states'];
-  initial?: string;
-  tickTimeoutMs?: number;
-  /** Per-agent session keying. Defaults to `(n) => n.chatId`. */
-  sessionResolver?: SessionResolver;
-  /**
-   * Agent-private long-term memory. Operator-provided. Default: a fresh
-   * `InMemoryStore` (non-durable; lost on process restart). For durability,
-   * pass `new FileMemoryStore(path)` or your own implementation.
-   */
-  memory?: MemoryStore;
-  /**
-   * FSM session persistence. Operator-provided. When set, AgentHost loads
-   * prior state before each tick (cold-start recovery) and saves after every
-   * successful tick. Omit to keep state in-process only (default behaviour).
-   */
-  sessionStore?: SessionStore;
-  /** Observability tap: called after every effect with the effect and its response. */
-  effectTap?: (effect: import('./types.js').Effect, response: unknown) => void;
-  /** Observability tap: called on every FSM state transition, no-match, depth-guard, or error-escape (ZIG-442). */
-  transitionTap?: (event: import('./runtime/AgentMachine.js').TransitionEvent) => void;
-  /**
-   * Usage/cost tap: called once per settled tick with the tick's authoritative
-   * token usage (result.metrics). This is the SINGLE source of truth for
-   * usage/cost across every cognition — the FSM (llm-call + streamed reply +
-   * tool-internal LLM) and the Claude brain (incl. cache tokens) both funnel
-   * their spend here (ZIG-813). effectTap / tool generations are structural
-   * tracing only and must NOT also carry billable usage, or cost double-counts.
-   */
-  metricsTap?: (info: {
-    agentId: string;
-    sessionId: string;
-    model: string;
-    cognition: string;
-    metrics: import('./agent/Agent.js').TickOutput['metrics'];
-  }) => void;
-  /** Production monitoring ingest (ZIG-360). Default on; set false to disable. */
-  telemetryIngest?: boolean;
-  /**
-   * Pull inbox on every WS connect/reconnect (ZIG-454). Default true.
-   * Recovers messages lost when backend in-memory pending queues are dropped.
-   */
-  inboxCatchUp?: boolean;
-}
-
-function createToolManager(options: AgentHostOptions): ToolManager {
-  const toolManager = new ToolManager();
-  const userTools = options.tools || options.services?.tools || [];
-  let taskTools: ToolDefinition[];
-  if (options.taskTools === 'none') taskTools = [];
-  else if (Array.isArray(options.taskTools)) taskTools = PROTOCOL_TOOLS.filter((t: ToolDefinition) => (options.taskTools as string[]).includes(t.schema.function.name as string));
-  else taskTools = PROTOCOL_TOOLS; // 'all' or undefined
-  const claudeSdkTools = options.cognition === 'claude-sdk' ? CLAUDE_SDK_TOOLS : [];
-  toolManager.registerAll([...taskTools, ...claudeSdkTools, ...(Array.isArray(userTools) ? userTools : [])]);
-  return toolManager;
-}
-
-function isLlmAdapter(v: unknown): v is LlmAdapter {
-  return typeof v === 'object' && v !== null && typeof (v as LlmAdapter).chatMessages === 'function';
-}
-
-function createBackendServices(options: AgentHostOptions) {
-  const toolManager = createToolManager(options);
-  const model = (options.services?.llm as { model?: string } | undefined)?.model || options.model;
-  // The Claude brain drives query() directly and never emits llm-call/stream-text
-  // effects, so it needs no adapter. Building one here would be dead — and worse,
-  // the provider client throws at construction on a missing key, so a claude-sdk
-  // agent left on the default (OpenAI) model with no openaiKey would fail to
-  // start over an adapter it never uses. Skip it.
-  const llm = options.cognition === 'claude-sdk'
-    ? undefined
-    : isLlmAdapter(options.services?.llm)
-      ? options.services!.llm as LlmAdapter
-      : model?.startsWith('claude')
-        ? new AnthropicAdapter({ key: options.anthropicKey, model })
-        : new OpenAIAdapter({ key: options.openaiKey, model });
-  const operatorKey = options.operatorKey!;
-  const agentId = options.agentId!;
-  const artifactsClient = new ArtifactsClient(operatorKey, agentId);
-  const contextReadClient = new ContextReadClient(operatorKey, agentId);
-  const promptBuilder = new PromptBuilder({ description: options.description, specialization: options.specialization });
-  const taskService = new TaskService(operatorKey, agentId);
-  const agreementService = new AgreementService(operatorKey, agentId);
-  const telemetryClient = new TelemetryClient(operatorKey, agentId);
-  return {
-    toolManager,
-    llm,
-    artifactsClient,
-    contextReadClient,
-    promptBuilder,
-    taskService,
-    agreementService,
-    telemetryClient,
-  };
-}
-
-interface LaneSession {
-  sessionId: string;
-  ownAgentId: string;
-  ctx?: Ctx;
-  state?: string;
-}
-
-/**
- * AgentHost — the Server. Owns a pure {@link Agent}, an {@link EffectHandler},
- * a transport (Ziggs WebSocket), and the lane router (per-session FIFO queue
- * + in-memory session state).
- *
- *   transport (WS)  →  handleMessage  →  agent.tick(... , eff)  →  ...
- */
-export class AgentHost {
-  options: Required<Pick<AgentHostOptions, 'agentId' | 'operatorKey' | 'openaiKey'>> & AgentHostOptions;
-  toolManager!: ToolManager;
-  // Retained for external inspection. Undefined for the Claude brain, which
-  // drives query() directly and needs no LLM adapter.
-  llm?: OpenAIAdapter | LlmAdapter;
-  agent!: Agent | ClaudeSdkAgent;
-  wsClient!: WebSocketClient;
-  private eff!: EffectHandler;
-  private eventQueue!: EventQueue;
-  private sessions = new Map<string, LaneSession>();
-  private sessionResolver: SessionResolver;
-  private tickTimeoutMs: number;
-  private memory: MemoryStore;
-  private sessionStore: SessionStore | null;
-  private taskService!: TaskService;
-  private agreementService!: AgreementService;
-  private messageSender!: (message: string, receiverId: string, sessionId: string) => Promise<unknown>;
-  private seenMessages = new SeenMessages();
-  /** Lazy inbox client for advancing the watermark on the live-push path (ZIG-832 P4). */
-  private _inbox?: InboxClient;
-  private stateTimers!: StateTimers;
-  private catchUpInFlight: Promise<void> | null = null;
-  private inboxCatchUpEnabled: boolean;
-
-  constructor(options: AgentHostOptions = {}) {
-    this.options = {
-      openaiKey: options.openaiKey || process.env.OPENAI_API_KEY,
-      anthropicKey: options.anthropicKey || process.env.ANTHROPIC_API_KEY,
-      model: options.model || (!isLlmAdapter(options.services?.llm) ? options.services?.llm?.model : undefined) || DEFAULT_MODEL,
-      operatorKey: options.operatorKey || process.env.ZIGGS_OPERATOR_KEY || undefined,
-      agentId: options.agentId || '',
-      name: options.name || null,
-      wsUrl: options.wsUrl,
-      description: options.description || 'A helpful assistant',
-      specialization: options.specialization ?? null,
-      tools: options.tools || [],
-      taskTools: options.taskTools,
-      states: options.states,
-      initial: options.initial,
-      services: options.services,
-      workflow: options.workflow,
-      tickTimeoutMs: options.tickTimeoutMs,
-      sessionResolver: options.sessionResolver,
-      effectTap: options.effectTap,
-      transitionTap: options.transitionTap,
-      metricsTap: options.metricsTap,
-      inboxCatchUp: options.inboxCatchUp,
-      cognition: options.cognition ?? 'fsm',
-      claudeMaxTurns: options.claudeMaxTurns,
-    } as Required<Pick<AgentHostOptions, 'agentId' | 'operatorKey' | 'openaiKey'>> & AgentHostOptions;
-    this.inboxCatchUpEnabled = options.inboxCatchUp !== false;
-    this.sessionResolver = options.sessionResolver || DEFAULT_SESSION_RESOLVER;
-    this.tickTimeoutMs = options.tickTimeoutMs ?? 120_000;
-    this.memory = options.memory ?? new InMemoryStore();
-    this.sessionStore = options.sessionStore ?? null;
-    this._validate();
-    this._setup();
-  }
-
-  private _validate(): void {
-    if (this.options.cognition === 'claude-sdk') {
-      if (!this.options.anthropicKey) {
-        throw new Error('anthropicKey is required for claude-sdk cognition — pass { anthropicKey } or set ANTHROPIC_API_KEY');
-      }
-    } else if (!isLlmAdapter(this.options.services?.llm)) {
-      if (this.options.model?.startsWith('claude')) {
-        if (!this.options.anthropicKey) throw new Error('anthropicKey is required for claude-* models — pass { anthropicKey } or set ANTHROPIC_API_KEY');
-      } else if (!this.options.openaiKey) {
-        throw new Error('openaiKey is required');
-      }
-    }
-    if (!this.options.operatorKey) throw new Error('operatorKey is required — pass { operatorKey } or set ZIGGS_OPERATOR_KEY');
-    if (!this.options.agentId) throw new Error('agentId is required');
-  }
-
-  private _setup(): void {
-    const services = createBackendServices(this.options);
-    this.toolManager = services.toolManager;
-    this.llm = services.llm;
-
-    this.wsClient = new WebSocketClient({
-      wsUrl: this.options.wsUrl,
-      operatorKey: this.options.operatorKey,
-      agentId: this.options.agentId,
-      label: this.options.name || 'agent',
-    });
-
-    const messageSender = (message: string, receiverId: string, sessionId: string, messageId?: string): Promise<unknown> => {
-      this.wsClient.send(sessionId, receiverId, message, messageId ? { messageId } : undefined);
-      return Promise.resolve(undefined);
-    };
-    const chunkSender = (sessionId: string, receiverId: string, text: string, messageId: string): void => {
-      this.wsClient.send(sessionId, receiverId, text, { partial: true, messageId });
-    };
-    this.taskService = services.taskService;
-    this.agreementService = services.agreementService;
-    this.messageSender = messageSender;
-
-    let workflow = this.options.workflow;
-    if (!workflow && this.options.states) {
-      workflow = {
-        id: this.options.agentId,
-        description: this.options.description!,
-        initial: this.options.initial || 'idle',
-        states: this.options.states,
-      };
-    }
-    if (!workflow?.states) {
-      // The Claude brain has no FSM — it drives query() per wake and parks. It
-      // still plugs into the host's lane/timer machinery via a trivial parked
-      // workflow, synthesized here so callers don't hand-write a dummy one.
-      if (this.options.cognition === 'claude-sdk') {
-        workflow = {
-          id: this.options.agentId,
-          description: this.options.description!,
-          initial: 'ready',
-          states: { ready: { kind: 'parked', transitions: [] } },
-        };
-      } else {
-        throw new Error('AgentHost: workflow (or states + initial) is required');
-      }
-    }
-
-    this.eff = createZiggsEffectHandler({
-      llm: services.llm as unknown as import('./server/ZiggsEffectHandler.js').ZiggsEffectDeps['llm'],
-      artifactsClient: services.artifactsClient,
-      contextReadClient: services.contextReadClient,
-      taskService: services.taskService,
-      agreementService: services.agreementService,
-      messageSender,
-      chunkSender,
-      toolManager: services.toolManager,
-      operatorKey: this.options.operatorKey!,
-      agentId: this.options.agentId!,
-      telemetryClient: services.telemetryClient,
-      telemetryIngest: this.options.telemetryIngest,
-      effectTap: this.options.effectTap,
-    });
-
-    this.agent = this.options.cognition === 'claude-sdk'
-      ? new ClaudeSdkAgent({
-          workflow,
-          toolManager: services.toolManager,
-          description: this.options.description!,
-          specialization: this.options.specialization,
-          model: resolveClaudeModel(
-            this.options.model,
-            (this.options.services?.llm as { model?: string } | undefined)?.model,
-          ),
-          anthropicKey: this.options.anthropicKey!,
-          operatorKey: this.options.operatorKey!,
-          agentId: this.options.agentId!,
-          // No taskService/agreementService: Claude-brain tools execute through
-          // eff({ kind: 'tool-call' }) → the shared executor, which sources those
-          // services from the effect handler's deps like the FSM path (ZIG-775).
-          maxTurns: this.options.claudeMaxTurns,
-        })
-      : new Agent({
-          workflow,
-          toolManager: services.toolManager,
-          promptBuilder: services.promptBuilder,
-        });
-
-    this.eventQueue = new EventQueue((event, laneKey) => this._processEvent(event, laneKey));
-    this.stateTimers = new StateTimers((ev, laneKey) => { void this.eventQueue.enqueue(ev, laneKey); });
-
-    this.wsClient.setMessageHandler((text: string, metadata: MessageMetadata) => this.handleMessage(text, metadata as unknown as Record<string, unknown>));
-    this.wsClient.setResourceEventHandler((event) => this.handleResourceEvent(event as unknown as Record<string, unknown>));
-
-    if (this.inboxCatchUpEnabled) {
-      this.wsClient.onConnect(() => {
-        void this._ensureCatchUp();
-      });
-    }
-  }
-
-  /**
-   * Coalesce concurrent connect/reconnect bursts into one catch-up pass.
-   */
-  private _ensureCatchUp(): Promise<void> {
-    if (!this.catchUpInFlight) {
-      this.catchUpInFlight = this._runInboxCatchUp().finally(() => {
-        this.catchUpInFlight = null;
-      });
-    }
-    return this.catchUpInFlight;
-  }
-
-  private async _runInboxCatchUp(): Promise<void> {
-    const label = this.options.name || 'agent';
-    try {
-      await runInboxCatchUp({
-        creds: {
-          operatorKey: this.options.operatorKey!,
-          agentId: this.options.agentId!,
-        },
-        ownAgentId: this.options.agentId!,
-        baseUrl: this.options.wsUrl ? undefined : undefined,
-        seen: this.seenMessages,
-        label,
-        onMessage: (text, metadata) => this.handleMessage(text, metadata),
-        onResourceEvent: (event) => this.handleResourceEvent(event),
-      });
-    } catch (err: unknown) {
-      runtimeLog.warn(
-        label,
-        `inbox catch-up failed: ${(err as Error)?.message ?? err}`,
-      );
-    }
-  }
-
-  /**
-   * Push notification handler — invoked when the backend sees a relevant
-   * resource change (artifact created, task state transition, agreement
-   * updated). The agent decides which session/lane to wake based on the
-   * event payload; it pulls the actual data via the primitive endpoints
-   * from inside the tick.
-   *
-   * Lightweight: defers all work to a tick by enqueueing a synthetic event
-   * carrying just enough context for the agent to route it.
-   */
-  async handleResourceEvent(event: Record<string, unknown>): Promise<void> {
-    if (!event || typeof event !== 'object') return;
-    const ownAgentId = this.options.agentId;
-    if (!ownAgentId) return;
-
-    // The agent's own writes aren't news to it (same rule the backend inbox
-    // applies to counts). The backend already skips agent actors on emit;
-    // this guards the same invariant host-side so a self-caused event can
-    // never re-wake the brain — that echo was a token-burning wake loop for
-    // LLM cognitions (one wake's tool calls seeded the next wake, forever).
-    if (event.actorId != null && String(event.actorId) === ownAgentId) {
-      runtimeLog.debug('AgentHost', `skip self-caused resource event kind=${event.kind ?? 'unknown'} resourceId=${event.resourceId ?? 'null'}`);
-      return;
-    }
-
-    // A `message` resource event is the second channel for news the message
-    // push already delivered — the backend emits BOTH a `chat:message` frame
-    // and a `resource_changed {kind:'message', resourceId: messageId}` for
-    // every send. The resource frame exists for offline recovery (queue +
-    // launcher wake); when we already processed that messageId live via
-    // handleMessage, waking again just re-runs the brain over handled news
-    // (every inbound chat message cost a second wake). Unseen ids still wake:
-    // that's the recovery path working.
-    if (
-      event.kind === 'message' &&
-      typeof event.resourceId === 'string' &&
-      this.seenMessages.has(event.resourceId)
-    ) {
-      runtimeLog.debug('AgentHost', `skip resource event for already-handled message ${event.resourceId}`);
-      return;
-    }
-
-    // Map the event to a candidate session key using the configured resolver
-    // on a synthetic normalized-event shape. Default resolver buckets by
-    // chatId; agents using a different sessionResolver (agreementId, taskId,
-    // counterpartyId) will get the right lane here as long as the wire
-    // event carries the corresponding id.
-    const fakeNormalized = {
-      chatId: event.chatId as string | null,
-      event: { type: 'message' as const, timestamp: Date.now(), text: '' },
-      shouldProcess: true,
-      reason: null,
-    } as NormalizedEvent;
-    const sessionId = this.sessionResolver(fakeNormalized, ownAgentId);
-    if (!sessionId) return;
-
-    const laneKey = `${ownAgentId}:${sessionId}`;
-    if (!this.sessions.has(laneKey)) {
-      this.sessions.set(laneKey, { sessionId, ownAgentId });
-    }
-    return this.eventQueue.enqueue({ type: 'resource_changed', resource: event, chatId: event.chatId, taskId: event.taskId, agreementId: event.agreementId }, laneKey);
-  }
-
-  /** Wire entry. Normalize → resolve session → enqueue on the right lane. */
-  async handleMessage(text: string, metadata: Record<string, unknown> = {}): Promise<void> {
-    const messageId = metadata.messageId as string | undefined;
-    if (messageId && this.seenMessages.has(messageId)) {
-      runtimeLog.debug('AgentHost', `skip duplicate messageId=${messageId}`);
-      return;
-    }
-    if (messageId) this.seenMessages.mark(messageId);
-
-    const ownAgentId = this._resolveOwnAgentId(metadata);
-    if (!ownAgentId) {
-      runtimeLog.warn('AgentHost', 'handleMessage: ownAgentId missing — dropping event');
-      return;
-    }
-
-    let enrichedText = typeof text === 'string' ? text : '';
-    if (!enrichedText.trim()) {
-      const agreement = metadata.agreement as Record<string, unknown> | undefined;
-      const terms = agreement?.terms as { description?: string } | undefined;
-      if (terms?.description) {
-        enrichedText = String(terms.description);
-      }
-    }
-
-    const normalized = normalizeIncomingEvent({ text: enrichedText, metadata, ownAgentId });
-    if (!normalized.shouldProcess) {
-      const receiverId = (metadata.receiver as Record<string, unknown> | undefined)?.id ?? metadata.receiverId;
-      runtimeLog.warn('AgentHost', `skip reason=${normalized.reason || 'not_relevant'} ownAgentId=${ownAgentId} receiverId=${receiverId ?? 'null'} chatId=${normalized.chatId ?? 'null'}`);
-      return;
-    }
-
-    const sessionId = this.sessionResolver(normalized, ownAgentId);
-    if (!sessionId) {
-      runtimeLog.warn('AgentHost', `session resolver returned null ownAgentId=${ownAgentId} chatId=${normalized.chatId ?? 'null'}`);
-      return;
-    }
-
-    const laneKey = `${ownAgentId}:${sessionId}`;
-    if (!this.sessions.has(laneKey)) {
-      this.sessions.set(laneKey, { sessionId, ownAgentId });
-    }
-    const enqueued = this.eventQueue.enqueue(normalized.event, laneKey);
-    // ZIG-832 P4: advance this chat's inbox watermark for a message handled on
-    // the LIVE push path. Without it, only catch-up acks — so on a re-host the
-    // server watermark still sits before this message and catch-up re-delivers
-    // it, re-running a finished pipeline (the cross-wake token burn). Mirrors
-    // catch-up's ack-on-delivery; newer messages carry a later ts and still
-    // deliver, so a genuinely new turn in the same chat is not lost. Best-effort:
-    // never block or fail the wake.
-    const msgTs = (metadata.createdAt ?? metadata.timestamp ?? metadata.sentTimestamp) as string | undefined;
-    if (normalized.chatId && typeof msgTs === 'string' && msgTs) {
-      void this._ackChatWatermark(normalized.chatId, msgTs);
-    } else if (normalized.chatId) {
-      // ZIG-860: this ack silently not firing is exactly how the re-delivery
-      // bug hid — a live message with no usable timestamp must be loud.
-      runtimeLog.warn('AgentHost', `live-ack skipped: no timestamp on message chatId=${normalized.chatId} messageId=${messageId ?? 'null'}`);
-    }
-    return enqueued;
-  }
-
-  /** Best-effort: advance the inbox watermark for a chat handled live (ZIG-832 P4). */
-  private async _ackChatWatermark(chatId: string, upTo: string): Promise<void> {
-    try {
-      if (!this._inbox) {
-        this._inbox = new InboxClient(this.options.operatorKey!, this.options.agentId!);
-      }
-      await this._inbox.ack([{ kind: 'chat', id: chatId, upTo }]);
-    } catch (e: unknown) {
-      // warn, not debug (ZIG-860): a failing live-ack means catch-up will
-      // re-deliver this chat's backlog after the next host eviction.
-      runtimeLog.warn('AgentHost', `live-ack chat ${chatId} failed: ${(e as Error)?.message ?? e}`);
-    }
-  }
-
-  private async _processEvent(event: unknown, laneKey: string): Promise<void> {
-    const session = this.sessions.get(laneKey);
-    if (!session?.sessionId) return;
-
-    // Stale timer frames (superseded epoch) are dropped BEFORE touching the
-    // live timer — a pure-stale frame must not reset a freshly armed countdown.
-    const frame = this.stateTimers.stripStale(event, laneKey);
-    if (frame === null) return;
-
-    // Any event reaching the machine invalidates the countdown ("clear on any
-    // event for the lane"); re-armed below if the tick settles parked+timed.
-    this.stateTimers.clear(laneKey);
-
-    // Cold-start recovery: restore FSM state from sessionStore when the
-    // in-memory lane has no prior context (e.g. after a container restart).
-    if (this.sessionStore && session.ctx === undefined && session.state === undefined) {
-      try {
-        const persisted = await this.sessionStore.load(laneKey);
-        if (persisted) {
-          session.ctx = persisted.ctx;
-          session.state = persisted.state;
-        }
-      } catch (err: unknown) {
-        runtimeLog.warn('AgentHost', `sessionStore.load failed laneKey=${laneKey}: ${(err as Error)?.message || err}`);
-      }
-    }
-
-    const identity: Identity = {
-      agentId: session.ownAgentId || this.options.agentId,
-      sessionId: session.sessionId,
-      laneKey,
-    };
-
-    // The watchdog timer must be cleared once the tick settles — leaving it
-    // armed pinned one live 2-minute timer per tick (and kept short-lived
-    // processes/tests alive until it fired).
-    let tickWatchdog: ReturnType<typeof setTimeout> | undefined;
-    try {
-      const result = await Promise.race([
-        this.agent.tick({ event: frame, ctx: session.ctx, state: session.state, identity, eff: this.eff, memory: this.memory, transitionTap: this.options.transitionTap }),
-        new Promise<never>((_, reject) => {
-          tickWatchdog = setTimeout(() => reject(new Error('tick timeout')), this.tickTimeoutMs);
-        }),
-      ]);
-      session.ctx = result.ctx;
-      session.state = result.state;
-      this.sessions.set(laneKey, session);
-
-      // One line per wake that actually spent LLM budget — the handle for
-      // tracking a hosted agent live (grep `agent=<id>`). Parked no-op ticks
-      // (FSM exits, wake-rate-skipped Claude wakes) report zero tokens and
-      // stay quiet. A regressed self-wake loop shows here as a rapid stream of
-      // these lines for one lane. Tokens are billable input (incl. cache).
-      const m = result.metrics;
-      if (m && (m.tokens?.total ?? 0) > 0) {
-        runtimeLog.info(
-          'AgentHost',
-          `wake agent=${identity.agentId} lane=${laneKey} llmCalls=${m.llmCalls} ` +
-            `tokens_in=${m.tokens.input} tokens_out=${m.tokens.output} total=${m.tokens.total}`,
-        );
-      }
-
-      // Single source of truth for usage/cost (ZIG-813): emit the tick's
-      // authoritative token metrics once, for every cognition. Never let an
-      // observability failure break the tick.
-      if (this.options.metricsTap && result.metrics) {
-        try {
-          this.options.metricsTap({
-            agentId: identity.agentId,
-            sessionId: session.sessionId,
-            model: this.options.model ?? 'unknown',
-            cognition: this.options.cognition ?? 'fsm',
-            metrics: result.metrics,
-          });
-        } catch (err: unknown) {
-          runtimeLog.warn('AgentHost', `metricsTap failed: ${(err as Error)?.message || err}`);
-        }
-      }
-
-      if (this.sessionStore) {
-        this.sessionStore.save(laneKey, { ctx: session.ctx, state: session.state }).catch((err: unknown) => {
-          runtimeLog.warn('AgentHost', `sessionStore.save failed laneKey=${laneKey}: ${(err as Error)?.message || err}`);
-        });
-      }
-
-      // Arm only when the timeout was handled: an unhandled state-timeout must
-      // not re-arm, or the lane would runtimeLog.error every timeoutMs forever.
-      if (!result.stateTimeoutUnhandled) this._armIfTimedParked(laneKey, result.state);
-    } catch (err: unknown) {
-      runtimeLog.warn('AgentHost', `tick failed laneKey=${laneKey}: ${(err as Error)?.message || err}`);
-      // Deliberate re-arm on failure. Exact scenario: the tick timed out at
-      // tickTimeoutMs (or sessionStore.load threw) leaving session.state at a
-      // timed parked state — without re-arming, that lane would never wake
-      // again unless a real event happens to arrive.
-      this._armIfTimedParked(laneKey, session.state ?? this.agent.workflow.initial);
-      // Best-effort: also notify the user so the conversation isn't silently
-      // stuck (ZIG-607). Complements the timer re-arm above — that recovers a
-      // parked lane; this tells a waiting human.
-      const ev = event as Record<string, unknown> | undefined;
-      const senderType = String(ev?.senderType ?? '').toUpperCase();
-      const senderId = ev?.senderId as string | undefined;
-      if (senderId && senderType === 'USER') {
-        this.eff({ kind: 'send-message', sessionId: session.sessionId, receiverId: senderId, text: 'Something went wrong. Please try again.' }).catch(() => {});
-      }
-    } finally {
-      clearTimeout(tickWatchdog);
-    }
-  }
-
-  /** Arms the lane's liveness timer iff stateName is a parked state declaring timeoutMs. */
-  private _armIfTimedParked(laneKey: string, stateName: string | undefined): void {
-    if (!stateName) return;
-    const sd = this.agent.workflow.states[stateName];
-    if (sd?.kind !== 'parked' || sd.timeoutMs === undefined) return;
-    this.stateTimers.arm(laneKey, stateName, sd.timeoutMs);
-  }
-
-  private _resolveOwnAgentId(metadata: Record<string, unknown> = {}): string | null {
-    const self = metadata.self as Record<string, unknown> | undefined;
-    const agent = metadata.agent as Record<string, unknown> | undefined;
-    return this.options.agentId || (self?.id as string) || (agent?.id as string) || (metadata.ziggsAgentId as string) || null;
-  }
-
-  async connectAsync(timeout?: number) {
-    await this.wsClient.connectAsync(timeout);
-    if (this.inboxCatchUpEnabled) {
-      await this._ensureCatchUp();
-      // Backend flushPendingMessages can emit after auth; re-poll once so inbox
-      // ack catches stragglers and we don't leave newMessages > 0 (ZIG-462).
-      await new Promise((r) => setTimeout(r, 750));
-      this.catchUpInFlight = null;
-      await this._ensureCatchUp();
-      await this._bootstrapAssignedActiveTasks();
-    }
-    return this;
-  }
-  private async _bootstrapAssignedActiveTasks(): Promise<void> {
-    const agentId = this.options.agentId;
-    if (!agentId || !this.taskService) return;
-
-    let tasks: Array<{ taskId?: string; assigneeId?: string | null }> = [];
-    try {
-      tasks = await this.taskService.getActiveTasksForAgent(agentId);
-    } catch (err: unknown) {
-      runtimeLog.warn(
-        this.options.name || 'agent',
-        `active-task bootstrap skipped: ${(err as Error)?.message ?? err}`,
-      );
-      return;
-    }
-
-    for (const row of tasks) {
-      const taskId = row.taskId;
-      if (!taskId) continue;
-      if (row.assigneeId && row.assigneeId !== agentId) continue;
-
-      let full: Record<string, unknown>;
-      try {
-        full = (await this.taskService.getTask(taskId)) as unknown as Record<string, unknown>;
-      } catch {
-        continue;
-      }
-      const state = String(full.state ?? '');
-      if (state !== 'active' && state !== 'in-progress') continue;
-
-      const sessionId =
-        (full.agreementId as string | undefined) ||
-        (full.originChatId as string | undefined) ||
-        'default';
-      const laneKey = `${agentId}:${sessionId}`;
-      if (!this.sessions.has(laneKey)) {
-        this.sessions.set(laneKey, { sessionId, ownAgentId: agentId });
-      }
-
-      runtimeLog.info(
-        this.options.name || 'agent',
-        `bootstrap task-assigned ${taskId} (state=${state})`,
-      );
-      await this.eventQueue.enqueue(
-        {
-          type: 'task_result',
-          result: {
-            ...full,
-            taskId: (full.taskId as string | undefined) ?? taskId,
-            state,
-            providerIsYou: true,
-          },
-          chatId: full.originChatId as string | undefined,
-        },
-        laneKey,
-      );
-    }
-  }
-
-  /** ZIG-802: replay task-assigned for an existing active task (demo recovery). */
-  async wakeTaskAssignment(taskId: string): Promise<void> {
-    const agentId = this.options.agentId;
-    if (!agentId || !this.taskService) {
-      throw new Error('wakeTaskAssignment: agent not configured');
-    }
-    const full = (await this.taskService.getTask(taskId)) as unknown as Record<string, unknown>;
-    const state = String(full.state ?? '');
-    if (state !== 'active' && state !== 'in-progress') {
-      throw new Error(`wakeTaskAssignment: task ${taskId} is ${state}, not active`);
-    }
-    const sessionId =
-      (full.agreementId as string | undefined) ||
-      (full.originChatId as string | undefined) ||
-      'default';
-    const laneKey = `${agentId}:${sessionId}`;
-    if (!this.sessions.has(laneKey)) {
-      this.sessions.set(laneKey, { sessionId, ownAgentId: agentId });
-    }
-    await this.eventQueue.enqueue(
-      {
-        type: 'task_result',
-        result: {
-          ...full,
-          taskId: (full.taskId as string | undefined) ?? taskId,
-          state,
-          providerIsYou: true,
-        },
-        chatId: full.originChatId as string | undefined,
-      },
-      laneKey,
-    );
-  }
-
-  disconnect() { this.stateTimers.clearAll(); this.wsClient.disconnect(); }
-  /** Waits for all in-flight ticks to complete. Call before process.exit() on SIGTERM. */
-  drain(timeoutMs = 30_000): Promise<void> { return this.eventQueue.waitForIdle(timeoutMs); }
-  registerTool(tool: ToolDefinition) { return this.toolManager.register(tool); }
-  isConnected() { return this.wsClient.isConnected(); }
-}
-
-/**
- * createAgent(config)            → AgentHost
- * createAgentPool([cfg, ...])    → ConnectionPool (lazy fleet, async-loaded)
- */
-export function createAgent(options: AgentHostOptions | AgentConfig = {}): AgentHost {
-  return new AgentHost(options as AgentHostOptions);
-}
-
-export async function createAgentPool(
-  configs: AgentHostOptions[] | AgentConfig[],
-  opts: { poolOptions?: { maxActive?: number; idleTimeoutMs?: number } } = {},
-): Promise<unknown> {
-  const ConnectionPool = await loadConnectionPool();
-  const pool = new ConnectionPool(opts.poolOptions);
-  (pool as { register: (configs: unknown[]) => void }).register(configs);
-  return pool;
-}
-
-export default AgentHost;