@botcord/daemon 0.2.75 → 0.2.76

package/dist/cloud-auth.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Cloud-daemon auth manager.
+ *
+ * Implements the subset of `UserAuthManager` surface that `ControlChannel`
+ * uses (`current`, `ensureAccessToken`) so the same channel implementation
+ * can be reused for `/cloud/daemon/ws`. Unlike the user variant there is
+ * no refresh token: the Hub-managed E2B provider rotates the access token
+ * by relaunching the daemon. When the embedded JWT expires, the WS server
+ * closes with 4401 and `ControlChannel.onClose` writes the auth-expired
+ * flag — at which point the provider would resume the sandbox with a
+ * fresh token.
+ *
+ * Plan §6.4: `auth-expired.flag` is still written so any external monitor
+ * watching the sandbox filesystem can detect the situation; the cloud
+ * provider doesn't read this file directly today (it relies on
+ * `daemon_instances.last_seen_at` going stale instead).
+ *
+ * Field names match `UserAuthRecord` for drop-in compatibility with
+ * `ControlChannel.start()` which reads `auth.current.{userId,hubUrl,label}`.
+ */
+import type { UserAuthRecord, UserAuthManager } from "./user-auth.js";
+import type { CloudModeConfig } from "./cloud-mode.js";
+/**
+ * Minimal `UserAuthManager`-shaped wrapper backed by the cloud-mode env
+ * vars. Static-typed against `UserAuthManager` so `ControlChannel` accepts
+ * it without an interface change.
+ */
+export declare class CloudAuthManager {
+    private record;
+    constructor(cfg: CloudModeConfig);
+    get current(): UserAuthRecord;
+    /**
+     * Cloud-mode access token never refreshes locally — it's baked into the
+     * JWT the provider injected at sandbox start. The provider rotates by
+     * relaunching the daemon, not by talking to a refresh endpoint.
+     */
+    ensureAccessToken(): Promise<string>;
+}
+/**
+ * Hand the cloud auth wrapper out as a `UserAuthManager` so `ControlChannel`
+ * (which only consults `current` and `ensureAccessToken`) accepts it.
+ *
+ * Cast-only — no runtime translation needed because `CloudAuthManager`
+ * implements the same shape. Kept as a single helper so the cast is
+ * documented in one place.
+ */
+export declare function asUserAuthManager(mgr: CloudAuthManager): UserAuthManager;

package/dist/cloud-auth.js

@@ -0,0 +1,51 @@
+/**
+ * Minimal `UserAuthManager`-shaped wrapper backed by the cloud-mode env
+ * vars. Static-typed against `UserAuthManager` so `ControlChannel` accepts
+ * it without an interface change.
+ */
+export class CloudAuthManager {
+    record;
+    constructor(cfg) {
+        this.record = {
+            version: 1,
+            // The cloud daemon row is owned by a single user — but we don't get
+            // the user id in the env (the JWT carries it server-side). Surface
+            // the cloud daemon instance id as a stable "who am I" string for
+            // logs; the Hub already knows the binding.
+            userId: cfg.cloudDaemonInstanceId,
+            daemonInstanceId: cfg.daemonInstanceId,
+            hubUrl: cfg.hubUrl,
+            accessToken: cfg.accessToken,
+            // No refresh token in cloud mode. Stored as an empty string to keep
+            // the type intact; `ensureAccessToken` never reaches the refresh path
+            // because `expiresAt` is set to a date far in the future (the Hub
+            // closes the WS with 4401 when the embedded JWT expires).
+            refreshToken: "",
+            expiresAt: Number.MAX_SAFE_INTEGER,
+            loggedInAt: new Date().toISOString(),
+            label: `cloud:${cfg.cloudDaemonInstanceId}`,
+        };
+    }
+    get current() {
+        return this.record;
+    }
+    /**
+     * Cloud-mode access token never refreshes locally — it's baked into the
+     * JWT the provider injected at sandbox start. The provider rotates by
+     * relaunching the daemon, not by talking to a refresh endpoint.
+     */
+    async ensureAccessToken() {
+        return this.record.accessToken;
+    }
+}
+/**
+ * Hand the cloud auth wrapper out as a `UserAuthManager` so `ControlChannel`
+ * (which only consults `current` and `ensureAccessToken`) accepts it.
+ *
+ * Cast-only — no runtime translation needed because `CloudAuthManager`
+ * implements the same shape. Kept as a single helper so the cast is
+ * documented in one place.
+ */
+export function asUserAuthManager(mgr) {
+    return mgr;
+}

