@beeos-ai/device-agent 0.7.2 → 0.8.0

package/dist/plugins/message-bus/index.js

@@ -0,0 +1,392 @@
+/**
+ * Plugin — message-bus.
+ *
+ * Subscribes the device-agent to the BeeOS Message Service so it can
+ * receive `chat_message` envelopes from L0 / A2A / MCP / OpenAPI
+ * invocations and reply over `ch:{channelId}` with `agent_reply` /
+ * `agent_reply_delta` (in_reply_to = original message_id).
+ *
+ * Disabled by default — opt in by setting `BEEOS_MESSAGE_BUS_ENABLED=true`
+ * (or `--message-bus`) AND providing both `--agent-gateway-url` and
+ * an Ed25519 identity. Without those the plugin logs a one-line warning
+ * during `start()` and stays disabled — the rest of the agent (Bridge
+ * ACP, HTTP debug) still runs.
+ *
+ * Lifecycle:
+ *   - `init` — read config, decide enabled / disabled.
+ *   - `start` — kick off the connect loop. Returns IMMEDIATELY (does
+ *     not block bootstrap on the network). The first connect attempt
+ *     and any subsequent retries run in the background.
+ *   - `stop` — cancel any pending retry, disconnect SDK, unsubscribe
+ *     outbound listener, drop in-flight register.
+ *
+ * Failure mode: if `tokenProvider()` rejects (e.g. the device instance
+ * has not been provisioned with `agentPublicKey` yet), the plugin
+ * schedules a retry with exponential backoff (30s → 60s → 120s → 240s,
+ * capped at 300s) and keeps trying forever until either `connect`
+ * succeeds or `stop()` cancels the loop. This mirrors beeos-claw's
+ * `localServer.onceAgentMappingReady(...)` deferred-connect pattern —
+ * see `[index.ts:484-498](agents/beeos-claw/src/index.ts)`.
+ */
+import { MessageSDK } from "@beeos-ai/message-sdk";
+import { createDeviceMessagingTokenProvider } from "../../messaging/token-provider.js";
+import { MessageSdkBusyReplyHandler } from "./busy-reply.js";
+import { buildMessageBusInboundHandler } from "./inbound.js";
+import { installMessageBusOutbound } from "./outbound.js";
+import { TurnContextRegister } from "./turn-context.js";
+/**
+ * Backoff schedule for token / connect failures (milliseconds). Each
+ * entry is the delay BEFORE the next retry. The last entry caps the
+ * delay; once we hit the cap we keep retrying forever at that interval.
+ *
+ * Tunable via `MessageBusPluginOptions.retrySchedule` — tests pin a
+ * tighter schedule (e.g. `[5, 5, 5]`) to keep `vi.useFakeTimers()`
+ * runs cheap.
+ */
+export const DEFAULT_RETRY_SCHEDULE_MS = Object.freeze([
+    30_000,
+    60_000,
+    120_000,
+    240_000,
+    300_000,
+]);
+/** Attempt indices (1-based) where a `warn` log is preferred over `debug`. */
+const WARN_ATTEMPT_INDICES = new Set([1, 3, 5, 10]);
+export class MessageBusPlugin {
+    opts;
+    name = "message-bus";
+    ctx;
+    sdk = null;
+    register = null;
+    unsubscribeOutbound = null;
+    resolvedPrincipalId = "";
+    // Connect-loop state.
+    stopped = false;
+    retryHandle = null;
+    // When the loop is sleeping in `sleep(ms)`, this resolver lets
+    // `stop()` (or any other test-level cancel) wake it up early with
+    // `cancelled = true`. Always cleared back to `null` once the resolver
+    // fires.
+    retryResolve = null;
+    connectAttempt = 0;
+    legacyDeprecationLogged = false;
+    // Resolves once the plugin has either successfully connected OR is
+    // permanently disabled. Tests await this to avoid racing the
+    // background loop. Production callers ignore it.
+    connectSettled = Promise.resolve();
+    resolveConnectSettled = () => undefined;
+    constructor(opts = {}) {
+        this.opts = opts;
+    }
+    async init(ctx) {
+        this.ctx = ctx;
+        if (!ctx.config.messageBus?.enabled) {
+            ctx.log.info("message-bus: disabled (set BEEOS_MESSAGE_BUS_ENABLED=true or --message-bus to enable)");
+            return;
+        }
+        if (!this.opts.keypair) {
+            ctx.log.warn("message-bus: enabled but no Ed25519 identity available — stays disabled");
+            return;
+        }
+        if (!ctx.config.agentGatewayUrl) {
+            ctx.log.warn("message-bus: enabled but no agentGatewayUrl configured — stays disabled");
+            return;
+        }
+    }
+    async start() {
+        const ctx = this.ctx;
+        if (!ctx)
+            return;
+        if (!ctx.config.messageBus?.enabled)
+            return;
+        if (!this.opts.keypair)
+            return;
+        if (!ctx.config.agentGatewayUrl)
+            return;
+        this.connectSettled = new Promise((resolve) => {
+            this.resolveConnectSettled = resolve;
+        });
+        // Kick off the loop. Do NOT await — the bootstrap should not block
+        // on a remote handshake. The loop reschedules itself via setTimeout
+        // until either `tryConnectOnce` returns true or `stop()` is called.
+        void this.runConnectLoop();
+    }
+    async stop() {
+        this.stopped = true;
+        this.cancelPendingRetry();
+        // Resolve any outstanding waiter so test code that awaits
+        // `whenSettled()` does not hang past stop().
+        this.resolveConnectSettled();
+        if (this.unsubscribeOutbound) {
+            try {
+                this.unsubscribeOutbound();
+            }
+            catch {
+                /* ignore */
+            }
+            this.unsubscribeOutbound = null;
+        }
+        if (this.sdk) {
+            try {
+                await this.sdk.disconnect();
+            }
+            catch (err) {
+                this.ctx?.log.warn({ err: err instanceof Error ? err.message : String(err) }, "message-bus: disconnect failed");
+            }
+            this.sdk = null;
+        }
+        if (this.register) {
+            this.register.reset();
+            this.register = null;
+        }
+    }
+    // Test seam — exposes the resolved principal so integration tests can
+    // assert what the plugin actually subscribed to without poking at
+    // private state.
+    get principalId() {
+        return this.resolvedPrincipalId;
+    }
+    /**
+     * Test helper — resolves once `start()`'s connect loop has either
+     * successfully connected or `stop()` was called. Production code
+     * never needs this.
+     */
+    whenSettled() {
+        return this.connectSettled;
+    }
+    // ── Internals ──────────────────────────────────────────────────────────
+    async runConnectLoop() {
+        const ctx = this.ctx;
+        const log = ctx.log;
+        while (!this.stopped) {
+            this.connectAttempt += 1;
+            const ok = await this.tryConnectOnce(this.connectAttempt);
+            if (ok) {
+                this.resolveConnectSettled();
+                return;
+            }
+            if (this.stopped) {
+                this.resolveConnectSettled();
+                return;
+            }
+            const delayMs = this.nextDelayMs(this.connectAttempt);
+            this.logRetryScheduled(this.connectAttempt, delayMs, log);
+            const cancelled = await this.sleep(delayMs);
+            if (cancelled) {
+                this.resolveConnectSettled();
+                return;
+            }
+        }
+        this.resolveConnectSettled();
+    }
+    /**
+     * Single connect attempt. Returns `true` on success (sdk connected,
+     * handlers + listener installed) and `false` on any failure (caller
+     * should schedule a retry).
+     *
+     * Each attempt builds a FRESH `MessageSDK` instance — re-using one
+     * across reconnects would carry stale handlers and confuse the
+     * centrifuge-js internal state. The SDK has its own internal
+     * reconnect once `.connect()` succeeds; this loop is for the OPENING
+     * handshake only.
+     */
+    async tryConnectOnce(attempt) {
+        const ctx = this.ctx;
+        const log = ctx.log;
+        const keypair = this.opts.keypair;
+        const agentGatewayUrl = ctx.config.agentGatewayUrl;
+        const tokenProvider = this.opts.tokenProviderFactory?.({ agentGatewayUrl, keypair }) ??
+            createDeviceMessagingTokenProvider({ agentGatewayUrl, keypair });
+        const sdk = this.opts.sdkFactory?.(log) ??
+            new MessageSDK({
+                // No serviceUrl — agents talk to MS only via Agent Gateway
+                // proxy + Centrifugo (P6 boundary).
+                centrifugoUrl: ctx.config.messageBus.centrifugoUrl || undefined,
+            }, wrapLoggerForSdk(log));
+        let tok;
+        try {
+            tok = await tokenProvider(ctx.config.messageBus.principalIdOverride ?? "");
+        }
+        catch (err) {
+            this.logAttemptFailure(attempt, "messaging-token fetch failed", err, log);
+            return false;
+        }
+        const principalId = tok.principal_id;
+        if (!principalId) {
+            this.logAttemptFailure(attempt, "gateway returned empty principal_id", null, log);
+            return false;
+        }
+        const register = new TurnContextRegister();
+        const busyReply = new MessageSdkBusyReplyHandler({ sdk });
+        const chatHandler = buildMessageBusInboundHandler({
+            host: ctx.host,
+            register,
+            busyReply,
+            logger: log,
+            localAgentId: this.opts.localAgentId,
+            source: "chat_message",
+        });
+        const legacyHandler = buildMessageBusInboundHandler({
+            host: ctx.host,
+            register,
+            busyReply,
+            logger: log,
+            localAgentId: this.opts.localAgentId,
+            source: "agent_request",
+        });
+        sdk.onMessage("chat_message", async (env) => chatHandler(env));
+        // Gap F — fire a one-shot deprecation warn the FIRST time a legacy
+        // `agent_request` envelope arrives. Mirrors beeos-claw
+        // [`index.ts:551-557`](agents/beeos-claw/src/index.ts).
+        sdk.onMessage("agent_request", async (env) => {
+            if (!this.legacyDeprecationLogged) {
+                this.legacyDeprecationLogged = true;
+                log.warn({}, "message-bus: received legacy 'agent_request' envelope — this path is deprecated; please migrate upstream callers to 'chat_message' (L0 AgentInvocationService)");
+            }
+            await legacyHandler(env);
+        });
+        const unsubscribe = installMessageBusOutbound({
+            host: ctx.host,
+            sdk,
+            register,
+            logger: log,
+        });
+        sdk.onceConnected(() => {
+            log.info({
+                principalId,
+                centrifugoUrl: tok.centrifugo_url,
+                channels: tok.channels,
+                attempt,
+            }, "message-bus: connected");
+        });
+        try {
+            await sdk.connect(principalId, {
+                centrifugoUrl: tok.centrifugo_url,
+                tokenProvider,
+            });
+        }
+        catch (err) {
+            // Roll back the listener so we don't double-subscribe on the
+            // next retry, and disconnect the half-opened SDK.
+            try {
+                unsubscribe();
+            }
+            catch {
+                /* ignore */
+            }
+            try {
+                await sdk.disconnect();
+            }
+            catch {
+                /* ignore */
+            }
+            this.logAttemptFailure(attempt, "Centrifugo connect failed", err, log);
+            return false;
+        }
+        this.sdk = sdk;
+        this.register = register;
+        this.unsubscribeOutbound = unsubscribe;
+        this.resolvedPrincipalId = principalId;
+        return true;
+    }
+    nextDelayMs(attempt) {
+        const schedule = this.opts.retrySchedule ?? DEFAULT_RETRY_SCHEDULE_MS;
+        const idx = Math.min(attempt - 1, schedule.length - 1);
+        return schedule[idx];
+    }
+    /**
+     * Log an attempt failure with attenuated severity — first attempt
+     * + a few well-spaced retries get a `warn`, the rest are `debug` to
+     * avoid log spam when an instance has never been provisioned.
+     */
+    logAttemptFailure(attempt, summary, err, log) {
+        const errStr = err == null
+            ? null
+            : err instanceof Error
+                ? err.message
+                : String(err);
+        const fields = { attempt };
+        if (errStr)
+            fields.err = errStr;
+        if (WARN_ATTEMPT_INDICES.has(attempt)) {
+            log.warn(fields, `message-bus: ${summary} — will retry`);
+        }
+        else {
+            log.debug(fields, `message-bus: ${summary} — will retry`);
+        }
+    }
+    logRetryScheduled(attempt, delayMs, log) {
+        if (WARN_ATTEMPT_INDICES.has(attempt)) {
+            log.warn({ attempt, retryInMs: delayMs }, "message-bus: scheduled connect retry");
+        }
+    }
+    /**
+     * Sleep `ms` milliseconds. Returns `true` when stop() cancels the
+     * timer mid-flight (so the caller breaks out of its loop), or
+     * `false` once the timer fires normally.
+     */
+    sleep(ms) {
+        const sched = this.scheduler();
+        return new Promise((resolve) => {
+            this.retryResolve = resolve;
+            this.retryHandle = sched.setTimeout(() => {
+                this.retryHandle = null;
+                this.retryResolve = null;
+                resolve(false);
+            }, ms);
+        });
+    }
+    cancelPendingRetry() {
+        if (this.retryHandle == null)
+            return;
+        const sched = this.scheduler();
+        try {
+            sched.clearTimeout(this.retryHandle);
+        }
+        catch {
+            /* ignore */
+        }
+        this.retryHandle = null;
+        const resolve = this.retryResolve;
+        this.retryResolve = null;
+        if (resolve)
+            resolve(true);
+    }
+    scheduler() {
+        return (this.opts.scheduler ?? {
+            setTimeout: (cb, t) => setTimeout(cb, t),
+            clearTimeout: (h) => clearTimeout(h),
+        });
+    }
+}
+/**
+ * Adapt the device-agent pino logger to the MessageSDKLogger shape the
+ * shared SDK expects. The SDK calls `info(msg)` / `warn(msg, fields?)`
+ * with positional args; pino's signature is `(obj, msg)` so we coerce
+ * to a stringly form that prints sanely either way.
+ */
+function wrapLoggerForSdk(log) {
+    return {
+        info: (...args) => log.info(formatSdkArgs(args)),
+        warn: (...args) => log.warn(formatSdkArgs(args)),
+        error: (...args) => log.error(formatSdkArgs(args)),
+        debug: (...args) => log.debug(formatSdkArgs(args)),
+    };
+}
+function formatSdkArgs(args) {
+    return args
+        .map((a) => {
+        if (typeof a === "string")
+            return a;
+        if (a instanceof Error)
+            return a.message;
+        try {
+            return JSON.stringify(a);
+        }
+        catch {
+            return String(a);
+        }
+    })
+        .join(" ");
+}
+//# sourceMappingURL=index.js.map

