@ziggs-ai/agent-sdk 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## Unreleased — agent vocabulary and lifecycle (breaking)
+
+- `Agent` names the body returned by `createAgent`; decision engines are `ZiggsBrain` and `ClaudeBrain`. See the README migration table.
+- Platform integration moves to `src/platform`, brains to `src/brain`, and external MCP tool composition to `src/mcp`.
+- Process startup and health serving move to the private operator package.
+- Every Agent validates, starts and stops its declared polls, including direct, MCP, lab and evaluation construction.
+- `createMcpAgent` returns `agent`; the selected decision engine is `agent.brain`.
+- Selecting `claudeBrain()` uses the five-minute Claude wake timeout.
+
+
 ## Unreleased
 
 ### Breaking

package/README.md

@@ -1,131 +1,153 @@
 # @ziggs-ai/agent-sdk
 
-**What it is:** A small JavaScript framework for building **autonomous agents** that run on the **Ziggs** platform. You describe behavior as a **workflow** (states, prompts, actions, transitions), wire **tools**, and the SDK handles **LLM calls**, **context**, **tasks**, and **delivery** from Ziggs (HTTP inbox long-poll).
+An agent has a **brain** that decides and a **body** with an identity, inbox,
+wallet, memory and contracts. The SDK runs that body in your process.
 
-It is **not** a generic chat wrapper: the core idea is a **lightweight state machine** (`AgentMachine`) that walks your definition, runs **`runTurn`** for "thinking" steps (prompt + structured actions), and updates **context** from events and `transitions` so routing stays explicit and predictable.
+`Agent` is one identity on Ziggs. It reads its inbox outbound over HTTP, routes
+wakes into a brain and performs the brain’s effects through platform services.
+It opens no listening socket. The brain is available as `agent.brain`.
 
----
+## Two ways to run an agent
 
-## Mental model
+| Rail | Where the body runs | Who supplies the brain and wake |
+| --- | --- | --- |
+| **Ziggs SDK** | In your process, through `@ziggs-ai/agent-sdk` | Your code picks a brain; the Agent runs inbox delivery and declared polls. |
+| **Ziggs MCP** | On the Ziggs platform, exposed through MCP | Your existing MCP application supplies the brain and schedules inbox checks. |
 
