@agentchatme/openclaw 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,756 @@
+import { A as AgentchatChannelConfig } from './setup-entry-CU0vHfyd.js';
+export { a as AGENTCHAT_CHANNEL_ID, b as AGENTCHAT_DEFAULT_ACCOUNT_ID, c as AgentchatResolvedAccount, d as agentchatChannelEntry, e as agentchatPlugin, f as agentchatSetupEntry, e as agentchatSetupPlugin, d as default, p as parseChannelConfig } from './setup-entry-CU0vHfyd.js';
+import { ChannelSetupWizard } from 'openclaw/plugin-sdk/channel-setup';
+export { hasAgentChatConfiguredState } from './configured-state.js';
+import { WebSocket } from 'ws';
+import 'openclaw/plugin-sdk/channel-core';
+import 'zod';
+
+/**
+ * Minimal HTTP client used by the setup plugin (P7) to:
+ *   - verify an API key is live before finalizing setup (`validateApiKey`)
+ *   - drive the email-OTP self-registration flow for agents without a key yet
+ *     (`registerAgentStart` → `registerAgentVerify`)
+ *
+ * Why this lives separately from `outbound.ts`:
+ *   - `outbound.ts` is the hot-path message sender. It wants retries, a circuit
+ *     breaker, metrics, and a long-lived `fetch`. Setup is one-shot, low-rate,
+ *     user-interactive — a 200ms validation call doesn't need any of that.
+ *   - Setup runs before the runtime exists; coupling it to `OutboundAdapter`
+ *     (which expects a parsed `AgentchatChannelConfig`) would force an odd
+ *     partial-config path during registration.
+ *
+ * The server endpoints this module targets are stable AgentChat REST calls:
+ *   - `GET  /v1/agents/me`          → 200 OK when the key authenticates
+ *   - `POST /v1/register`           → 200 with `{ pending_id }`
+ *   - `POST /v1/register/verify`    → 201 with `{ agent, api_key }` on success
+ *
+ * All methods return strongly-typed result unions — setup UIs can `switch` on
+ * the discriminant without guessing at HTTP status codes.
+ */
+/** Subset of the AgentChat agent row the setup surface needs to show the user. */
+interface AgentchatAgentIdentity {
+    readonly handle: string;
+    readonly displayName: string | null;
+    readonly email: string;
+    readonly createdAt: string;
+}
+type ValidateApiKeyResult = {
+    readonly ok: true;
+    readonly agent: AgentchatAgentIdentity;
+} | {
+    readonly ok: false;
+    /** High-level reason code the UI can map to a localized message. */
+    readonly reason: 'unauthorized' | 'forbidden' | 'deleted' | 'network-error' | 'unreachable' | 'server-error' | 'unexpected-shape';
+    readonly message: string;
+    readonly status?: number;
+};
+interface ValidateApiKeyOptions {
+    readonly apiBase?: string;
+    readonly fetch?: typeof fetch;
+    readonly timeoutMs?: number;
+}
+/**
+ * Probe the API key against `GET /v1/agents/me`. Returns a discriminated
+ * result — never throws on HTTP or network errors. The caller decides how
+ * to surface each failure mode to the user.
+ */
+declare function validateApiKey(apiKey: string, opts?: ValidateApiKeyOptions): Promise<ValidateApiKeyResult>;
+interface RegisterAgentStartInput {
+    readonly email: string;
+    readonly handle: string;
+    readonly displayName?: string;
+    readonly description?: string;
+}
+type RegisterStartResult = {
+    readonly ok: true;
+    readonly pendingId: string;
+} | {
+    readonly ok: false;
+    readonly reason: 'invalid-handle' | 'handle-taken' | 'email-taken' | 'email-is-owner' | 'email-exhausted' | 'rate-limited' | 'otp-failed' | 'network-error' | 'server-error' | 'validation';
+    readonly message: string;
+    readonly status?: number;
+    readonly retryAfterSeconds?: number;
+};
+interface RegisterAgentVerifyInput {
+    readonly pendingId: string;
+    readonly code: string;
+}
+type RegisterVerifyResult = {
+    readonly ok: true;
+    readonly apiKey: string;
+    readonly agent: AgentchatAgentIdentity;
+} | {
+    readonly ok: false;
+    readonly reason: 'expired' | 'invalid-code' | 'rate-limited' | 'handle-taken' | 'email-taken' | 'email-is-owner' | 'network-error' | 'server-error' | 'unexpected-shape' | 'validation';
+    readonly message: string;
+    readonly status?: number;
+    readonly retryAfterSeconds?: number;
+};
+interface RegisterOptions {
+    readonly apiBase?: string;
+    readonly fetch?: typeof fetch;
+    readonly timeoutMs?: number;
+}
+/**
+ * Kick off an email-OTP registration. Server caches the intent under a
+ * `pending_id` for 10 minutes and emails a 6-digit code to `email`.
+ */
+declare function registerAgentStart(input: RegisterAgentStartInput, opts?: RegisterOptions): Promise<RegisterStartResult>;
+/** Verify the OTP the user received by email and mint the API key. */
+declare function registerAgentVerify(input: RegisterAgentVerifyInput, opts?: RegisterOptions): Promise<RegisterVerifyResult>;
+/**
+ * Throw-flavored wrapper used by callers that prefer exception control flow
+ * (the setup plugin's `afterAccountConfigWritten` hook). Converts a failure
+ * result into an `AgentChatChannelError` with an appropriate class.
+ */
+declare function assertApiKeyValid(apiKey: string, opts?: ValidateApiKeyOptions): Promise<AgentchatAgentIdentity>;
+
+/**
+ * Interactive setup wizard for the AgentChat channel.
+ *
+ * Invoked by `openclaw channels add --channel agentchat`. Drives three branches:
+ *
+ *   - edit     — existing config → re-validate OR rotate OR change API base
+ *   - have-key — user pastes an existing ac_live_* key → /agents/me probe → write
+ *   - register — email + handle + description → /register + OTP → /register/verify
+ *
+ * All branches converge on `writeAccountPatch` which mutates
+ * `channels.agentchat.<accountId>` in either flat or multi-account form.
+ *
+ * Every server-side failure mode surfaces as actionable copy — there are no
+ * silent failures. The wizard only returns when the user has either finished
+ * or explicitly chosen to abort.
+ */
+
+declare const agentchatSetupWizard: ChannelSetupWizard;
+
+interface Logger {
+    trace(obj: object, msg?: string): void;
+    debug(obj: object, msg?: string): void;
+    info(obj: object, msg?: string): void;
+    warn(obj: object, msg?: string): void;
+    error(obj: object, msg?: string): void;
+    child(bindings: Record<string, unknown>): Logger;
+}
+
+/**
+ * Optional Prometheus metrics for the channel plugin.
+ *
+ * Design: the gateway owns the `/metrics` endpoint. Plugins do not expose
+ * their own port. If the user passes a `prom-client` Registry via channel
+ * runtime context, we register our counters/gauges/histograms into it.
+ * Otherwise, we return a no-op recorder — zero overhead, zero config.
+ *
+ * Names are prefixed with `agentchat_channel_` for easy scraping.
+ */
+interface MetricsRecorder {
+    /** Incremented on every successfully delivered inbound message. */
+    incInboundDelivered(labels: {
+        kind: InboundKind;
+    }): void;
+    /** Incremented on every successfully sent outbound message. */
+    incOutboundSent(labels: {
+        kind: OutboundKind;
+    }): void;
+    /** Incremented on every send failure, labeled by error class. */
+    incOutboundFailed(labels: {
+        errorClass: string;
+    }): void;
+    /** Incremented on every reconnect attempt. */
+    incReconnect(labels: {
+        reason: string;
+    }): void;
+    /** Observe end-to-end send latency (ms). */
+    observeSendLatency(ms: number): void;
+    /** Set the current connection state (cardinality bounded by state kinds). */
+    setConnectionState(kind: string): void;
+    /** Set the current in-flight send queue depth. */
+    setInFlightDepth(n: number): void;
+}
+type InboundKind = 'message' | 'group-message' | 'typing' | 'read' | 'presence' | 'rate-limit-warning';
+type OutboundKind = 'message' | 'typing' | 'read';
+
+/**
+ * Error taxonomy for the AgentChat channel plugin.
+ *
+ * Every error that crosses a pipeline boundary (inbound receive, outbound
+ * send, config validation, transport) must be classifiable as one of:
+ *
+ *   terminal-auth       — 401/403. API key invalid or revoked. Do not retry.
+ *                         Move state machine to AUTH_FAIL.
+ *   terminal-user       — 400/422 (client-side validation). Bug in this plugin
+ *                         or malformed outbound. Log at error level, drop,
+ *                         do not retry.
+ *   retry-rate          — 429. Retry after `retryAfterMs` (or jittered
+ *                         exponential backoff if header absent).
+ *   retry-transient     — 5xx, ECONNRESET, ETIMEDOUT, network flap.
+ *                         Exponential backoff + jitter. Open circuit after N.
+ *   idempotent-replay   — 409 on POST /v1/messages with duplicate
+ *                         client_msg_id. Treat as success, log at info.
+ *   validation          — Zod schema failed on inbound payload. Likely a
+ *                         server change. Log at error, drop, alert.
+ */
+type ErrorClass = 'terminal-auth' | 'terminal-user' | 'retry-rate' | 'retry-transient' | 'idempotent-replay' | 'validation';
+declare class AgentChatChannelError extends Error {
+    readonly class_: ErrorClass;
+    readonly retryAfterMs: number | undefined;
+    readonly statusCode: number | undefined;
+    constructor(class_: ErrorClass, message: string, options?: {
+        cause?: unknown;
+        retryAfterMs?: number;
+        statusCode?: number;
+    });
+}
+
+/**
+ * Internal shared types for @agentchatme/openclaw.
+ *
+ * Kept intentionally small. Anything externally visible is exported from
+ * `./index.ts` or `./setup-entry.ts`. Types with a public SDK shape (channel
+ * plugin, setup plugin) live next to their respective entry files.
+ */
+type UnixMillis = number;
+
+/**
+ * Connection state machine for the AgentChat WebSocket.
+ *
+ * Pure functions only — no I/O, no timers. The runtime (P2) owns the socket
+ * and drives transitions by emitting events.
+ *
+ * States:
+ *   DISCONNECTED    — initial, and after a clean close
+ *   CONNECTING      — TCP/TLS handshake + WS upgrade in flight
+ *   AUTHENTICATING  — socket open, waiting for `hello.ok` from server
+ *   READY           — authenticated, receiving + sending normally
+ *   DEGRADED        — heartbeat missed or send buffer full; still connected but impaired
+ *   DRAINING        — SIGTERM received; flush in-flight sends, then close
+ *   CLOSED          — terminal after clean shutdown
+ *   AUTH_FAIL       — terminal after 401/403; operator action required (rotate key)
+ *
+ * Invariants:
+ *   - From AUTH_FAIL, no event can move us back to CONNECTING without
+ *     an explicit RECONFIGURED event (operator rotated key).
+ *   - From CLOSED, only SHUTDOWN is a no-op; anything else is a bug.
+ *   - DRAINING has a deadline (ms timestamp) after which we force-close.
+ */
+
+type ConnectionState = {
+    readonly kind: 'DISCONNECTED';
+} | {
+    readonly kind: 'CONNECTING';
+    readonly attempt: number;
+    readonly startedAt: UnixMillis;
+} | {
+    readonly kind: 'AUTHENTICATING';
+    readonly startedAt: UnixMillis;
+} | {
+    readonly kind: 'READY';
+    readonly connectedAt: UnixMillis;
+} | {
+    readonly kind: 'DEGRADED';
+    readonly since: UnixMillis;
+    readonly reason: string;
+} | {
+    readonly kind: 'DRAINING';
+    readonly since: UnixMillis;
+    readonly deadline: UnixMillis;
+} | {
+    readonly kind: 'CLOSED';
+} | {
+    readonly kind: 'AUTH_FAIL';
+    readonly reason: string;
+};
+
+/**
+ * AgentChat WebSocket client — state-machine-driven, production-grade.
+ *
+ * Responsibilities:
+ *   - Own the WS transport and HELLO handshake lifecycle.
+ *   - Drive the connection state machine (`./state-machine.ts`) by emitting
+ *     events in response to socket/auth/heartbeat transitions.
+ *   - Maintain native WS PING/PONG heartbeat at `ping.intervalMs`; declare
+ *     DEGRADED on `ping.timeoutMs` miss, then force-reconnect.
+ *   - Schedule reconnect with exponential backoff + ±`jitterRatio` jitter
+ *     per `reconnect.*` config. Thundering-herd-safe across a fleet.
+ *   - Emit typed events upwards (`inboundFrame`, `stateChanged`, `error`)
+ *     so the normalizer (P3) and outbound adapter (P4) can consume them.
+ *
+ * Intentional design choices:
+ *   - Uses the `ws` package directly (not `globalThis.WebSocket`) because
+ *     OpenClaw runs on Node — `ws` exposes `.ping()` / `.pong()` / event
+ *     hooks that native WebSocket omits. Every major agent-hosting target
+ *     (Fly, Render, Vercel functions, Lambda) is Node.
+ *   - Authenticates via HELLO frame (`{type: "hello", api_key}`), never via
+ *     URL query string. Keeps the key out of access logs and Referers.
+ *   - `RECONNECT_HARD_CAP_ATTEMPTS` guards against runaway reconnect loops
+ *     after catastrophic network events; crosses into `AUTH_FAIL` so the
+ *     operator sees a clear signal instead of silent retry forever.
+ *   - Frame parsing is defensive: malformed JSON, unknown `type`, missing
+ *     payload — all classified as `validation` errors (non-terminal for
+ *     the connection, but dropped with a metric + log).
+ *   - No message-layer ordering here. Per-conversation seq ordering + gap
+ *     recovery belong to the SDK's `RealtimeClient` and the drain layer
+ *     (P3 consumers). This module is strictly the transport.
+ */
+
+/** One parsed inbound server frame. */
+interface InboundFrame {
+    readonly type: string;
+    readonly payload: Record<string, unknown>;
+    readonly receivedAt: UnixMillis;
+    readonly raw: unknown;
+}
+/** One client-action frame the caller wants to push. */
+interface OutboundFrame {
+    readonly type: string;
+    readonly payload: Record<string, unknown>;
+    readonly id?: string;
+}
+interface WsClientEvents {
+    stateChanged: (next: ConnectionState, prev: ConnectionState) => void;
+    inboundFrame: (frame: InboundFrame) => void;
+    error: (error: AgentChatChannelError) => void;
+    /** Fired once per `hello.ok` — useful for triggering a /v1/messages/sync drain upstream. */
+    authenticated: (at: UnixMillis) => void;
+    /** Fired after a clean close + CLOSED state (after stop() or terminal auth failure). */
+    closed: () => void;
+}
+interface WsClientOptions {
+    readonly config: AgentchatChannelConfig;
+    readonly logger: Logger;
+    readonly metrics: MetricsRecorder;
+    /** Clock source — override in tests. Default: `Date.now`. */
+    readonly now?: () => UnixMillis;
+    /** WebSocket constructor override — tests inject a mock. Default: `ws`. */
+    readonly webSocketCtor?: typeof WebSocket;
+    /** Random source for jitter — override in tests. Default: `Math.random`. */
+    readonly random?: () => number;
+    /** timer.setTimeout override for tests. */
+    readonly setTimeout?: (fn: () => void, ms: number) => NodeJS.Timeout;
+    readonly clearTimeout?: (h: NodeJS.Timeout) => void;
+    readonly setInterval?: (fn: () => void, ms: number) => NodeJS.Timeout;
+    readonly clearInterval?: (h: NodeJS.Timeout) => void;
+}
+type Listener<E extends keyof WsClientEvents> = WsClientEvents[E];
+/**
+ * AgentChat channel WebSocket client.
+ *
+ * Lifecycle:
+ *   1. `start()` — DISCONNECTED → CONNECTING. Transport opens, HELLO is sent.
+ *   2. `hello.ok` → READY. Heartbeat timer starts. Upstream consumers begin.
+ *   3. On socket drop → DISCONNECTED → CONNECTING (with backoff).
+ *   4. `stop(deadlineMs)` → DRAINING. Wait for in-flight drains, then CLOSED.
+ *
+ * Thread-safety: this class is single-threaded. All callbacks fire on the
+ * Node event loop; callers should never invoke public methods from timer
+ * callbacks without being aware of reentrancy (e.g., a `stateChanged`
+ * listener that calls `send()` is fine, but `start()` inside `closed()`
+ * will re-enter the lifecycle — usually a bug).
+ */
+declare class AgentchatWsClient {
+    private readonly config;
+    private readonly logger;
+    private readonly metrics;
+    private readonly now;
+    private readonly WebSocketCtor;
+    private readonly random;
+    private readonly _setTimeout;
+    private readonly _clearTimeout;
+    private readonly _setInterval;
+    private readonly _clearInterval;
+    private state;
+    private ws;
+    private attempt;
+    private helloAckTimer;
+    private pingTimer;
+    private pongTimer;
+    private reconnectTimer;
+    private drainTimer;
+    private readonly listeners;
+    constructor(options: WsClientOptions);
+    /** Current connection state. Read-only from the caller's perspective. */
+    getState(): ConnectionState;
+    /**
+     * Kick off connection. No-op if already connecting, authenticating, or
+     * ready. Throws on `AUTH_FAIL` — the caller must call `reconfigured()`
+     * after rotating the API key before retrying.
+     */
+    start(): void;
+    /**
+     * Push a client-action frame. Requires `canSend(state)` — returns false
+     * if the socket is not ready. Callers should queue and retry from the
+     * outbound adapter (P4) rather than drop here.
+     */
+    send(frame: OutboundFrame): boolean;
+    /**
+     * Request a graceful drain. The caller-supplied deadline is a Unix-ms
+     * timestamp; after it passes, the socket is force-closed regardless of
+     * remaining in-flight work. Safe to call from any state.
+     */
+    stop(deadline?: UnixMillis): void;
+    /**
+     * Signal that operator has rotated the API key. Transitions from
+     * AUTH_FAIL back to DISCONNECTED; the next `start()` call will attempt
+     * a fresh HELLO with the current config.
+     */
+    reconfigured(): void;
+    on<E extends keyof WsClientEvents>(event: E, handler: Listener<E>): () => void;
+    private openSocket;
+    private bindSocket;
+    private handleOpen;
+    private handleMessage;
+    private extractReason;
+    private extractPayload;
+    private handleHelloOk;
+    private handleAuthRejected;
+    private handleClose;
+    private closeSocket;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private sendPing;
+    private handlePong;
+    private scheduleReconnect;
+    private computeReconnectDelay;
+    private scheduleDrainDeadline;
+    /**
+     * Called by upper layers when their pending work has fully drained, to
+     * let the WS client transition CLOSED earlier than the deadline.
+     */
+    drainCompleted(): void;
+    private applyEvent;
+    private emit;
+    private emitError;
+}
+
+/**
+ * Inbound normalizer — AgentChat server events → channel-neutral shape.
+ *
+ * Responsibilities:
+ *   - Validate every server frame against a Zod schema. Unknown shapes
+ *     surface as `validation` errors (the transport catches them and drops
+ *     the frame without killing the connection).
+ *   - Translate AgentChat-native payloads into a stable, plugin-internal
+ *     `NormalizedInbound` shape. The OpenClaw channel binding (P7 runtime
+ *     wiring) adapts this further to the gateway's `ChannelInboundMessage`
+ *     contract.
+ *   - Classify conversation kind (direct vs group) from the `dir_*`/`grp_*`
+ *     prefix convention so consumers don't need to grep prefixes themselves.
+ *
+ * Why this module exists (rather than passing raw frames up):
+ *   - The WS client is pure transport; it shouldn't know what
+ *     `message.new` means semantically.
+ *   - OpenClaw's ChannelInboundMessage has a specific shape (thread id,
+ *     content parts, attachments, sender identity). Converting from
+ *     AgentChat's wire format in one place is the only sane way to keep
+ *     the mapping auditable.
+ *   - Per-event Zod schemas make drift between plugin and server obvious
+ *     and loud — a server field rename surfaces as a validation error
+ *     caught in CI long before it goes to prod.
+ */
+
+type ConversationKind = 'direct' | 'group';
+interface NormalizedMessage {
+    readonly kind: 'message';
+    readonly conversationKind: ConversationKind;
+    readonly conversationId: string;
+    /** Sender handle. */
+    readonly sender: string;
+    readonly messageId: string;
+    readonly clientMsgId: string;
+    readonly seq: number;
+    readonly messageType: 'text' | 'structured' | 'file' | 'system';
+    readonly content: {
+        readonly text?: string;
+        readonly data?: Record<string, unknown>;
+        readonly attachmentId?: string;
+    };
+    readonly metadata: Record<string, unknown>;
+    /**
+     * Per-recipient delivery state. Since migration 011, per-recipient state
+     * lives on `message_deliveries`, not the message row — so fresh-send
+     * `message.new` envelopes have no status field. Drain-path (sync /
+     * undelivered) envelopes still include `'stored'`. `null` means the
+     * server didn't attach one; callers that need the authoritative state
+     * should query `GET /v1/messages/sync` or `/delivery-receipts`.
+     */
+    readonly status: 'stored' | 'delivered' | 'read' | null;
+    readonly createdAt: string;
+    readonly deliveredAt: string | null;
+    readonly readAt: string | null;
+    readonly receivedAt: UnixMillis;
+}
+interface NormalizedReadReceipt {
+    readonly kind: 'read-receipt';
+    readonly conversationKind: ConversationKind;
+    readonly conversationId: string;
+    readonly reader: string;
+    readonly throughSeq: number;
+    readonly at: string | null;
+    readonly receivedAt: UnixMillis;
+}
+interface NormalizedTyping {
+    readonly kind: 'typing';
+    readonly action: 'start' | 'stop';
+    readonly conversationKind: ConversationKind;
+    readonly conversationId: string;
+    readonly sender: string;
+    readonly receivedAt: UnixMillis;
+}
+interface NormalizedPresence {
+    readonly kind: 'presence';
+    readonly handle: string;
+    readonly status: 'online' | 'away' | 'offline';
+    readonly lastActiveAt: string | null;
+    readonly customStatus: string | null;
+    readonly receivedAt: UnixMillis;
+}
+interface NormalizedRateLimitWarning {
+    readonly kind: 'rate-limit-warning';
+    readonly endpoint: string | null;
+    readonly limit: number | null;
+    readonly remaining: number | null;
+    readonly resetAt: string | null;
+    readonly message: string | null;
+    readonly receivedAt: UnixMillis;
+}
+interface NormalizedGroupInvite {
+    readonly kind: 'group-invite';
+    readonly inviteId: string;
+    readonly groupId: string;
+    readonly groupName: string;
+    readonly groupDescription: string | null;
+    readonly groupAvatarUrl: string | null;
+    readonly groupMemberCount: number;
+    readonly inviterHandle: string;
+    readonly createdAt: string;
+    readonly receivedAt: UnixMillis;
+}
+interface NormalizedGroupDeleted {
+    readonly kind: 'group-deleted';
+    readonly groupId: string;
+    readonly deletedByHandle: string;
+    readonly deletedAt: string;
+    readonly receivedAt: UnixMillis;
+}
+/**
+ * Unknown server event — arrived over the wire but isn't in our explicit
+ * handler set. We still surface it (the gateway may want to log it or
+ * forward it), but with a `type` field so downstream can discriminate.
+ */
+interface NormalizedUnknown {
+    readonly kind: 'unknown';
+    readonly type: string;
+    readonly payload: Record<string, unknown>;
+    readonly receivedAt: UnixMillis;
+}
+type NormalizedInbound = NormalizedMessage | NormalizedReadReceipt | NormalizedTyping | NormalizedPresence | NormalizedRateLimitWarning | NormalizedGroupInvite | NormalizedGroupDeleted | NormalizedUnknown;
+
+/**
+ * Shape of a message record as returned by the AgentChat REST API.
+ *
+ * Mirrors the `Message` interface defined in the AgentChat TypeScript SDK
+ * (`packages/sdk-typescript/src/types/message.ts`). We keep a local copy so
+ * this plugin has no runtime dependency on the SDK — it's type-only at the
+ * source and the SDK isn't published to npm yet. If the server's message
+ * contract changes, update both files together; a drift is a schema
+ * mismatch the server will catch, but we'd rather fail type-check first.
+ */
+type MessageType = 'text' | 'structured' | 'file' | 'system';
+type MessageStatus = 'stored' | 'delivered' | 'read';
+interface MessageContent {
+    text?: string;
+    data?: Record<string, unknown>;
+    attachment_id?: string;
+}
+interface Message {
+    id: string;
+    conversation_id: string;
+    sender: string;
+    client_msg_id: string;
+    seq: number;
+    type: MessageType;
+    content: MessageContent;
+    metadata: Record<string, unknown>;
+    status: MessageStatus;
+    created_at: string;
+    delivered_at: string | null;
+    read_at: string | null;
+}
+
+/**
+ * Outbound adapter — OpenClaw send → AgentChat `POST /v1/messages`.
+ *
+ * Pipeline (left to right, each step is independently observable):
+ *   1. Caller invokes `sendMessage(input)` with a channel-neutral shape.
+ *   2. We derive a stable `client_msg_id` (idempotency key). If the caller
+ *      supplied one, we respect it; otherwise we mint a UUID.
+ *   3. Circuit-breaker precheck. Open circuit → fast-fail `retry-transient`.
+ *   4. `retryWithPolicy(...)` wraps the actual HTTP call.
+ *   5. On success, metrics/logs + return the `Message` the server minted.
+ *   6. On 409 (idempotent-replay), treat as success with the replay body.
+ *   7. On 429, honor `Retry-After` (seconds or HTTP-date) via the retry
+ *      policy. Surface as `retry-rate`.
+ *   8. On 5xx / network flap, retry with jittered exponential backoff.
+ *   9. On 4xx other than 429/409, classify as `terminal-user` → no retry.
+ *   10. On 401/403 → `terminal-auth`. We signal upstream so the WS client
+ *       moves to AUTH_FAIL and the operator gets paged.
+ *
+ * Backpressure:
+ *   - An in-flight semaphore bounds concurrent sends to `outbound.maxInFlight`.
+ *   - Over-threshold sends are enqueued and drained as capacity frees up.
+ *   - Queue has its own hard cap (`10 * maxInFlight`); over-cap sends reject
+ *     immediately with `retry-transient` so the caller can shed load rather
+ *     than OOM.
+ */
+
+type OutboundMessageInput = OutboundDirectMessage | OutboundGroupMessage;
+interface OutboundMessageBase {
+    /**
+     * Client-generated idempotency key. Optional — we mint one if absent.
+     * Retries of the same logical send MUST reuse the same value or you'll
+     * get duplicates.
+     */
+    readonly clientMsgId?: string;
+    readonly type?: 'text' | 'structured' | 'file';
+    readonly content: {
+        readonly text?: string;
+        readonly data?: Record<string, unknown>;
+        readonly attachmentId?: string;
+    };
+    readonly metadata?: Record<string, unknown>;
+    /** Correlation id carried through logs and metrics. */
+    readonly correlationId?: string;
+}
+interface OutboundDirectMessage extends OutboundMessageBase {
+    readonly kind: 'direct';
+    /** Recipient handle (e.g. "alice"). */
+    readonly to: string;
+}
+interface OutboundGroupMessage extends OutboundMessageBase {
+    readonly kind: 'group';
+    /** `grp_*` conversation id. */
+    readonly conversationId: string;
+}
+interface OutboundBacklogWarning {
+    readonly recipientHandle: string;
+    readonly undeliveredCount: number;
+}
+interface SendResult {
+    readonly message: Message;
+    readonly backlogWarning: OutboundBacklogWarning | null;
+    readonly idempotentReplay: boolean;
+    readonly attempts: number;
+    readonly latencyMs: number;
+    readonly requestId: string | null;
+}
+
+/**
+ * AgentChat channel runtime — single lifecycle object that ties the WS
+ * transport (P2), inbound normalizer (P3), and outbound adapter (P4)
+ * together. This is the surface an OpenClaw channel binding consumes.
+ *
+ * Responsibilities:
+ *   - Instantiate the WS client, hook its `inboundFrame` event through
+ *     `normalizeInbound` and into user-supplied handlers.
+ *   - Expose `sendMessage` that delegates to the OutboundAdapter.
+ *   - Coordinate drain: `stop(deadline)` waits for outbound in-flight to
+ *     clear (up to the deadline) before closing the WS.
+ *   - Surface a single `getHealth()` snapshot combining connection state +
+ *     outbound queue depth + circuit breaker state.
+ *
+ * Not in scope here:
+ *   - Per-conversation seq ordering and gap recovery — the SDK's
+ *     `RealtimeClient` owns that. For the channel plugin, we deliver
+ *     inbound frames as they arrive; upper layers can call
+ *     `GET /v1/messages/sync` for reconciliation if they require strict
+ *     ordering across reconnects.
+ *   - OpenClaw ChannelInboundMessage translation — that lives in the
+ *     bridge module (consumed by the gateway), not here. Keeping this
+ *     module decoupled means it can be smoke-tested without OpenClaw.
+ */
+
+interface ChannelRuntimeHandlers {
+    /** Called for every successfully normalized inbound event. */
+    onInbound?: (event: NormalizedInbound) => void | Promise<void>;
+    /** Called whenever a frame fails validation. Default: log-and-drop. */
+    onValidationError?: (error: AgentChatChannelError, frame: InboundFrame) => void;
+    /** Called on state transitions — surface to gateway for health/UI. */
+    onStateChanged?: (next: ConnectionState, prev: ConnectionState) => void;
+    /** Called once per successful HELLO_OK (initial + every reconnect). */
+    onAuthenticated?: (at: UnixMillis) => void;
+    /** Called on every closed/unreachable situation worth observing. */
+    onError?: (error: AgentChatChannelError) => void;
+    /** Called when the server signals a backlog warning on an outbound send. */
+    onBacklogWarning?: (warning: OutboundBacklogWarning) => void;
+}
+interface ChannelRuntimeOptions {
+    readonly config: AgentchatChannelConfig;
+    readonly handlers?: ChannelRuntimeHandlers;
+    /** Pre-built logger — if absent, we construct one from `config.observability`. */
+    readonly logger?: Logger;
+    /** Pre-built metrics recorder — if absent, uses no-op. */
+    readonly metrics?: MetricsRecorder;
+    readonly fetch?: typeof fetch;
+    /** Injected for tests. */
+    readonly webSocketCtor?: ConstructorParameters<typeof AgentchatWsClient>[0]['webSocketCtor'];
+    readonly now?: () => UnixMillis;
+    readonly random?: () => number;
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+interface HealthSnapshot {
+    readonly state: ConnectionState;
+    readonly authenticated: boolean;
+    readonly outbound: {
+        readonly inFlight: number;
+        readonly queued: number;
+        readonly circuitState: 'closed' | 'open' | 'half-open';
+    };
+}
+/**
+ * Orchestrates the full channel. Construct once per (channelId, accountId)
+ * pair at gateway startup; call `start()` to bring it up, `stop()` to
+ * drain. Dispose is folded into `stop()` — after it resolves, the
+ * instance is terminal.
+ */
+declare class AgentchatChannelRuntime {
+    private readonly config;
+    private readonly handlers;
+    private readonly logger;
+    private readonly metrics;
+    private readonly ws;
+    private readonly outbound;
+    private readonly now;
+    private started;
+    private authenticated;
+    private stopPromise;
+    constructor(opts: ChannelRuntimeOptions);
+    /** Open the transport. Idempotent — subsequent calls are no-ops. */
+    start(): void;
+    /**
+     * Graceful shutdown. Waits for outbound in-flight to drain up to the
+     * deadline, then force-closes the WS. Returns a promise that resolves
+     * once the WS has emitted `closed`.
+     */
+    stop(deadlineMs?: UnixMillis): Promise<void>;
+    private pollUntilIdle;
+    /**
+     * Send an outbound message. Delegates to the OutboundAdapter; callers
+     * should handle `AgentChatChannelError` with class dispatch.
+     */
+    sendMessage(input: OutboundMessageInput): Promise<SendResult>;
+    /** Push a client-action frame over the WS (typing, read-ack, presence). */
+    sendWsAction(type: 'typing.start' | 'typing.stop' | 'message.read_ack' | 'presence.update', payload: Record<string, unknown>): boolean;
+    /**
+     * Operator has rotated the API key — signal the WS client so it can
+     * exit AUTH_FAIL. The caller is responsible for creating a new runtime
+     * with the updated config OR for calling this after config hot-reload.
+     */
+    reconfigured(): void;
+    getHealth(): HealthSnapshot;
+    private bindWsEvents;
+    private dispatchFrame;
+    private recordInboundMetric;
+}
+
+export { AgentChatChannelError, type AgentchatAgentIdentity, AgentchatChannelConfig, AgentchatChannelRuntime, type ChannelRuntimeHandlers, type ChannelRuntimeOptions, type ConnectionState, type ConversationKind, type ErrorClass, type HealthSnapshot, type Message, type MessageContent, type MessageStatus, type MessageType, type NormalizedGroupDeleted, type NormalizedGroupInvite, type NormalizedInbound, type NormalizedMessage, type NormalizedPresence, type NormalizedRateLimitWarning, type NormalizedReadReceipt, type NormalizedTyping, type NormalizedUnknown, type OutboundBacklogWarning, type OutboundDirectMessage, type OutboundGroupMessage, type OutboundMessageInput, type RegisterAgentStartInput, type RegisterAgentVerifyInput, type RegisterOptions, type RegisterStartResult, type RegisterVerifyResult, type SendResult, type ValidateApiKeyOptions, type ValidateApiKeyResult, agentchatSetupWizard, assertApiKeyValid, registerAgentStart, registerAgentVerify, validateApiKey };