package/dist/plugins/message-bus/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/plugins/message-bus/index.ts"],"names":[],"mappings":"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"}

package/dist/plugins/message-bus/outbound.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Outbound — bridge AgentHost events back to the MS IM channel.
+ *
+ * Subscribes to `AgentHost.on(listener)` ONCE at plugin start, then
+ * publishes Centrifugo `ch:{channelId}` envelopes whose shape matches
+ * the contract the rest of the BeeOS platform expects:
+ *
+ *   - `agent_reply_delta` — streaming chunks. Carries an inner
+ *     `update.sessionUpdate` field that callers (A2A / OpenAPI) demux
+ *     on. Only `agent_message_chunk` is treated as user-visible
+ *     reply text by `backend/pkg/convmsg/extract.go::extractNestedDelta`;
+ *     `agent_thought_chunk` is intentionally filtered out so reasoning
+ *     never leaks into status text.
+ *
+ *   - `agent_reply` — terminal reply on `task:end`. `payload.text` for
+ *     success, `payload.error` for failure. Matches
+ *     `chatinvoke/invoker.go::extractReplyFinal`.
+ *
+ * Each envelope carries `in_reply_to` set to the original request's
+ * `message_id`, which is what the L0 `/channels/{id}/wait` endpoint
+ * matches on.
+ *
+ * The listener filters by taskId via the in-flight register — events
+ * for tasks NOT submitted through the message-bus inbound (e.g. ACP
+ * `session/prompt` traffic) are ignored, so the two surfaces never
+ * collide.
+ */
+import type { MessageSDK } from "@beeos-ai/message-sdk";
+import type { AgentHost } from "../../ports/agent-host.js";
+import type { Logger } from "../../logger/index.js";
+import type { TurnContextRegister } from "./turn-context.js";
+export interface MessageBusOutboundOptions {
+    host: AgentHost;
+    sdk: MessageSDK;
+    register: TurnContextRegister;
+    logger: Logger;
+}
+/**
+ * Install the outbound listener on the host. Returns an `unsubscribe`
+ * function — call it from the plugin's `stop()` so we don't keep
+ * publishing after the SDK has been disconnected.
+ */
+export declare function installMessageBusOutbound(opts: MessageBusOutboundOptions): () => void;