package/dist/cloud-daemon.d.ts

@@ -0,0 +1,43 @@
+import { type GatewayLogger, type GatewayRuntimeSnapshot } from "./gateway/index.js";
+import type { DaemonConfig } from "./config.js";
+import { ControlChannel } from "./control-channel.js";
+import { createProvisioner } from "./provision.js";
+import type { CloudModeConfig } from "./cloud-mode.js";
+/** Options accepted by {@link startCloudDaemon}. */
+export interface CloudDaemonRuntimeOptions {
+    /** Resolved env-driven cloud config (see {@link loadCloudModeConfig}). */
+    cloudConfig: CloudModeConfig;
+    /**
+     * Empty/initial DaemonConfig. Cloud daemons start with zero agents and
+     * grow exclusively via `provision_agent` frames over the cloud control
+     * plane — `agents[]` / `routes[]` arrays are seeded empty.
+     */
+    config: DaemonConfig;
+    configPath: string;
+    sessionStorePath?: string;
+    snapshotPath?: string;
+    snapshotIntervalMs?: number;
+    log?: GatewayLogger;
+    /** Test hook — override the control-channel cstr. */
+    controlChannelFactory?: typeof ControlChannel;
+    /** Skip control channel entirely; for tests that exercise the gateway only. */
+    disableControlChannel?: boolean;
+    /**
+     * Test hook — inject a pre-built provisioner. Default uses
+     * `createProvisioner({ gateway, policyResolver, onAgentInstalled })`.
+     */
+    provisionerFactory?: typeof createProvisioner;
+}
+/** Handle returned by {@link startCloudDaemon}. */
+export interface CloudDaemonHandle {
+    stop: (reason?: string) => Promise<void>;
+    snapshot: () => GatewayRuntimeSnapshot;
+}
+/**
+ * Boot the cloud daemon. The gateway starts with zero channels; every
+ * provisioned agent arrives via `provision_agent`, which calls into the
+ * shared `provision.ts` flow exactly like a local daemon does. The only
+ * difference is the control-channel auth, endpoint path, and the absence
+ * of a local user-auth file.
+ */
+export declare function startCloudDaemon(opts: CloudDaemonRuntimeOptions): Promise<CloudDaemonHandle>;

package/dist/cloud-daemon.js

