@ziggs-ai/agent-sdk 0.16.1 → 0.18.0

package/dist/{AgentHost.js → Agent.js}

@@ -1,31 +1,33 @@
+import { agreementLaneId, agreementIdFromLane } from '@ziggs-ai/api-client';
+import { createDeclaredPollRunner } from './platform/polls/declaredPollRunner.js';
 import { randomUUID } from 'node:crypto';
-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 { CHAT_TOOLS } from './server/tools/tier2/chatTools.js';
-import { EventQueue } from './server/EventQueue.js';
-import { StateTimers } from './server/StateTimers.js';
-import { createZiggsEffectHandler } from './server/ZiggsEffectHandler.js';
+import { ZiggsBrain } from './brain/ZiggsBrain.js';
+import { ClaudeBrain } from './brain/ClaudeBrain.js';
+import { applyBrainToAgentOptions, isClaudeCognition, } from './brain/index.js';
+import { CLAUDE_SDK_TOOLS } from './brain/claudeSdkTools.js';
+import { resolveClaudeModel } from './brain/claudeCognition.js';
+import { CHAT_TOOLS } from './platform/tools/tier2/chatTools.js';
+import { EventQueue } from './platform/EventQueue.js';
+import { StateTimers } from './platform/StateTimers.js';
+import { createZiggsEffectHandler } from './platform/ZiggsEffectHandler.js';
 import { normalizeIncomingEvent } from './ingress/normalizeIncoming.js';
 import { PromptBuilder } from './runtime/PromptBuilder.js';
-import { InMemoryStore } from './memory/MemoryStore.js';
+import { InMemoryStore, memorySectionForWake, partitionMemoryStore, } from './memory/MemoryStore.js';
 import { ToolManager } from './tools/ToolManager.js';
 import { toolName } from './tools/defineTool.js';
-import { PROTOCOL_TOOLS } from './server/tools/tier1/protocolTools.js';
-import { marketplaceViewTool } from './server/tools/tier2/marketplaceTools.js';
+import { PROTOCOL_TOOLS } from './platform/tools/tier1/protocolTools.js';
+import { marketplaceViewTool } from './platform/tools/tier2/marketplaceTools.js';
 import { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
 import { AnthropicAdapter } from './adapters/AnthropicAdapter.js';
 import { ArtifactsClient, ConnectionsClient, ContextReadClient, TelemetryClient, sendChatMessage, } from '@ziggs-ai/api-client';
 import { normalizeNeeds, unmetNeeds, unmetNeedsMessage, } from './tools/needs.js';
-import { TaskService } from './server/tasks/TaskService.js';
-import { AgreementService } from './server/agreements/AgreementService.js';
-import { runInboxLoop } from './server/inboxLoop.js';
-import { requestExactMatch } from './server/requestMatch.js';
-import { SeenMessages } from './server/SeenMessages.js';
+import { TaskService } from './platform/tasks/TaskService.js';
+import { AgreementService } from './platform/agreements/AgreementService.js';
+import { runInboxLoop } from './platform/inboxLoop.js';
+import { requestExactMatch } from './platform/requestMatch.js';
+import { SeenMessages } from './platform/SeenMessages.js';
 import { runtimeLog } from './shared/runtimeLog.js';
-import { isTelemetryIngestEnabled, sendTelemetry, } from './server/telemetryIngest.js';
+import { isTelemetryIngestEnabled, sendTelemetry, } from './platform/telemetryIngest.js';
 import { buildWakeOutcomePayload, classifyWakeOutcome, } from './runtime/wakeOutcome.js';
 /**
  * The single fleet-wide default model — the one place the fallback lives.
@@ -36,9 +38,9 @@ import { buildWakeOutcomePayload, classifyWakeOutcome, } from './runtime/wakeOut
  */
 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.
+// dynamic import to avoid a circular import with Agent.
 async function loadConnectionPool() {
-    const modPath = './server/ConnectionPool.js';
+    const modPath = './platform/ConnectionPool.js';
     const mod = await import(/* @vite-ignore */ modPath);
     return mod.ConnectionPool;
 }
@@ -57,7 +59,7 @@ export function laneSessionIdForTask(task) {
         return task.originChatId;
     }
     if (typeof task.agreementId === 'string' && task.agreementId) {
-        return `agrn-${task.agreementId}`;
+        return agreementLaneId(task.agreementId);
     }
     return 'default';
 }