package/dist/plugins/message-bus/outbound.js

@@ -0,0 +1,149 @@
+/**
+ * Outbound — bridge AgentHost events back to the MS IM channel.
+ *
+ * Subscribes to `AgentHost.on(listener)` ONCE at plugin start, then
+ * publishes Centrifugo `ch:{channelId}` envelopes whose shape matches
+ * the contract the rest of the BeeOS platform expects:
+ *
+ *   - `agent_reply_delta` — streaming chunks. Carries an inner
+ *     `update.sessionUpdate` field that callers (A2A / OpenAPI) demux
+ *     on. Only `agent_message_chunk` is treated as user-visible
+ *     reply text by `backend/pkg/convmsg/extract.go::extractNestedDelta`;
+ *     `agent_thought_chunk` is intentionally filtered out so reasoning
+ *     never leaks into status text.
+ *
+ *   - `agent_reply` — terminal reply on `task:end`. `payload.text` for
+ *     success, `payload.error` for failure. Matches
+ *     `chatinvoke/invoker.go::extractReplyFinal`.
+ *
+ * Each envelope carries `in_reply_to` set to the original request's
+ * `message_id`, which is what the L0 `/channels/{id}/wait` endpoint
+ * matches on.
+ *
+ * The listener filters by taskId via the in-flight register — events
+ * for tasks NOT submitted through the message-bus inbound (e.g. ACP
+ * `session/prompt` traffic) are ignored, so the two surfaces never
+ * collide.
+ */
+/**
+ * Install the outbound listener on the host. Returns an `unsubscribe`
+ * function — call it from the plugin's `stop()` so we don't keep
+ * publishing after the SDK has been disconnected.
+ */
+export function installMessageBusOutbound(opts) {
+    const listener = (event) => {
+        void handleEvent(event, opts);
+    };
+    return opts.host.on(listener);
+}
+async function handleEvent(event, opts) {
+    const ctx = opts.register.getByTaskId(event.taskId);
+    if (!ctx)
+        return; // Not an MS-originated turn — ignored.
+    try {
+        switch (event.type) {
+            case "task:start":
+                // Intentionally not emitted. beeos-claw does not publish an
+                // `agent_status` delta on prompt start either — see
+                // [acp-server.ts onStreamDelta](agents/beeos-claw/src/acp-server.ts);
+                // the first wire publish is the first real LLM delta. The
+                // server-side `extractNestedDelta` only honours
+                // `agent_message_chunk` anyway, so synthesising an extra
+                // `agent_status` envelope would be pure noise. KISS — skip.
+                return;
+            case "task:text":
+                await sendDelta(opts, ctx, "agent_message_chunk", event.text);
+                return;
+            case "task:reasoning":
+                await sendDelta(opts, ctx, "agent_thought_chunk", event.text);
+                return;
+            case "task:notice":
+                // Notices (warnings / non-fatal errors) surface as user-visible
+                // chunks so the operator sees something. Same `agent_message_chunk`
+                // sessionUpdate so they get included in the final concatenated
+                // text by extractNestedDelta. Payload is the canonical
+                // `{ session_key, update }` shape — no extra fields, matching
+                // beeos-claw's onStreamDelta output exactly.
+                await sendDelta(opts, ctx, "agent_message_chunk", event.text);
+                return;
+            case "task:tool":
+            case "task:step":
+                // Tool calls and step transitions are debug-grade today —
+                // streaming them would dilute the agent_message_chunk text.
+                // Skip silently; callers that want richer telemetry should
+                // subscribe to the personal channel directly.
+                return;
+            case "task:end": {
+                const ok = !event.error;
+                const finalText = (event.result?.finalMessage ??
+                    event.result?.text ??
+                    "") || "";
+                // Wire shape mirrors beeos-claw `[acp-server.ts:498/:514]`
+                // (agents/beeos-claw/src/acp-server.ts):
+                //   success → { session_key, text }
+                //   failure → { session_key, error }   (text optional)
+                const payload = ok
+                    ? { session_key: ctx.sessionKey, text: finalText }
+                    : {
+                        session_key: ctx.sessionKey,
+                        error: event.error ?? "unknown_error",
+                        text: finalText,
+                    };
+                await opts.sdk.sendToChannel(ctx.channelId, "agent_reply", payload, { inReplyTo: ctx.inboundMessageId });
+                opts.logger.info({
+                    taskId: event.taskId,
+                    channelId: ctx.channelId,
+                    ok,
+                    durationMs: event.completedAt - ctx.startedAt,
+                }, "message-bus: turn finished");
+                opts.register.clear(event.taskId);
+                return;
+            }
+        }
+    }
+    catch (err) {
+        // Never throw out of the AgentHost listener — that would crash the
+        // entire event fan-out. Log and continue; the next event for the
+        // same task will retry the publish path.
+        opts.logger.error({
+            err: err instanceof Error ? err.message : String(err),
+            eventType: event.type,
+            taskId: event.taskId,
+            channelId: ctx.channelId,
+        }, "message-bus: outbound publish failed");
+    }
+}
+/**
+ * Publish a single `agent_reply_delta` envelope.
+ *
+ * Wire shape locked-in to match beeos-claw
+ * [`acp-server.ts onStreamDelta` (acp-server.ts:438-450)](agents/beeos-claw/src/acp-server.ts):
+ *
+ * ```json
+ * {
+ *   "session_key": "agent:{id}:invoke:ctx-...",
+ *   "update": {
+ *     "sessionUpdate": "agent_message_chunk" | "agent_thought_chunk",
+ *     "content": { "type": "text", "text": "..." }
+ *   }
+ * }
+ * ```
+ *
+ * Server-side `backend/pkg/convmsg/extract.go::extractNestedDelta`
+ * filters on `update.sessionUpdate === "agent_message_chunk"` for
+ * user-visible reply text — `agent_thought_chunk` is dropped so
+ * reasoning never leaks into status text. The `session_key` field is
+ * forward-compatible: no current backend consumer reads it (verified
+ * via `rg session_key backend/`), but emitting it preserves byte-for-
+ * byte parity with beeos-claw for downstream observers.
+ */
+async function sendDelta(opts, ctx, sessionUpdate, text) {
+    await opts.sdk.sendToChannel(ctx.channelId, "agent_reply_delta", {
+        session_key: ctx.sessionKey,
+        update: {
+            sessionUpdate,
+            content: { type: "text", text },
+        },
+    }, { inReplyTo: ctx.inboundMessageId });
+}
+//# sourceMappingURL=outbound.js.map

