@ziggs-ai/agent-sdk 0.1.12 → 0.2.0

package/dist/AgentHost.js

@@ -0,0 +1,652 @@
+import { Agent } from './agent/Agent.js';
+import { ClaudeSdkAgent } from './agent/ClaudeSdkAgent.js';
+import { applyBrainToHostOptions, isClaudeCognition, } from './brain/index.js';
+import { CLAUDE_SDK_TOOLS } from './agent/claudeSdkTools.js';
+import { resolveClaudeModel } from './agent/claudeCognition.js';
+import { EventQueue } from './server/EventQueue.js';
+import { StateTimers } from './server/StateTimers.js';
+import { createZiggsEffectHandler } from './server/ZiggsEffectHandler.js';
+import { normalizeIncomingEvent } from './ingress/normalizeIncoming.js';
+import { PromptBuilder } from './runtime/PromptBuilder.js';
+import { InMemoryStore } from './memory/MemoryStore.js';
+import { ToolManager } from './tools/ToolManager.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, } 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() {
+    const modPath = './server/ConnectionPool.js';
+    const mod = await import(/* @vite-ignore */ modPath);
+    return mod.ConnectionPool;
+}
+const DEFAULT_SESSION_RESOLVER = (normalized) => normalized.chatId;
+function createToolManager(options) {
+    const toolManager = new ToolManager();
+    const userTools = options.tools || options.services?.tools || [];
+    let taskTools;
+    if (options.taskTools === 'none')
+        taskTools = [];
+    else if (Array.isArray(options.taskTools))
+        taskTools = PROTOCOL_TOOLS.filter((t) => options.taskTools.includes(t.schema.function.name));
+    else
+        taskTools = PROTOCOL_TOOLS; // 'all' or undefined
+    const claudeSdkTools = isClaudeCognition(options.cognition) ? CLAUDE_SDK_TOOLS : [];
+    toolManager.registerAll([...taskTools, ...claudeSdkTools, ...(Array.isArray(userTools) ? userTools : [])]);
+    return toolManager;
+}
+function isLlmAdapter(v) {
+    return typeof v === 'object' && v !== null && typeof v.chatMessages === 'function';
+}
+function createBackendServices(options) {
+    const toolManager = createToolManager(options);
+    const model = options.services?.llm?.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 = isClaudeCognition(options.cognition)
+        ? undefined
+        : isLlmAdapter(options.services?.llm)
+            ? options.services.llm
+            : 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,
+    };
+}
+/**
+ * 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;
+    toolManager;
+    // Retained for external inspection. Undefined for the Claude brain, which
+    // drives query() directly and needs no LLM adapter.
+    llm;
+    agent;
+    wsClient;
+    eff;
+    eventQueue;
+    sessions = new Map();
+    sessionResolver;
+    tickTimeoutMs;
+    memory;
+    sessionStore;
+    taskService;
+    agreementService;
+    messageSender;
+    seenMessages = new SeenMessages();
+    /** Lazy inbox client for advancing the watermark on the live-push path (ZIG-832 P4). */
+    _inbox;
+    stateTimers;
+    catchUpInFlight = null;
+    inboxCatchUpEnabled;
+    constructor(options = {}) {
+        const resolved = applyBrainToHostOptions(options);
+        this.options = {
+            openaiKey: resolved.openaiKey || process.env.OPENAI_API_KEY,
+            anthropicKey: resolved.anthropicKey || process.env.ANTHROPIC_API_KEY,
+            model: resolved.model || (!isLlmAdapter(resolved.services?.llm) ? resolved.services?.llm?.model : undefined) || DEFAULT_MODEL,
+            operatorKey: resolved.operatorKey || process.env.ZIGGS_OPERATOR_KEY || undefined,
+            agentId: resolved.agentId || '',
+            name: resolved.name || null,
+            wsUrl: resolved.wsUrl,
+            description: resolved.description || 'A helpful assistant',
+            specialization: resolved.specialization ?? null,
+            tools: resolved.tools || [],
+            taskTools: resolved.taskTools,
+            states: resolved.states,
+            initial: resolved.initial,
+            services: resolved.services,
+            workflow: resolved.workflow,
+            tickTimeoutMs: resolved.tickTimeoutMs,
+            sessionResolver: resolved.sessionResolver,
+            effectTap: resolved.effectTap,
+            transitionTap: resolved.transitionTap,
+            metricsTap: resolved.metricsTap,
+            inboxCatchUp: resolved.inboxCatchUp,
+            brain: resolved.brain,
+            cognition: resolved.cognition ?? 'fsm',
+            claudeMaxTurns: resolved.claudeMaxTurns,
+        };
+        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();
+    }
+    _validate() {
+        if (isClaudeCognition(this.options.cognition)) {
+            if (!this.options.anthropicKey) {
+                throw new Error('anthropicKey is required for the Claude brain — pass claudeBrain({ 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');
+    }
+    _setup() {
+        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, receiverId, sessionId, messageId) => {
+            this.wsClient.send(sessionId, receiverId, message, messageId ? { messageId } : undefined);
+            return Promise.resolve(undefined);
+        };
+        const chunkSender = (sessionId, receiverId, text, messageId) => {
+            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 (isClaudeCognition(this.options.cognition)) {
+                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,
+            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 = isClaudeCognition(this.options.cognition)
+            ? new ClaudeSdkAgent({
+                workflow,
+                toolManager: services.toolManager,
+                description: this.options.description,
+                specialization: this.options.specialization,
+                model: resolveClaudeModel(this.options.model, this.options.services?.llm?.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, metadata) => this.handleMessage(text, metadata));
+        this.wsClient.setResourceEventHandler((event) => this.handleResourceEvent(event));
+        if (this.inboxCatchUpEnabled) {
+            this.wsClient.onConnect(() => {
+                void this._ensureCatchUp();
+            });
+        }
+    }
+    /**
+     * Coalesce concurrent connect/reconnect bursts into one catch-up pass.
+     */
+    _ensureCatchUp() {
+        if (!this.catchUpInFlight) {
+            this.catchUpInFlight = this._runInboxCatchUp().finally(() => {
+                this.catchUpInFlight = null;
+            });
+        }
+        return this.catchUpInFlight;
+    }
+    async _runInboxCatchUp() {
+        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) {
+            runtimeLog.warn(label, `inbox catch-up failed: ${err?.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) {
+        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,
+            event: { type: 'message', timestamp: Date.now(), text: '' },
+            shouldProcess: true,
+            reason: null,
+        };
+        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, metadata = {}) {
+        const messageId = metadata.messageId;
+        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;
+            const terms = agreement?.terms;
+            if (terms?.description) {
+                enrichedText = String(terms.description);
+            }
+        }
+        const normalized = normalizeIncomingEvent({ text: enrichedText, metadata, ownAgentId });
+        if (!normalized.shouldProcess) {
+            const receiverId = metadata.receiver?.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);
+        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). */
+    async _ackChatWatermark(chatId, upTo) {
+        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) {
+            // 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?.message ?? e}`);
+        }
+    }
+    async _processEvent(event, laneKey) {
+        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) {
+                runtimeLog.warn('AgentHost', `sessionStore.load failed laneKey=${laneKey}: ${err?.message || err}`);
+            }
+        }
+        const 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;
+        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((_, 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) {
+                    runtimeLog.warn('AgentHost', `metricsTap failed: ${err?.message || err}`);
+                }
+            }
+            if (this.sessionStore) {
+                this.sessionStore.save(laneKey, { ctx: session.ctx, state: session.state }).catch((err) => {
+                    runtimeLog.warn('AgentHost', `sessionStore.save failed laneKey=${laneKey}: ${err?.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) {
+            runtimeLog.warn('AgentHost', `tick failed laneKey=${laneKey}: ${err?.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;
+            const senderType = String(ev?.senderType ?? '').toUpperCase();
+            const senderId = ev?.senderId;
+            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. */
+    _armIfTimedParked(laneKey, stateName) {
+        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);
+    }
+    _resolveOwnAgentId(metadata = {}) {
+        const self = metadata.self;
+        const agent = metadata.agent;
+        return this.options.agentId || self?.id || agent?.id || metadata.ziggsAgentId || null;
+    }
+    async connectAsync(timeout) {
+        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;
+    }
+    async _bootstrapAssignedActiveTasks() {
+        const agentId = this.options.agentId;
+        if (!agentId || !this.taskService)
+            return;
+        let tasks = [];
+        try {
+            tasks = await this.taskService.getActiveTasksForAgent(agentId);
+        }
+        catch (err) {
+            runtimeLog.warn(this.options.name || 'agent', `active-task bootstrap skipped: ${err?.message ?? err}`);
+            return;
+        }
+        for (const row of tasks) {
+            const taskId = row.taskId;
+            if (!taskId)
+                continue;
+            if (row.assigneeId && row.assigneeId !== agentId)
+                continue;
+            let full;
+            try {
+                full = (await this.taskService.getTask(taskId));
+            }
+            catch {
+                continue;
+            }
+            const state = String(full.state ?? '');
+            if (state !== 'active' && state !== 'in-progress')
+                continue;
+            const sessionId = full.agreementId ||
+                full.originChatId ||
+                '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 ?? taskId,
+                    state,
+                    providerIsYou: true,
+                },
+                chatId: full.originChatId,
+            }, laneKey);
+        }
+    }
+    /** ZIG-802: replay task-assigned for an existing active task (demo recovery). */
+    async wakeTaskAssignment(taskId) {
+        const agentId = this.options.agentId;
+        if (!agentId || !this.taskService) {
+            throw new Error('wakeTaskAssignment: agent not configured');
+        }
+        const full = (await this.taskService.getTask(taskId));
+        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 ||
+            full.originChatId ||
+            '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 ?? taskId,
+                state,
+                providerIsYou: true,
+            },
+            chatId: full.originChatId,
+        }, 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) { return this.eventQueue.waitForIdle(timeoutMs); }
+    registerTool(tool) { return this.toolManager.register(tool); }
+    isConnected() { return this.wsClient.isConnected(); }
+}
+/**
+ * createAgent(config)            → AgentHost
+ * createAgentPool([cfg, ...])    → ConnectionPool (lazy fleet, async-loaded)
+ */
+export function createAgent(options = {}) {
+    return new AgentHost(options);
+}
+export async function createAgentPool(configs, opts = {}) {
+    const ConnectionPool = await loadConnectionPool();
+    const pool = new ConnectionPool(opts.poolOptions);
+    pool.register(configs);
+    return pool;
+}
+export default AgentHost;