@@ -67,16 +69,11 @@ export function workScopeFromWake(event, sessionId) {
     const resource = rec.resource && typeof rec.resource === 'object'
         ? rec.resource
         : {};
-    const fromAgrn = (id) => {
-        if (typeof id !== 'string' || !id.startsWith('agrn-'))
-            return undefined;
-        return id.slice('agrn-'.length) || undefined;
-    };
     const agreementId = (typeof rec.agreementId === 'string' && rec.agreementId) ||
         (typeof resource.agreementId === 'string' && resource.agreementId) ||
-        fromAgrn(rec.chatId) ||
-        fromAgrn(resource.chatId) ||
-        fromAgrn(sessionId) ||
+        agreementIdFromLane(rec.chatId) ||
+        agreementIdFromLane(resource.chatId) ||
+        agreementIdFromLane(sessionId) ||
         undefined;
     const taskId = (typeof rec.taskId === 'string' && rec.taskId) ||
         (typeof resource.taskId === 'string' && resource.taskId) ||
@@ -132,7 +129,7 @@ export function warnOnShadowedPlatformTools(platformTools, ownTools, agentId) {
         .filter((name) => platform.has(name));
     if (shadowed.length === 0)
         return;
-    console.warn(`[AgentHost] ${agentId}: tool name(s) ${shadowed.join(', ')} shadow the platform tools of the same name — ` +
+    console.warn(`[Agent] ${agentId}: tool name(s) ${shadowed.join(', ')} shadow the platform tools of the same name — ` +
         'the agent will call yours, not Ziggs\'s. Rename them unless that is deliberate.');
 }
 function isLlmAdapter(v) {
@@ -178,19 +175,18 @@ function createBackendServices(options) {
     };
 }
 /**
- * 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)  →  ..
+ * One agent identity and its body: inbox, tools, contracts, memory and lanes.
+ * The brain decides on each wake; platform services perform its effects.
+ * connectAsync starts outbound inbox reads and declared external polls.
+ * An Agent never opens a listening socket.
  */
-export class AgentHost {
+export class Agent {
     options;
     toolManager;
     // Retained for external inspection. Undefined for the Claude brain, which
     // drives query() directly and needs no LLM adapter.
     llm;
-    agent;
+    brain;
     eff;
     eventQueue;
     sessions = new Map();
@@ -207,6 +203,8 @@ export class AgentHost {
     /** The per-agent inbox long-poll loop — this agent's sole wake source. */
     inboxLoop = null;
     inboxLoopEnabled;
+    started = false;
+    pollRunner;
     /** Short-lived grant-provider cache for the declared-needs gate. */
     /**
      * Lanes where an unmet-need refusal has already been allowed its one turn to
@@ -218,7 +216,7 @@ export class AgentHost {
     unmetTasksPendingAsk = new Map();
     grantProviderCache = null;
     constructor(options = {}) {
-        const resolved = applyBrainToHostOptions(options);
+        const resolved = applyBrainToAgentOptions(options);
         this.options = {
             openaiKey: resolved.openaiKey || process.env.OPENAI_API_KEY,
             anthropicKey: resolved.anthropicKey || process.env.ANTHROPIC_API_KEY,
@@ -251,6 +249,8 @@ export class AgentHost {
             inboxCatchUp: resolved.inboxCatchUp,
             telemetryIngest: resolved.telemetryIngest,
             brain: resolved.brain,
+            polls: resolved.polls,
+            pollKinds: resolved.pollKinds,
             cognition: resolved.cognition ?? 'fsm',
             claudeMaxTurns: resolved.claudeMaxTurns,
             claudeStatelessPerWake: resolved.claudeStatelessPerWake,
@@ -263,12 +263,15 @@ export class AgentHost {
         // default.
         this.tickTimeoutMs =
             options.tickTimeoutMs ??
-                (isClaudeCognition(options.cognition)
+                (isClaudeCognition(resolved.cognition)
                     ? Number(process.env.CLAUDE_SDK_TICK_TIMEOUT_MS ?? 300_000)
                     : 120_000);
         this.memory = options.memory ?? new InMemoryStore();
         this.sessionStore = options.sessionStore ?? null;
         this._validate();
+        this.pollRunner = createDeclaredPollRunner(this.options, {
+            sendTo: (_agentId, text, metadata) => this.handleMessage(text, metadata ?? {}),
+        });
         this._setup();
     }
     _validate() {
@@ -331,7 +334,7 @@ export class AgentHost {
         }
         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
+            // still plugs into the agent'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 = {
@@ -342,7 +345,7 @@ export class AgentHost {
                 };
             }
             else {
-                throw new Error('AgentHost: workflow (or states + initial) is required');
+                throw new Error('Agent: workflow (or states + initial) is required');
             }
         }
         this.eff = createZiggsEffectHandler({
@@ -359,8 +362,8 @@ export class AgentHost {
             telemetryIngest: this.options.telemetryIngest,
             effectTap: this.options.effectTap,
         });
-        this.agent = isClaudeCognition(this.options.cognition)
-            ? new ClaudeSdkAgent({
+        this.brain = isClaudeCognition(this.options.cognition)
+            ? new ClaudeBrain({
                 workflow,
                 toolManager: services.toolManager,
                 description: this.options.description,
@@ -376,7 +379,7 @@ export class AgentHost {
                 maxTurns: this.options.claudeMaxTurns,
                 statelessPerWake: this.options.claudeStatelessPerWake,
             })
-            : new Agent({
+            : new ZiggsBrain({
                 workflow,
                 toolManager: services.toolManager,
                 promptBuilder: services.promptBuilder,
@@ -387,7 +390,7 @@ export class AgentHost {
         // than left as an unhandled rejection (made enqueue reject).
         this.stateTimers = new StateTimers((ev, laneKey) => {
             void this.eventQueue.enqueue(ev, laneKey).catch((err) => {
-                runtimeLog.warn('AgentHost', `state-timer frame failed laneKey=${laneKey}: ${err?.message || err}`);
+                runtimeLog.warn('Agent', `state-timer frame failed laneKey=${laneKey}: ${err?.message || err}`);
             });
         });
     }
@@ -429,7 +432,7 @@ export class AgentHost {
                     event.resourceId) ||
                 null;
             if (agreementId)
-                sessionId = `agrn-${agreementId}`;
+                sessionId = agreementLaneId(agreementId);
         }
         if (!sessionId)
             return;
@@ -456,14 +459,14 @@ export class AgentHost {
     async handleMessage(text, metadata = {}) {
         const messageId = metadata.messageId;
         if (messageId && this.seenMessages.has(messageId)) {
-            runtimeLog.debug('AgentHost', `skip duplicate messageId=${messageId}`);
+            runtimeLog.debug('Agent', `skip duplicate messageId=${messageId}`);
             return;
         }
         if (messageId)
             this.seenMessages.mark(messageId);
         const ownAgentId = this._resolveOwnAgentId();
         if (!ownAgentId) {
-            runtimeLog.warn('AgentHost', 'handleMessage: ownAgentId missing — dropping event');
+            runtimeLog.warn('Agent', 'handleMessage: ownAgentId missing — dropping event');
             return;
         }
         let enrichedText = typeof text === 'string' ? text : '';
@@ -483,14 +486,14 @@ export class AgentHost {
         const normalized = normalizeIncomingEvent({ text: enrichedText, metadata, ownAgentId });
         const sessionId = this.sessionResolver(normalized, ownAgentId);
         if (!sessionId) {
-            runtimeLog.warn('AgentHost', `session resolver returned null ownAgentId=${ownAgentId} chatId=${normalized.chatId ?? 'null'}`);
+            runtimeLog.warn('Agent', `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 });
         }
-        // The inbox loop owns ack (act-before-ack, delivery law); the host only
+        // The inbox loop owns ack (act-before-ack, delivery law); the agent only
         // routes the event onto its lane. No live-path watermark ack — there is no
         // separate live/push channel to reconcile against anymore.
         //
@@ -536,6 +539,13 @@ export class AgentHost {
             llmCalls,
         }), isTelemetryIngestEnabled(this.options.telemetryIngest));
     }
+    memoryForWake(session) {
+        return partitionMemoryStore(this.memory, memorySectionForWake({
+            sessionId: session.sessionId,
+            activeAgreementId: session.ctx
+                ?.activeAgreementId,
+        }));
+    }
     /**
      * A chat-lane session that still carries a cancelled hire from a previous
      * engagement will agreement_get that dead row and stop. Drop it so this
@@ -546,7 +556,7 @@ export class AgentHost {
         const pinned = ctx?.activeAgreementId;
         if (!pinned || !this.agreementService)
             return;
-        if (session.sessionId === `agrn-${pinned}`)
+        if (session.sessionId === agreementLaneId(pinned))
             return;
         try {
             const agreement = await this.agreementService.get(pinned);
@@ -564,9 +574,7 @@ export class AgentHost {
         }
     }
     async laneAgreementIsTerminal(sessionId) {
-        if (!sessionId.startsWith('agrn-'))
-            return false;
-        const agreementId = sessionId.slice('agrn-'.length);
+        const agreementId = agreementIdFromLane(sessionId);
         if (!agreementId || !this.agreementService)
             return false;
         try {
@@ -793,7 +801,7 @@ export class AgentHost {
                 }
             }
             catch (err) {
-                runtimeLog.warn('AgentHost', `sessionStore.load failed laneKey=${laneKey}: ${err?.message || err}`);
+                runtimeLog.warn('Agent', `sessionStore.load failed laneKey=${laneKey}: ${err?.message || err}`);
             }
         }
         await this.dropStaleCancelledAgreementSession(session);
@@ -802,6 +810,7 @@ export class AgentHost {
             sessionId: session.sessionId,
             laneKey,
         };
+        const memory = this.memoryForWake(session);
         // Recorded here rather than after the tick: this is the last point where the
         // input is still exactly what the brain will see, and a wake that goes on to
         // throw is the one most worth replaying.
@@ -817,7 +826,7 @@ export class AgentHost {
                 });
             }
             catch (err) {
-                runtimeLog.warn('AgentHost', `wakeTap failed: ${err?.message || err}`);
+                runtimeLog.warn('Agent', `wakeTap failed: ${err?.message || err}`);
             }
         }
         // The watchdog timer must be cleared once the tick settles — leaving it
@@ -842,7 +851,7 @@ export class AgentHost {
         };
         try {
             const result = await Promise.race([
-                this.agent.tick({ event: frame, ctx: session.ctx, state: session.state, identity, eff, memory: this.memory, transitionTap: this.options.transitionTap, signal: tickAbort.signal }),
+                this.brain.tick({ event: frame, ctx: session.ctx, state: session.state, identity, eff, memory, transitionTap: this.options.transitionTap, signal: tickAbort.signal }),
                 new Promise((_, reject) => {
                     tickWatchdog = setTimeout(() => {
                         tickAbort.abort(new Error('tick timeout'));
@@ -867,7 +876,7 @@ export class AgentHost {
             // 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} ` +
+                runtimeLog.info('Agent', `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: emit the tick's
@@ -885,12 +894,12 @@ export class AgentHost {
                     });
                 }
                 catch (err) {
-                    runtimeLog.warn('AgentHost', `metricsTap failed: ${err?.message || err}`);
+                    runtimeLog.warn('Agent', `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}`);
+                    runtimeLog.warn('Agent', `sessionStore.save failed laneKey=${laneKey}: ${err?.message || err}`);
                 });
             }
             // Arm only when the timeout was handled: an unhandled state-timeout must
@@ -919,12 +928,12 @@ export class AgentHost {
                 kind: 'no-op',
                 reason: 'tick_failed',
             });
-            runtimeLog.warn('AgentHost', `tick failed laneKey=${laneKey}: ${err?.message || err}`);
+            runtimeLog.warn('Agent', `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);
+            this._armIfTimedParked(laneKey, session.state ?? this.brain.workflow.initial);
             // Best-effort: also notify the user so the conversation isn't silently
             // stuck. Complements the timer re-arm above — that recovers a
             // parked lane; this tells a waiting human.
@@ -950,12 +959,12 @@ export class AgentHost {
         }
     }
     /**
-     * Re-run one recorded wake against THIS host's agent, and nothing else.
+     * Re-run one recorded wake against THIS agent, and nothing else.
      *
      * The dev loop for a prompt: record a wake off a live run, edit the agent, and
      * see what it does differently in seconds instead of standing a world back up
      * for one turn. The brain, tools and effect handler are the real ones, so the
-     * turn is real — its tool calls hit the backend this host is pointed at, which
+     * turn is real — its tool calls hit the backend this agent is pointed at, which
      * is why it belongs against a disposable world and not a shared one.
      *
      * Deliberately NOT routed through `_processEvent`: everything that method does
@@ -971,19 +980,23 @@ export class AgentHost {
             sessionId: record.sessionId,
             laneKey: record.laneKey || record.sessionId,
         };
+        const memory = this.memoryForWake({
+            sessionId: record.sessionId,
+            ctx: record.ctx,
+        });
         // Same watchdog as a live wake, for the same reason: an unaborted Claude
         // query outlives the promise that abandoned it and keeps spending.
         const abort = new AbortController();
         let watchdog;
         try {
             const result = await Promise.race([
-                this.agent.tick({
+                this.brain.tick({
                     event: record.event,
                     ctx: record.ctx,
                     state: record.state,
                     identity,
                     eff: this.eff,
-                    memory: this.memory,
+                    memory,
                     transitionTap: this.options.transitionTap,
                     signal: abort.signal,
                 }),
@@ -1006,7 +1019,7 @@ export class AgentHost {
                     });
                 }
                 catch (err) {
-                    runtimeLog.warn('AgentHost', `metricsTap failed: ${err?.message || err}`);
+                    runtimeLog.warn('Agent', `metricsTap failed: ${err?.message || err}`);
                 }
             }
             return result;
@@ -1019,25 +1032,33 @@ export class AgentHost {
     _armIfTimedParked(laneKey, stateName) {
         if (!stateName)
             return;
-        const sd = this.agent.workflow.states[stateName];
+        const sd = this.brain.workflow.states[stateName];
         if (sd?.kind !== 'parked' || sd.timeoutMs === undefined)
             return;
         this.stateTimers.arm(laneKey, stateName, sd.timeoutMs);
     }
     _resolveOwnAgentId() {
-        // The host is constructed for exactly one agent; its own id is the only
+        // The body is constructed for exactly one identity; its own id is the only
         // source. (The socket-frame-era metadata fallbacks — self/agent/ziggsAgentId
         // — are gone: nothing on the inbox wire ever carried them.)
         return this.options.agentId || null;
     }
     async connectAsync(_timeout) {
-        // Bootstrap active assigned tasks once (HTTP pull → lane), then start the
-        // per-agent inbox long-poll loop — the agent's sole wake source. There is
-        // no socket to connect and no reconnect: a crash is just the loop's next
-        // iteration (the cursor is server-side). `_timeout` is accepted for
-        // backward-compatible call sites but no longer gates a handshake.
+        if (this.started)
+            return this;
+        // Start the per-agent inbox long-poll loop — the agent's sole wake source.
+        // There is no socket to connect and no reconnect: a crash is just the
+        // loop's next iteration (the cursor is server-side). `_timeout` is accepted
+        // for backward-compatible call sites but no longer gates a handshake.
+        //
+        // There is no separate catch-up sweep here any more. `tasksAwaitingMe` is
+        // re-derived from the collection on every pass and redelivers an open
+        // assigned task until it closes, so the loop's first pass IS the catch-up —
+        // a restarted agent sees its standing work with nothing extra to run. The
+        // sweep that used to sit here pulled the same list over
+        // `GET /agents/:id/tasks` and reached one gate the inbox does not, which is
+        // how a withheld join node got handed to its assignee before its turn.
         if (this.inboxLoopEnabled) {
-            await this._bootstrapAssignedActiveTasks();
             const label = this.options.name || 'agent';
             this.inboxLoop = runInboxLoop({
                 creds: {
@@ -1070,10 +1091,12 @@ export class AgentHost {
                 },
             });
         }
+        this.pollRunner?.start();
+        this.started = true;
         return this;
     }
     /**
-     * plain string compare against {@link AgentHostOptions.requestMatchTags}
+     * plain string compare against {@link AgentOptions.requestMatchTags}
      * and `specialization`. No match → return (caller acks). Match → normal wake.
      */
     async triageRequestDelivery(request) {
@@ -1093,52 +1116,6 @@ export class AgentHost {
             agreementId: request.agreementId,
         });
     }
-    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 = laneSessionIdForTask(full);
-            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: sessionId,
-            }, laneKey);
-        }
-    }
     /** replay task-assigned for an existing active task (demo recovery). */
     async wakeTaskAssignment(taskId) {
         const agentId = this.options.agentId;
@@ -1166,7 +1143,13 @@ export class AgentHost {
             chatId: sessionId,
         }, laneKey);
     }