package/dist/plugins/message-bus/outbound.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbound.js","sourceRoot":"","sources":["../../../src/plugins/message-bus/outbound.ts"],"names":[],"mappings":"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"}

package/dist/plugins/message-bus/turn-context.d.ts

@@ -0,0 +1,57 @@
+/**
+ * In-flight Message-Service turn register.
+ *
+ * Holds the channel + reply correlator for the SINGLE turn that's
+ * currently executing on the host. Single-entry by design — device-agent
+ * runs one ACP session and the SessionManager serialises turns inside
+ * that session, so a second concurrent `chat_message` would be a logic
+ * error and is rejected via `busy-reply.ts`.
+ *
+ * The taskId is allocated by `host.submitTask(...)` and used to filter
+ * the `host.on(listener)` event stream so we never publish another
+ * turn's deltas to the wrong MS channel.
+ */
+export interface MessagingTurnContext {
+    /** Allocated by `host.submitTask` — used to filter AgentEvent stream. */
+    taskId: string;
+    /** IM channel the reply is published on (`ch:{channelId}`). */
+    channelId: string;
+    /** Request `message_id` echoed back as `in_reply_to` on every reply. */
+    inboundMessageId: string;
+    /**
+     * Stable session anchor (e.g. `agent:{id}:invoke:ctx-{contextId}` or
+     * `agent:{id}:invoke:ch-{channelId}`) derived by `extractChatPrompt`.
+     * Embedded as `payload.session_key` on every outbound publish so the
+     * wire format matches beeos-claw `[acp-server.ts:443]`
+     * (agents/beeos-claw/src/acp-server.ts) — downstream consumers
+     * (dashboards, A2A SSE projection) use it to group chunks belonging
+     * to the same logical conversation turn.
+     */
+    sessionKey: string;
+    /** Optional context-id, surfaced for logging only. */
+    contextId?: string;
+    /** Wall-clock timestamp the turn was claimed (ms). For diagnostics. */
+    startedAt: number;
+}
+/**
+ * Single-entry in-flight register.
+ *
+ * Methods are intentionally synchronous — they run on the WS publication
+ * callback (low latency) and on AgentHost listener invocations.
+ */
+export declare class TurnContextRegister {
+    private current;
+    isBusy(): boolean;
+    /**
+     * Claim the register for a new turn. Returns the entry on success or
+     * `null` when a previous turn is still in flight (caller MUST then
+     * use the busy-reply path).
+     */
+    claim(entry: Omit<MessagingTurnContext, "startedAt">): MessagingTurnContext | null;
+    current_(): MessagingTurnContext | null;
+    getByTaskId(taskId: string): MessagingTurnContext | null;
+    /** Idempotent — clearing twice is a no-op. */
+    clear(taskId: string): void;
+    /** Force-clear (used during plugin stop / disconnect). */
+    reset(): void;
+}