@@ -0,0 +1,252 @@
+/**
+ * Cloud-daemon mode runtime entrypoint.
+ *
+ * Equivalent to {@link startDaemon} for cloud-mode operation: skips local
+ * user-auth, skips local on-disk credentials, dials
+ * `${HUB_URL}/cloud/daemon/ws` with the env-injected JWT, and reuses the
+ * existing provisioner so `provision_agent` / `revoke_agent` frames work
+ * the same way they do for local daemons.
+ *
+ * See ``docs/cloud-agent-technical-design.md`` §4 + §6.
+ */
+import { shouldWake } from "@botcord/protocol-core";
+import { Gateway, resolveTranscriptEnabled, } from "./gateway/index.js";
+import { ActivityTracker } from "./activity-tracker.js";
+import { SESSIONS_PATH, SNAPSHOT_PATH } from "./config.js";
+import { ControlChannel } from "./control-channel.js";
+import { toGatewayConfig } from "./daemon-config-map.js";
+import { log as daemonLog } from "./log.js";
+import { createProvisioner } from "./provision.js";
+import { createDaemonChannel, pushRuntimeSnapshot } from "./daemon.js";
+import { SnapshotWriter } from "./snapshot-writer.js";
+import { createDaemonSystemContextBuilder } from "./system-context.js";
+import { readWorkingMemorySnapshot } from "./working-memory.js";
+import { createRoomStaticContextBuilder } from "./room-context.js";
+import { createRoomContextFetcher } from "./room-context-fetcher.js";
+import { composeBotCordUserTurn } from "./turn-text.js";
+import { PolicyResolver } from "./gateway/policy-resolver.js";
+import { scanMention } from "./mention-scan.js";
+import { createActivityRecorder } from "./daemon.js";
+import { CloudAuthManager, asUserAuthManager } from "./cloud-auth.js";
+import { buildCloudRunSettleHook } from "./cloud-settle.js";
+// Cloud daemons follow the same cadence as local — keeps dashboard
+// "runtimes last detected" behavior identical across both kinds.
+const DEFAULT_TURN_TIMEOUT_MS = 30 * 60 * 1000;
+const DEFAULT_SNAPSHOT_INTERVAL_MS = 5_000;
+function resolveSnapshotIntervalMs() {
+    const raw = process.env.BOTCORD_DAEMON_SNAPSHOT_INTERVAL_MS;
+    if (!raw)
+        return DEFAULT_SNAPSHOT_INTERVAL_MS;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0)
+        return DEFAULT_SNAPSHOT_INTERVAL_MS;
+    return n;
+}
+function buildLogger(opt) {
+    if (opt)
+        return opt;
+    return {
+        info: (msg, meta) => daemonLog.info(msg, meta),
+        warn: (msg, meta) => daemonLog.warn(msg, meta),
+        error: (msg, meta) => daemonLog.error(msg, meta),
+        debug: (msg, meta) => daemonLog.debug(msg, meta),
+    };
+}
+/**
+ * Boot the cloud daemon. The gateway starts with zero channels; every
+ * provisioned agent arrives via `provision_agent`, which calls into the
+ * shared `provision.ts` flow exactly like a local daemon does. The only
+ * difference is the control-channel auth, endpoint path, and the absence
+ * of a local user-auth file.
+ */
+export async function startCloudDaemon(opts) {
+    const logger = buildLogger(opts.log);
+    const cloudCfg = opts.cloudConfig;
+    logger.info("cloud daemon starting", {
+        cloudDaemonInstanceId: cloudCfg.cloudDaemonInstanceId,
+        daemonInstanceId: cloudCfg.daemonInstanceId,
+        hubUrl: cloudCfg.hubUrl,
+    });
+    // ActivityTracker / policy resolver / per-agent caches — same as local
+    // daemon, but the caches start empty because no agents are bound at
+    // boot. `onAgentInstalled` populates them whenever provision_agent
+    // lands.
+    const activityTracker = new ActivityTracker();
+    const credentialPathByAgentId = new Map();
+    const hubUrlByAgentId = new Map();
+    const displayNameByAgent = new Map();
+    // Seed each per-agent hub URL with the cloud-mode value so that even
+    // before the first credential file is written the room-context fetcher
+    // has somewhere sensible to point.
+    const fallbackHubUrl = cloudCfg.hubUrl;
+    const resolveHubUrl = (accountId) => hubUrlByAgentId.get(accountId) ?? fallbackHubUrl;
+    // Same gateway-config translation as local — empty `agents` produces an
+    // empty `channels[]` initially, which is fine.
+    const gwConfig = toGatewayConfig(opts.config, { agentIds: [], agentRuntimes: {} });
+    const roomContextFetcher = createRoomContextFetcher({
+        credentialPathByAgentId,
+        hubBaseUrl: cloudCfg.hubUrl,
+        log: logger,
+    });
+    const roomContextBuilder = createRoomStaticContextBuilder({
+        fetchRoomInfo: roomContextFetcher,
+        log: logger,
+    });
+    const scBuilders = new Map();
+    const buildSystemContext = (message) => {
+        const b = scBuilders.get(message.accountId);
+        return b ? b(message) : undefined;
+    };
+    const buildMemoryContext = (message) => readWorkingMemorySnapshot(message.accountId);
+    const recordActivity = createActivityRecorder({ activityTracker });
+    const onInbound = (msg) => {
+        recordActivity(msg);
+    };
+    // Settle ``cloud_run`` envelopes against the Hub usage ledger once the
+    // runtime turn finishes. Pure adapter from the dispatcher's hook shape
+    // to the settle helper's input shape — the actual HTTP call lives in
+    // :func:`buildCloudRunSettleHook` so it's unit-testable.
+    const settleHook = buildCloudRunSettleHook({
+        hubUrl: cloudCfg.hubUrl,
+        accessToken: cloudCfg.accessToken,
+        log: logger,
+    });
+    const onTurnComplete = async (event) => {
+        const envelope = event.message.raw
+            ?.envelope;
+        const runId = envelope?.payload?.cloud_run?.run_id;
+        await settleHook({
+            envelopeType: envelope?.type,
+            runId: typeof runId === "string" ? runId : undefined,
+            wallTimeMs: event.wallTimeMs,
+            tokens: {
+                ...(event.result?.inputCacheHitTokens !== undefined
+                    ? { inputCacheHitTokens: event.result.inputCacheHitTokens }
+                    : {}),
+                ...(event.result?.inputCacheMissTokens !== undefined
+                    ? { inputCacheMissTokens: event.result.inputCacheMissTokens }
+                    : {}),
+                ...(event.result?.outputTokens !== undefined
+                    ? { outputTokens: event.result.outputTokens }
+                    : {}),
+            },
+            messageId: event.message.id,
+        });
+    };
+    const policyResolver = new PolicyResolver({
+        fetchGlobal: async (_agentId) => undefined,
+    });
+    const attentionGate = async (msg) => {
+        const policy = await policyResolver.resolve(msg.accountId, msg.conversation.id);
+        if (policy.mode === "allowed_senders") {
+            return (policy.allowedSenderIds ?? []).includes(msg.sender.id);
+        }
+        const localMention = scanMention(msg.text, {
+            agentId: msg.accountId,
+            displayName: displayNameByAgent.get(msg.accountId),
+        });
+        return shouldWake(policy, {
+            mentioned: msg.mentioned === true || localMention,
+            text: msg.text,
+        });
+    };
+    const onAgentInstalled = (info) => {
+        credentialPathByAgentId.set(info.agentId, info.credentialsFile);
+        if (info.hubUrl)
+            hubUrlByAgentId.set(info.agentId, info.hubUrl);
+        if (info.displayName)
+            displayNameByAgent.set(info.agentId, info.displayName);
+        if (!scBuilders.has(info.agentId)) {
+            scBuilders.set(info.agentId, createDaemonSystemContextBuilder({
+                agentId: info.agentId,
+                activityTracker,
+                roomContextBuilder,
+                // Cloud daemons run isolated — no loop-risk guard wired in PR1;
+                // the runtime adapter's wall-time budget enforces the equivalent.
+                loopRiskBuilder: () => null,
+            }));
+        }
+    };
+    const gateway = new Gateway({
+        config: gwConfig,
+        sessionStorePath: opts.sessionStorePath ?? SESSIONS_PATH,
+        createChannel: (chCfg) => {
+            return createDaemonChannel(chCfg, {
+                credentialPathByAgentId,
+                hubBaseUrl: cloudCfg.hubUrl,
+            });
+        },
+        log: logger,
+        turnTimeoutMs: DEFAULT_TURN_TIMEOUT_MS,
+        buildSystemContext,
+        buildMemoryContext,
+        onInbound,
+        onTurnComplete,
+        composeUserTurn: composeBotCordUserTurn,
+        attentionGate,
+        resolveHubUrl,
+        transcriptEnabled: resolveTranscriptEnabled(process.env.BOTCORD_TRANSCRIPT, opts.config.transcript?.enabled),
+    });
+    await gateway.start();
+    logger.info("cloud daemon gateway started (zero agents at boot)");
+    let controlChannel = null;
+    if (!opts.disableControlChannel) {
+        const auth = asUserAuthManager(new CloudAuthManager(cloudCfg));
+        const provisionerFactory = opts.provisionerFactory ?? createProvisioner;
+        const provisioner = provisionerFactory({
+            gateway,
+            policyResolver,
+            onAgentInstalled,
+        });
+        const ControlChannelCtor = opts.controlChannelFactory ?? ControlChannel;
+        controlChannel = new ControlChannelCtor({
+            auth,
+            // The cloud WS endpoint differs from the local daemon WS — same
+            // frame schema, different bearer-token kind on the Hub side.
+            path: "/cloud/daemon/ws",
+            handle: async (frame) => provisioner(frame),
+            label: `cloud:${cloudCfg.cloudDaemonInstanceId}`,
+        });
+        try {
+            await controlChannel.start();
+            // Same `runtime_snapshot` push as local — keeps the dashboard's
+            // "what's installed" view accurate the moment the daemon comes up.
+            const pushed = pushRuntimeSnapshot(controlChannel);
+            logger.info("cloud control-channel started; runtime_snapshot pushed", {
+                ok: pushed,
+            });
+        }
+        catch (err) {
+            logger.warn("cloud control-channel start failed; daemon will retry", {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    const snapshotWriter = new SnapshotWriter({
+        path: opts.snapshotPath ?? SNAPSHOT_PATH,
+        intervalMs: opts.snapshotIntervalMs ?? resolveSnapshotIntervalMs(),
+        snapshot: () => gateway.snapshot(),
+        log: logger,
+    });
+    snapshotWriter.start();
+    let stopping = null;
+    const stop = (reason) => {
+        if (stopping)
+            return stopping;
+        logger.info("cloud daemon stopping", { reason: reason ?? null });
+        snapshotWriter.stop();
+        snapshotWriter.writeFinal();
+        const controlStopP = controlChannel
+            ? controlChannel.stop().catch(() => undefined)
+            : Promise.resolve();
+        stopping = Promise.all([controlStopP, gateway.stop(reason)]).then(() => undefined).finally(() => {
+            snapshotWriter.remove();
+            logger.info("cloud daemon stopped", { reason: reason ?? null });
+        });
+        return stopping;
+    };
+    return {
+        stop,
+        snapshot: () => gateway.snapshot(),
+    };
+}

package/dist/cloud-mode.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Cloud-daemon mode detection + env-driven configuration.
+ *
+ * A "cloud daemon" is a `botcord-daemon` process running inside a Hub-managed
+ * E2B sandbox. It is configured exclusively through environment variables
+ * (no on-disk `user-auth.json`) and connects to `/cloud/daemon/ws` with a
+ * `cloud-daemon-access` JWT instead of the device-code-issued user token.
+ *
+ * The Hub-side provider that launches the daemon is
+ * `backend/hub/services/cloud_daemon_provider_e2b.py` — keep the env-var
+ * names below in sync with `_build_env` there.
+ *
+ * See ``docs/cloud-agent-technical-design.md`` §3-4.
+ */
+/** Names of the environment variables the cloud provider injects. */
+export declare const CLOUD_ENV_VARS: {
+    readonly HUB_URL: "BOTCORD_HUB_URL";
+    readonly CLOUD_DAEMON_INSTANCE_ID: "BOTCORD_CLOUD_DAEMON_INSTANCE_ID";
+    readonly DAEMON_INSTANCE_ID: "BOTCORD_DAEMON_INSTANCE_ID";
+    readonly ACCESS_TOKEN: "BOTCORD_CLOUD_DAEMON_ACCESS_TOKEN";
+};
+/** Resolved cloud-mode configuration. All fields are required when present. */
+export interface CloudModeConfig {
+    hubUrl: string;
+    cloudDaemonInstanceId: string;
+    daemonInstanceId: string;
+    accessToken: string;
+}
+/**
+ * Detection signal — true when `BOTCORD_CLOUD_DAEMON_ACCESS_TOKEN` is set.
+ *
+ * The access-token presence is the canonical mode switch (matches the
+ * provider contract — the token is the one piece the sandbox can't forge).
+ * Other env vars may be set during development without flipping mode.
+ */
+export declare function isCloudMode(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Resolve the cloud-mode configuration from env vars. Throws when a required
+ * variable is missing — the daemon must fail fast instead of falling through
+ * to the local-mode codepath with partial cloud config.
+ *
+ * `BOTCORD_DAEMON_INSTANCE_ID` is allowed to fall back to the cloud daemon
+ * id when omitted in tests, but in production the provider always sets it.
+ */
+export declare function loadCloudModeConfig(env?: NodeJS.ProcessEnv): CloudModeConfig;

package/dist/cloud-mode.js

@@ -0,0 +1,55 @@
+/**
+ * Cloud-daemon mode detection + env-driven configuration.
+ *
+ * A "cloud daemon" is a `botcord-daemon` process running inside a Hub-managed
+ * E2B sandbox. It is configured exclusively through environment variables
+ * (no on-disk `user-auth.json`) and connects to `/cloud/daemon/ws` with a
+ * `cloud-daemon-access` JWT instead of the device-code-issued user token.
+ *
+ * The Hub-side provider that launches the daemon is
+ * `backend/hub/services/cloud_daemon_provider_e2b.py` — keep the env-var
+ * names below in sync with `_build_env` there.
+ *
+ * See ``docs/cloud-agent-technical-design.md`` §3-4.
+ */
+/** Names of the environment variables the cloud provider injects. */
+export const CLOUD_ENV_VARS = {
+    HUB_URL: "BOTCORD_HUB_URL",
+    CLOUD_DAEMON_INSTANCE_ID: "BOTCORD_CLOUD_DAEMON_INSTANCE_ID",
+    DAEMON_INSTANCE_ID: "BOTCORD_DAEMON_INSTANCE_ID",
+    ACCESS_TOKEN: "BOTCORD_CLOUD_DAEMON_ACCESS_TOKEN",
+};
+/**
+ * Detection signal — true when `BOTCORD_CLOUD_DAEMON_ACCESS_TOKEN` is set.
+ *
+ * The access-token presence is the canonical mode switch (matches the
+ * provider contract — the token is the one piece the sandbox can't forge).
+ * Other env vars may be set during development without flipping mode.
+ */
+export function isCloudMode(env = process.env) {
+    const token = env[CLOUD_ENV_VARS.ACCESS_TOKEN];
+    return typeof token === "string" && token.length > 0;
+}
+/**
+ * Resolve the cloud-mode configuration from env vars. Throws when a required
+ * variable is missing — the daemon must fail fast instead of falling through
+ * to the local-mode codepath with partial cloud config.
+ *
+ * `BOTCORD_DAEMON_INSTANCE_ID` is allowed to fall back to the cloud daemon
+ * id when omitted in tests, but in production the provider always sets it.
+ */
+export function loadCloudModeConfig(env = process.env) {
+    const requireString = (name) => {
+        const v = env[name];
+        if (typeof v !== "string" || v.length === 0) {
+            throw new Error(`cloud-daemon mode: required env var "${name}" is missing or empty`);
+        }
+        return v;
+    };
+    return {
+        hubUrl: requireString(CLOUD_ENV_VARS.HUB_URL),
+        cloudDaemonInstanceId: requireString(CLOUD_ENV_VARS.CLOUD_DAEMON_INSTANCE_ID),
+        daemonInstanceId: requireString(CLOUD_ENV_VARS.DAEMON_INSTANCE_ID),
+        accessToken: requireString(CLOUD_ENV_VARS.ACCESS_TOKEN),
+    };
+}

package/dist/cloud-settle.d.ts

@@ -0,0 +1,81 @@
+/** Token usage breakdown reported alongside the wall-clock time. */
+export interface CloudRunSettleUsage {
+    provider: string;
+    model: string;
+    inputCacheHitTokens: number;
+    inputCacheMissTokens: number;
+    outputTokens: number;
+    sandboxSeconds: number;
+}
+/** Inputs accepted by {@link postCloudRunSettle}. */
+export interface CloudRunSettleInput extends CloudRunSettleUsage {
+    hubUrl: string;
+    accessToken: string;
+    runId: string;
+    /** Override the idempotency key. Defaults to `<run_id>:settle`. */
+    idempotencyKey?: string;
+    /** Test seam — override `fetch`. */
+    fetchFn?: typeof fetch;
+    /** Override timeout for the POST. Defaults to 10s. */
+    timeoutMs?: number;
+}
+/** Outcome of {@link postCloudRunSettle}. */
+export interface CloudRunSettleResult {
+    ok: boolean;
+    status: number;
+    /** Raw response body, when the Hub returned one. */
+    body?: unknown;
+}
+/**
+ * POST the settle payload to the Hub. Resolves with `ok=false` for non-2xx
+ * responses instead of throwing so the caller can decide whether to retry
+ * or surface the failure into the runtime log; throws only on transport
+ * errors (timeout / DNS) which are fully outside the daemon's control.
+ *
+ * Body shape matches the Hub-side `UsageEventCreate`-like contract:
+ *
+ *   {
+ *     "provider":                <str>,
+ *     "model":                   <str>,
+ *     "input_cache_hit_tokens":  <int>,
+ *     "input_cache_miss_tokens": <int>,
+ *     "output_tokens":           <int>,
+ *     "sandbox_seconds":         <int>,
+ *     "idempotency_key":         "<run_id>:settle"
+ *   }
+ *
+ * Snake_case is intentional: the Hub's Pydantic models use snake_case for
+ * the public surface even when the surrounding daemon control plane uses
+ * camelCase.
+ */
+export interface CloudRunSettleHookDeps {
+    hubUrl: string;
+    accessToken: string;
+    /** Fallback model name when the envelope doesn't carry one. */
+    defaultModel?: string;
+    /** Logger surface — only `warn` / `info` used. */
+    log?: {
+        info(msg: string, ctx?: Record<string, unknown>): void;
+        warn(msg: string, ctx?: Record<string, unknown>): void;
+    };
+    /** Test seam. */
+    fetchFn?: typeof fetch;
+}
+/** Minimal subset of an inbound message needed by the settle hook. */
+export interface CloudRunSettleHookEvent {
+    envelopeType?: string | undefined;
+    runId?: string | undefined;
+    wallTimeMs: number;
+    tokens?: {
+        inputCacheHitTokens?: number;
+        inputCacheMissTokens?: number;
+        outputTokens?: number;
+    };
+    messageId?: string;
+}
+/**
+ * Build the settle hook used by ``startCloudDaemon``. Extracted so unit
+ * tests can drive it directly without standing up the full gateway.
+ */
+export declare function buildCloudRunSettleHook(deps: CloudRunSettleHookDeps): (event: CloudRunSettleHookEvent) => Promise<void>;
+export declare function postCloudRunSettle(input: CloudRunSettleInput): Promise<CloudRunSettleResult>;

package/dist/cloud-settle.js

@@ -0,0 +1,100 @@
+/**
+ * Cloud Agent run settle helper.
+ *
+ * After a `cloud_run` envelope completes (or fails), the daemon POSTs the
+ * observed usage back to the Hub so the wallet ledger can finalize the
+ * reservation. The Hub-side endpoint is
+ * `POST /internal/cloud-agents/runs/{run_id}/settle` — see
+ * ``backend/hub/services/cloud_agent_usage.py``.
+ *
+ * Auth: the cloud daemon authenticates with its cloud-daemon-access JWT
+ * (the same token used for the WS upgrade). The Hub-side endpoint accepts
+ * either that JWT (scoped to the daemon's bound agents) or the operator
+ * `INTERNAL_API_SECRET` header — see ``hub/routers/cloud_agent_internal.py``.
+ */
+import { normalizeAndValidateHubUrl } from "@botcord/protocol-core";
+/**
+ * Build the settle hook used by ``startCloudDaemon``. Extracted so unit
+ * tests can drive it directly without standing up the full gateway.
+ */
+export function buildCloudRunSettleHook(deps) {
+    const log = deps.log;
+    const model = deps.defaultModel ?? "deepseek-v4-flash";
+    return async (event) => {
+        if (event.envelopeType !== "cloud_run")
+            return;
+        const runId = event.runId;
+        if (typeof runId !== "string" || runId.length === 0) {
+            log?.warn("cloud_run envelope missing run_id; skipping settle", {
+                messageId: event.messageId ?? "<unknown>",
+            });
+            return;
+        }
+        const sandboxSeconds = Math.max(1, Math.round(event.wallTimeMs / 1000));
+        try {
+            const settleResult = await postCloudRunSettle({
+                hubUrl: deps.hubUrl,
+                accessToken: deps.accessToken,
+                runId,
+                provider: "deepseek",
+                model,
+                // The deepseek-tui adapter does not yet surface token counts;
+                // ``UsageService`` charges by sandbox-seconds when tokens are
+                // zero. Filling these in is the next runtime-adapter PR.
+                inputCacheHitTokens: event.tokens?.inputCacheHitTokens ?? 0,
+                inputCacheMissTokens: event.tokens?.inputCacheMissTokens ?? 0,
+                outputTokens: event.tokens?.outputTokens ?? 0,
+                sandboxSeconds,
+                ...(deps.fetchFn ? { fetchFn: deps.fetchFn } : {}),
+            });
+            if (!settleResult.ok) {
+                log?.warn("cloud_run settle returned non-2xx", {
+                    runId,
+                    status: settleResult.status,
+                });
+            }
+            else {
+                log?.info("cloud_run settled", { runId, sandboxSeconds });
+            }
+        }
+        catch (err) {
+            // Transport errors only — Hub-side rejections surface as ok=false.
+            log?.warn("cloud_run settle threw — continuing", {
+                runId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    };
+}
+export async function postCloudRunSettle(input) {
+    const base = normalizeAndValidateHubUrl(input.hubUrl);
+    const url = `${base}/internal/cloud-agents/runs/${encodeURIComponent(input.runId)}/settle`;
+    const idempotencyKey = input.idempotencyKey ?? `${input.runId}:settle`;
+    const body = {
+        provider: input.provider,
+        model: input.model,
+        input_cache_hit_tokens: Math.max(0, Math.floor(input.inputCacheHitTokens)),
+        input_cache_miss_tokens: Math.max(0, Math.floor(input.inputCacheMissTokens)),
+        output_tokens: Math.max(0, Math.floor(input.outputTokens)),
+        sandbox_seconds: Math.max(0, Math.floor(input.sandboxSeconds)),
+        idempotency_key: idempotencyKey,
+    };
+    const doFetch = input.fetchFn ?? fetch;
+    const resp = await doFetch(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${input.accessToken}`,
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(input.timeoutMs ?? 10_000),
+    });
+    let parsed = undefined;
+    try {
+        parsed = await resp.json();
+    }
+    catch {
+        // Empty body on 204, etc. — leave parsed as undefined.
+    }
+    return { ok: resp.ok, status: resp.status, body: parsed };
+}