-    disconnect() { this.stateTimers.clearAll(); void this.inboxLoop?.stop(); this.inboxLoop = null; }
+    disconnect() {
+        this.started = false;
+        this.pollRunner?.stop();
+        this.stateTimers.clearAll();
+        void this.inboxLoop?.stop();
+        this.inboxLoop = null;
+    }
     /**
      * Waits for in-flight ticks to finish. Call before process.exit() on SIGTERM.
      * A timeout is returned, not thrown — the caller names it (lab verdict, fleet
@@ -1174,20 +1157,43 @@ export class AgentHost {
      */
     drain(timeoutMs = 30_000) { return this.eventQueue.waitForIdle(timeoutMs); }
     registerTool(tool) { return this.toolManager.register(tool); }
-    isConnected() { return this.inboxLoop?.running ?? false; }
+    isConnected() { return this.started && (!this.inboxLoopEnabled || (this.inboxLoop?.running ?? false)); }
+    /**
+     * Whether this agent is still reading its inbox, and when it last did. One
+     * signal, three readers: the store's online badge, an operator's health
+     * check, and monitoring. `lastPassAt` is the read itself; `lastAttemptAt`
+     * says the loop still turns when the server is the thing that is down.
+     * A `pollingInbox: false` agent (inboxCatchUp disabled, lab and eval paths)
+     * has nothing to be stale about and reports no timestamps.
+     */
+    inboxLiveness() {
+        return {
+            agentId: this.options.agentId,
+            connected: this.isConnected(),
+            pollingInbox: this.inboxLoopEnabled,
+            lastPassAt: this.inboxLoop?.lastPassAt ?? null,
+            lastAttemptAt: this.inboxLoop?.lastAttemptAt ?? null,
+        };
+    }
 }
 /**
- * createAgent(config)            → AgentHost
+ * createAgent(config)            → Agent
  * createAgentPool([cfg, ...])    → ConnectionPool (lazy fleet, async-loaded)
  */
 export function createAgent(options = {}) {
-    return new AgentHost(options);
+    return new Agent(options);
 }
 export async function createAgentPool(configs) {
     const ConnectionPool = await loadConnectionPool();
     const pool = new ConnectionPool();
     pool.register(configs);
-    await pool.connectAll();
-    return pool;
+    try {
+        await pool.connectAll();
+        return pool;
+    }
+    catch (err) {
+        await pool.shutdown();
+        throw err;
+    }
 }
-export default AgentHost;
+export default Agent;

package/dist/adapters/AnthropicAdapter.d.ts

@@ -7,7 +7,7 @@ interface AdapterOptions {
 /**
  * Anthropic adapter satisfying the same LlmAdapter contract as OpenAIAdapter:
  * OpenAI-wire-shaped LlmMessage[] in, { content, tool_calls, usage } out.
- * Selected by AgentHost when the configured model id starts with "claude".
+ * Selected by Agent when the configured model id starts with "claude".
  */
 export declare class AnthropicAdapter {
     private client;

package/dist/adapters/AnthropicAdapter.js

@@ -8,7 +8,7 @@ const MAX_COMPLETION_TOKENS = 16000;
 /**
  * Anthropic adapter satisfying the same LlmAdapter contract as OpenAIAdapter:
  * OpenAI-wire-shaped LlmMessage[] in, { content, tool_calls, usage } out.
- * Selected by AgentHost when the configured model id starts with "claude".
+ * Selected by Agent when the configured model id starts with "claude".
  */
 export class AnthropicAdapter {
     client;