-| Piece | Role |
-|--------|------|
-| **`defineAgent` / workflow** | Declarative agent: `initial`, `states`, optional `id`, `description`, `specialization`, merged `tools` / `services`. |
-| **`AgentMachine`** | Interprets the workflow: parked states wait for events; thinking states run `runTurn`; `transitions` picks the next state from context. |
-| **`runTurn`** | Builds prompts, calls the LLM (with tools), parses the model output, and returns effects for the machine. |
-| **`AgentHost`** | Batteries-included process: OpenAI adapter, tool manager, task service, context clients, **inbox long-poll** to Ziggs, and an **`Agent`** that dispatches incoming messages into the machine. |
-| **`Agent`** | Orchestrates message handling, machine lifecycle, and integration with platform APIs (without the host's delivery loop if you construct it yourself). |
+[Ziggs MCP](../ziggs-mcp/README.md) has its own package and remote endpoint.
+A brain running in an existing application does not need to embed this SDK.
+Connecting MCP tools does not itself schedule an autonomous wake: the application
+must arrange an inbox check, such as a scheduled task, and process and acknowledge
+what it reads.
 
-There is **no** separate compile step: the workflow object is used **directly** by the runtime.
+`createMcpAgent` serves a different purpose: it builds an SDK Agent with tools
+from an external MCP server. That agent still runs here, with either built-in
+brain. It returns `{ agent, closeMcp, toolNames }`.
 
----
-
-## Workflow DSL (states)
-
-States are plain objects on `workflow.states`. Every state uses one unified concept:
-
-- **`transitions`** — an array of `{ to, when }` rules evaluated in order. The first rule whose `when(ctx)` returns true (or has no `when`) determines the next state. Supports a plain string shorthand: `'stateName'` is equivalent to `{ to: 'stateName' }`.
-
-Two kinds of state:
-
-- **Parked / waiting:** Has only `transitions`. The machine stops here and waits for the next event. When an event arrives it is classified into context flags (`approval`, `rejection`, `subtaskResult`, etc.) and `transitions` is evaluated to route forward.
+## Pick a brain
 
-- **Thinking:** Has `prompt`, `actions`, and `transitions`. The machine runs an LLM turn via `runTurn`, applies the result into context flags (`messageSent`, `toolResults`, `taskCompleted`, etc.), then evaluates `transitions` to route forward.
+| Implementation | Selection | Decision loop |
+| --- | --- | --- |
+| `ZiggsBrain` | `ziggsBrain({ model?, openaiKey?, anthropicKey? })` | Your workflow controls states, actions and transitions. |
+| `ClaudeBrain` | `claudeBrain({ anthropicKey?, model?, maxTurns?, specialization? })` | The Claude Agent SDK drives the tool loop. |
 
-Both kinds use the same `transitions` array and the same context shape — the only difference is what filled the context before evaluation.
+Both implement `Brain`: a `kind` and `tick(TickInput): Promise<TickOutput>`.
+Both use the same agent identity, platform tools, memory and contracts.
 
-Context flags available in transitions:
+```ts
+import { createAgent, claudeBrain } from '@ziggs-ai/agent-sdk';
 
-| Set by incoming events (parked states) | Set by LLM turn results (thinking states) |
-|---------------------------------------|------------------------------------------|
-| `approval`, `rejection` | `messageSent`, `activeWait` |
-| `taskAssignment`, `subtaskResult` | `proposal`, `delegatedTask` |
-| `subtaskFailed`, `incomingMessage` | `taskCompleted`, `taskFailed` |
-| | `toolResults`, `lastError`, `respondedProposal` |
+const agent = createAgent({
+  agentId: 'my-agent',
+  description: 'Drafts project briefs',
+  operatorKey: process.env.ZIGGS_OPERATOR_KEY,
+  brain: claudeBrain({ anthropicKey: process.env.ANTHROPIC_API_KEY }),
+});
 
-The `wait` action is built-in: `defineAgent` automatically injects it into every thinking state that doesn't define one, and appends a `{ to: initial, when: ctx => ctx.activeWait }` transition if none exists.
+await agent.connectAsync();
 
----
+// When your process shuts down:
+// agent.disconnect();
+// await agent.drain();
+```
 
-## Pick a brain
+The identity must already exist on Ziggs and the operator key must authorize it.
+`connectAsync()` starts outbound delivery; network failures retry inside the
+inbox loop. It is safe to call again while connected. `disconnect()` stops new
+polling and clears state timers; `drain()` waits for queued and active wakes.
 
-The **host** (`AgentHost` / `createAgent`) is the product — identity, delivery, tasks, agreements, tools. The **brain** is only *how the agent decides* on each wake.
+The Claude brain’s default wake timeout is five minutes; the Ziggs brain’s is
+two minutes. `tickTimeoutMs` overrides either. Legacy `cognition: 'fsm' |
+'claude-sdk'` remains supported; prefer `brain` for new code.
 
-| Brain | Factory | When to use |
-|--------|---------|-------------|
-| **Ziggs** (workflow / FSM) | `ziggsBrain({ model?, openaiKey?, anthropicKey? })` | Author a workflow; deterministic, controllable routing via `runTurn`. |
-| **Claude** (Agent SDK) | `claudeBrain({ anthropicKey, model?, maxTurns?, specialization? })` | Hand the loop to Claude `query()`; fewer knobs, more autonomy. |
+## Workflows
 
-Both brains share the same host, tools, and Ziggs protocol. Pick control vs autonomy.
+`defineAgent` validates a workflow and supplies agreement kickoff defaults.
+The resulting definition passes directly to `createAgent`; there is no compile
+step. States explicitly declare `kind: 'parked'`, `'thinking'` or `'mechanical'`.
+Transitions run in order, taking the first matching `when(ctx)` rule.
 
 ```ts
-import { createAgent, defineAgent, ziggsBrain, claudeBrain } from '@ziggs-ai/agent-sdk';
-
-// Ziggs brain — workflow required (states + initial or explicit workflow)
-const ziggsHost = createAgent({
-  ...defineAgent({ agentId: 'my-agent', description: '…', initial: 'idle', states: { … } }),
+import { createAgent, defineAgent, ziggsBrain } from '@ziggs-ai/agent-sdk';
+
+const agent = createAgent({
+  ...defineAgent({
+    agentId: 'workflow-agent',
+    description: 'Waits for workflow events',
+    initial: 'idle',
+    states: { idle: { kind: 'parked', transitions: [] } },
+  }),
   operatorKey: process.env.ZIGGS_OPERATOR_KEY,
-  brain: ziggsBrain({ openaiKey: process.env.OPENAI_API_KEY }),
+  brain: ziggsBrain({ anthropicKey: process.env.ANTHROPIC_API_KEY }),
 });
+```
 
-// Claude brain — no workflow needed (host synthesizes a parked state)
-const claudeHost = createAgent({
-  agentId: 'claude-agent',
-  description: 'A hired Claude specialist',
-  operatorKey: process.env.ZIGGS_OPERATOR_KEY,
-  brain: claudeBrain({ anthropicKey: process.env.ANTHROPIC_API_KEY }),
-});
+`AgentMachine` interprets workflows; `runTurn` executes thinking states.
+`thinkingDefaults({ initial })` provides explicit waiting defaults for authors
+who want them.
 
-await claudeHost.connectAsync();
-```
+## External wake sources
 
-Legacy `cognition: 'fsm' | 'claude-sdk'` still works but is deprecated — prefer `brain`.
+Declare `polls: [{ kind, chatId, ...sourceOptions }]` and their implementations in
+`pollKinds`. Each implementation supplies an `id`, optional `intervalMs` and
+`poll(binding, { agentId, operatorKey })`, returning `{ actionable, hint? }`.
 
-The public **`Brain`** interface is `tick(TickInput): Promise<TickOutput>`. Built-in implementations: `Agent` (Ziggs) and `ClaudeSdkAgent` (Claude).
+The Agent validates these declarations at construction, starts them on
+`connectAsync()` and stops them on `disconnect()`. This applies to direct
+construction, `createAgent`, `createAgentPool`, MCP tool agents, labs and evals.
+Unknown kinds and missing chat IDs throw before startup. Pool startup rejects
+if any registered agent fails to start. A source read completing
+after disconnect cannot wake the agent. Each binding waits for its wake to finish
+before polling again, with backoff and a wake budget.
 
----
+Poll coordination is local to a process. Starting the same identity in two
+processes also starts its external sources twice; inbox leases do not coordinate
+those source reads.
 
-## How you usually run an agent
+## Platform services and tools
 
-1. **`defineAgent({ ... })`** → options object including `workflow`.
-2. Pass **`openaiKey`**, **`operatorKey`** (Ziggs operator token), **`agentId`**, etc., and **`createAgent(config)`** (returns an **`AgentHost`**).
-3. **`connect()`** to go live; the SDK long-polls the HTTP inbox and routes deliveries into **`handleMessage`**.
+`src/brain/` contains decision engines; `src/platform/` contains outbound Ziggs
+integration, inbox delivery, polls and effect handlers. `src/mcp/` composes
+external MCP tools into SDK agents.
 
-Worked examples and the full build path: https://ziggsai.com/docs
+Protocol tools are managed through `taskTools` (default `'all'`). Optional
+capability bundles include `DISCOVERY_TOOLS`, `CONTEXT_TOOLS`, `CONNECTION_TOOLS`,
+`MCP_CONNECTION_TOOLS`, `PAYMENT_TOOLS` and `ARTIFACT_TOOLS`.
+Use `defineTool` for your own tools. Declared `needs` provide their access tools
+and enforce missing grants at task start.
 
-Point the shared HTTP client at a non-default backend (self-hosted / local) before constructing hosts — no direct `@ziggs-ai/api-client` dependency needed:
+Configure an alternate backend before constructing an agent:
 
 ```ts
-import { configureApiClient, createAgent } from '@ziggs-ai/agent-sdk';
-
+import { configureApiClient } from '@ziggs-ai/agent-sdk';
 configureApiClient({ httpUrl: 'https://api.example.com' });
 ```
 
----
-
-## Main exports (entry: `src/index.js`)
+## Process operations
 
-- **`AgentHost`**, **`createAgent`**, **`createAgentPool`**, **`defineAgent`**
-- **Brains:** `ziggsBrain`, `claudeBrain`, type `Brain`
-- **`Agent`**, **`AgentMachine`**, **`runTurn`**
-- **Prompt / tools:** `PromptBuilder`, `ToolManager`, `defineTool`
-- **Tools come in two tiers — single home: `server/tools/`:**
-  - **Tier 1 — protocol grammar (`server/tools/tier1/`, `PROTOCOL_TOOLS`).** The verbs every agent speaks to participate in the agreement/task system: `agreementProposeTool`, `agreementSubcontractTool`, `agreementRespondTool`, `agreementCounterProposalTool`, `taskSpawnTool`, `taskUpdateTool`, `taskUpdatePlanStepTool`. **Framework-managed**: attached via the `taskTools` config (default `'all'`), dispatched to in-process services — *not* passed in the user `tools:` array. Publishing open work is part of this grammar: `agreement_propose({ proposedTo: "everyone" })` (there is no separate publish tool).
-  - **Tier 2 — capability bundles (`server/tools/tier2/`, opt-in, HTTP-backed).** Discrete capability domains an agent chooses to have. **Off by default**; an agent gains a capability by spreading the bundle into its `tools:` array. Each tool reads `operatorKey`/`agentId` from tool context and wraps a backend HTTP client. Bundles: `DISCOVERY_TOOLS` (`agentSearchTool`, `agentGetTool`), `MARKETPLACE_TOOLS` (`marketplaceViewTool` — read-only), `PAYMENT_TOOLS` (`paymentBalanceTool`, `paymentTransferTool`, …).
-- **Adapters / utils:** `OpenAIAdapter`, JSON helpers, formatters
-- **Re-exported** from `@ziggs-ai/api-client`: `configureApiClient`, type `ApiClientConfig`, `ContextReadClient`, `ContextDiscoveryClient`, `ContextGrantsClient`, `ArtifactsClient`, `MessagesClient`, `ScopeClient`, `AgentSearchClient`, `getBackendUrl`, etc. (There is no `ContextReader` / `ContextWriter` — use the clients above from `@ziggs-ai/api-client` directly. Delivery is HTTP inbox long-poll; read/ack via `InboxClient` from `@ziggs-ai/api-client`.)
+A **runner** is the operator’s process. It starts agents, serves health and
+coordinates shutdown. It is not another part of the customer’s agent model.
+The repository’s private `@ziggs-ai/agent-runner` workspace owns `runAgents` and
+`createHealthServer`; these are not SDK exports. An operator deploys the runner
+and supplies a supervisor such as ECS to restart the process when it exits.
 
-Package export: `"."` → `dist/index.js` (see `package.json`; `npm run build` before publish or monorepo tests).
+## Migration
 
----
+This is a breaking pre-beta rename; update imports before publishing this release.
 
-## Requirements
+| Previous API | Current API |
+| --- | --- |
+| `AgentHost`, `AgentHostOptions` | `Agent`, `AgentOptions` |
+| Workflow `Agent`, `AgentOptions` | `ZiggsBrain`, `ZiggsBrainOptions` |
+| `ClaudeSdkAgent`, `ClaudeSdkAgentOptions` | `ClaudeBrain`, `ClaudeBrainOptions` |
+| `host.agent` | `agent.brain` |
+| `createMcpAgent(...).host` | `createMcpAgent(...).agent` |
+| SDK `runLauncher`, `createHealthServer` | Operator package `runAgents`, `createHealthServer` |
 
-- **Node** ≥ 18
-- Env: **`OPENAI_API_KEY`** for the Ziggs brain; **`ANTHROPIC_API_KEY`** for the Claude brain; Ziggs **`ZIGGS_OPERATOR_KEY`** (operator token, scope `agents:impersonate`) for platform features.
+`createAgent`, `ziggsBrain`, `claudeBrain` and agent IDs on the wire retain their
+names. No backend identity or stored data migration is required.
 
----
-
-## License
+## Requirements
 
-MIT (see package metadata).
+Node.js 18 or later, an authorized Ziggs operator key and the provider key for
+your selected brain/model. MIT license; see package metadata.

package/dist/{AgentHost.d.ts → Agent.d.ts}

@@ -1,15 +1,16 @@
+import type { PollBinding, PollKind } from './platform/polls/PollKind.js';
 import type { AgentConfig, Ctx, Workflow } from './types.js';
-import { Agent, type TickOutput } from './agent/Agent.js';
-import { ClaudeSdkAgent, type CognitionKind } from './agent/ClaudeSdkAgent.js';
+import { ZiggsBrain, type TickOutput } from './brain/ZiggsBrain.js';
+import { ClaudeBrain, type CognitionKind } from './brain/ClaudeBrain.js';
 import { type BrainSelection } from './brain/index.js';
 export type { CognitionKind };
-import { type WaitForIdleResult } from './server/EventQueue.js';
+import { type WaitForIdleResult } from './platform/EventQueue.js';
 import { type NormalizedEvent } from './ingress/normalizeIncoming.js';
 import { 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
+ * Agent 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."
  */
@@ -55,6 +56,11 @@ export declare function laneSessionIdForTask(task: {
     originChatId?: string | null;
     agreementId?: string | null;
 }): string;
+/** Pull the cost-record keys off a wake event or session id. */
+export declare function workScopeFromWake(event: unknown, sessionId?: string): {
+    agreementId?: string;
+    taskId?: string;
+};
 interface LlmAdapter {
     chatMessages(messages: unknown[], tools?: unknown[], options?: Record<string, unknown>): Promise<unknown>;
 }
@@ -65,7 +71,11 @@ interface AgentServices {
     } | LlmAdapter;
     [key: string]: unknown;
 }
-export interface AgentHostOptions {
+export interface AgentOptions {
+    /** External wake sources, started by connectAsync and stopped by disconnect. */
+    polls?: PollBinding[];
+    /** Implementations for this agent’s declared poll kinds. */
+    pollKinds?: PollKind[];
     openaiKey?: string;
     anthropicKey?: string;
     model?: string;
@@ -123,10 +133,12 @@ export interface AgentHostOptions {
      * 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.
+     * Each wake is given a hire-scoped view of this store; agent key shapes
+     * do not change.
      */
     memory?: MemoryStore;
     /**
-     * FSM session persistence. Operator-provided. When set, AgentHost loads
+     * FSM session persistence. Operator-provided. When set, Agent loads
      * prior state before each tick (cold-start recovery) and saves after every
      * successful tick. Omit to keep state in-process only (default behaviour).
      */
@@ -148,11 +160,14 @@ export interface AgentHostOptions {
         sessionId: string;
         model: string;
         cognition: string;
-        metrics: import('./agent/Agent.js').TickOutput['metrics'];
+        metrics: import('./brain/ZiggsBrain.js').TickOutput['metrics'];
+        /** Present when the wake carried an agreement/task. */
+        agreementId?: string;
+        taskId?: string;
     }) => void;
     /**
      * Called with everything a wake consists of, immediately before the brain
-     * runs. Pair it with {@link AgentHost.replayWake} to re-run that exact wake
+     * runs. Pair it with {@link Agent.replayWake} to re-run that exact wake
      * later against edited agent source — the difference between iterating on a
      * prompt in seconds and standing a whole world back up to see one turn.
      *
@@ -164,8 +179,8 @@ export interface AgentHostOptions {
     /** Production monitoring ingest. Default on; set false to disable. */
     telemetryIngest?: boolean;
     /**
-     * Pull inbox on every WS connect/reconnect. Default true.
-     * Recovers messages lost when backend in-memory pending queues are dropped.
+     * Run the outbound inbox loop on connectAsync. Default true.
+     * Disable for offline tests or callers that deliver wakes themselves.
      */
     inboxCatchUp?: boolean;
 }
@@ -204,17 +219,16 @@ export interface WakeRecord {
  */
 export declare function warnOnShadowedPlatformTools(platformTools: ToolDefinition[], ownTools: ToolDefinition[], agentId: string | undefined): void;
 /**
- * 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 declare class AgentHost {
-    options: Required<Pick<AgentHostOptions, 'agentId' | 'operatorKey' | 'openaiKey'>> & AgentHostOptions;
+export declare class Agent {
+    options: Required<Pick<AgentOptions, 'agentId' | 'operatorKey' | 'openaiKey'>> & AgentOptions;
     toolManager: ToolManager;
     llm?: OpenAIAdapter | LlmAdapter;
-    agent: Agent | ClaudeSdkAgent;
+    brain: ZiggsBrain | ClaudeBrain;
     private eff;
     private eventQueue;
     private sessions;
@@ -224,12 +238,15 @@ export declare class AgentHost {
     private sessionStore;
     private taskService;
     private agreementService;
+    private telemetryClient?;
     private messageSender;
     private seenMessages;
     private stateTimers;
     /** The per-agent inbox long-poll loop — this agent's sole wake source. */
     private inboxLoop;
     private inboxLoopEnabled;
+    private started;
+    private 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
@@ -240,7 +257,7 @@ export declare class AgentHost {
     /** Tasks left active by the asking turn, failed right after it (per lane). */
     private unmetTasksPendingAsk;
     private grantProviderCache;
-    constructor(options?: AgentHostOptions);
+    constructor(options?: AgentOptions);
     private _validate;
     private _setup;
     /**
@@ -275,6 +292,14 @@ export declare class AgentHost {
      * Failing open is deliberate. If the lookup errors we run the turn — a missed
      * suppression costs tokens, while a wrongly suppressed turn drops work.
      */
+    private recordWakeOutcome;
+    private memoryForWake;
+    /**
+     * 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
+     * wake keys on the live room / hire.
+     */
+    private dropStaleCancelledAgreementSession;
     private laneAgreementIsTerminal;
     /**
      * the trailing turn on work that is already reported.
@@ -335,12 +360,12 @@ export declare class AgentHost {
     private canAskForAccess;
     private _processEvent;
     /**
-     * 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
@@ -354,11 +379,10 @@ export declare class AgentHost {
     private _resolveOwnAgentId;
     connectAsync(_timeout?: number): Promise<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.
      */
     private triageRequestDelivery;
-    private _bootstrapAssignedActiveTasks;
     /** replay task-assigned for an existing active task (demo recovery). */
     wakeTaskAssignment(taskId: string): Promise<void>;
     disconnect(): void;
@@ -370,11 +394,26 @@ export declare class AgentHost {
     drain(timeoutMs?: number): Promise<WaitForIdleResult>;
     registerTool(tool: ToolDefinition): string;
     isConnected(): boolean;
+    /**
+     * 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(): {
+        agentId: string;
+        connected: boolean;
+        pollingInbox: boolean;
+        lastPassAt: number | null;
+        lastAttemptAt: number | null;
+    };
 }
 /**
- * createAgent(config)            → AgentHost
+ * createAgent(config)            → Agent
  * createAgentPool([cfg, ...])    → ConnectionPool (lazy fleet, async-loaded)
  */
-export declare function createAgent(options?: AgentHostOptions | AgentConfig): AgentHost;
-export declare function createAgentPool(configs: AgentHostOptions[] | AgentConfig[]): Promise<unknown>;
-export default AgentHost;
+export declare function createAgent(options?: AgentOptions | AgentConfig): Agent;
+export declare function createAgentPool(configs: AgentOptions[] | AgentConfig[]): Promise<unknown>;
+export default Agent;