@runuai/host 0.9.162 → 0.9.164

package/lib/orchestrator.ts

@@ -31,6 +31,7 @@ import { dirname, join } from "node:path";
 import { inArray } from "drizzle-orm";
 
 import { getDb, schema } from "./db";
+import { newId } from "./ulid";
 import { mockAgentFactory } from "./agents/mock";
 import { realAgentFactory } from "./agents/factory";
 import { resolveAgentMode } from "./agents/mode";
@@ -152,7 +153,12 @@ import {
   codexHomeIsolatable,
   codexHomeSeedCommand,
   codexPerAgentHome,
+  clearEngineAccountCooldowns,
+  clearEngineAccountCooldownWindow,
   cooldownEngineAccount,
+  cooldownEngineAccountUntil,
+  cooldownEngineAccountWindow,
+  cooldownEngineAccountWindowUntil,
   noteEngineAccountUsed,
   pickEngineAccount,
   provisionEngineAccounts,
@@ -160,6 +166,7 @@ import {
   selectAccount,
   type ResolvedEngineAccount,
 } from "./engine-accounts";
+import { buildEngineUsageFrame } from "../src/engine-usage";
 import {
   ENGINE_ACCOUNT_HOMES,
   EngineCredentialWriteRefused,
@@ -227,6 +234,7 @@ import {
 import { env } from "./env";
 import type {
   ChannelEnsureInput,
+  EngineUsageFrame,
   ChannelHuman,
   HostEvent,
 } from "../src/protocol";
@@ -247,6 +255,17 @@ import {
 import { forgetTaskEnvSnapshot } from "./task-env-source";
 
 export type HostEventSubscriber = (event: HostEvent) => void;
+/** True means the frame reached the current cloud transport generation. */
+export type EngineUsageSubscriber = (frame: EngineUsageFrame) => boolean;
+
+export const ENGINE_USAGE_REFRESH_MS = 15 * 60_000;
+
+interface DeliveredEngineUsage {
+  payload: string;
+  sentAt: number;
+  taskId: string;
+  agentId: string;
+}
 
 // Rolling upgrade fence: v0 Secretary runners were launched under the
 // communicator tool-denial profile and may survive a host restart. Durable
@@ -568,6 +587,18 @@ const LEASED_CREDENTIAL_BLANKS: Readonly<Record<string, string>> = Object.freeze
  *  again. */
 const LEASED_SYNC_RETRY_MS = 30_000;
 
+const ENGINE_USAGE_KINDS = new Set<EngineUsageFrame["engine"]>([
+  "claude",
+  "codex",
+  "grok",
+  "cursor",
+  "opencode",
+]);
+
+function isEngineUsageKind(kind: string): kind is EngineUsageFrame["engine"] {
+  return ENGINE_USAGE_KINDS.has(kind as EngineUsageFrame["engine"]);
+}
+
 /** ADR-154 §6: the exact lease material a spawn starts on: an AI account's,
  *  or, for the Managed Engine, the task's open run alone (its agent's task
  *  token is its credential). */
@@ -762,6 +793,10 @@ export class Orchestrator {
    *  later command cannot overtake an earlier one after channel close. */
   private readonly taskLifecycleTails = new Map<string, Promise<void>>();
   private readonly hostSubscribers = new Set<HostEventSubscriber>();
+  private readonly engineUsageSubscribers = new Set<EngineUsageSubscriber>();
+  /** Last payload (excluding report id/time) for each leased account + agent.
+   * Structured Claude events can repeat without any state change. */
+  private readonly lastEngineUsage = new Map<string, DeliveredEngineUsage>();
   /** ADR-154 §6: launch slots retired whose retirement has not yet reached
    *  their runtime, per task, whatever channel they were in: an agent's next
    *  spawn launches there only once they have (`retireLeasedLaunch`). */
@@ -779,6 +814,11 @@ export class Orchestrator {
     return () => this.hostSubscribers.delete(fn);
   }
 
+  subscribeEngineUsageFrames(fn: EngineUsageSubscriber): () => void {
+    this.engineUsageSubscribers.add(fn);
+    return () => this.engineUsageSubscribers.delete(fn);
+  }
+
   /**
    * The cloud credential composer changed the MCP view it serves for a task.
    * Its committed lease view, not the independently delivered channel spec,
@@ -896,6 +936,30 @@ export class Orchestrator {
     }
   }
 
+  private emitEngineUsage(frame: EngineUsageFrame): boolean {
+    let delivered = false;
+    for (const fn of this.engineUsageSubscribers) {
+      try {
+        delivered = fn(frame) || delivered;
+      } catch {
+        // Usage is best-effort; a broken bridge subscriber cannot affect a
+        // running agent turn.
+      }
+    }
+    return delivered;
+  }
+
+  private forgetEngineUsage(taskId: string, agentId?: string): void {
+    for (const [key, delivered] of this.lastEngineUsage) {
+      if (
+        delivered.taskId === taskId &&
+        (agentId === undefined || delivered.agentId === agentId)
+      ) {
+        this.lastEngineUsage.delete(key);
+      }
+    }
+  }
+
   // -- channel lifecycle ----------------------------------------------------
 
   registerChannelSpec(spec: ChannelEnsureInput): void {
@@ -1683,11 +1747,19 @@ export class Orchestrator {
     channel: Channel,
     kind: string,
     exclude?: Set<string>,
+    preferredId?: string,
   ): ResolvedEngineAccount | null {
     if (!this.isLeasedChannel(channel)) {
-      return pickEngineAccount(kind, { scope: channel.engineAccountScope, exclude });
+      return pickEngineAccount(kind, {
+        scope: channel.engineAccountScope,
+        exclude,
+        preferredId,
+      });
     }
-    return selectAccount(this.engineAccounts(channel, kind), { exclude });
+    return selectAccount(this.engineAccounts(channel, kind), {
+      exclude,
+      preferredId,
+    });
   }
 
   private noteProvisionMutation(
@@ -2726,6 +2798,7 @@ export class Orchestrator {
     if (this.isLeasedChannel(channel)) return { ...floor, ...base };
     const account = pickEngineAccount(agent.kind, {
       scope: channel.engineAccountScope,
+      preferredId: agent.accountId,
     });
     if (!account) {
       channel.accountByAgent.delete(agent.id);
@@ -3318,8 +3391,14 @@ export class Orchestrator {
         account.engineKind === kind && isLeasedEngineAccount(account),
     );
     const bound = channel.accountByAgent.get(agentId);
+    const preferredId = channel.roster.find(
+      (candidate) => candidate.id === agentId,
+    )?.accountId;
     const kept = accounts.find((account) => account.credentialId === bound);
-    if (kept) return kept;
+    // Without a pin, preserve the live binding. With one, every fresh session
+    // re-evaluates it: a cooling/missing pin falls through now, and wins again
+    // automatically after its bench lifts.
+    if (!preferredId && kept) return kept;
     const picked = selectAccount(
       accounts.map((account) => ({
         id: account.credentialId,
@@ -3330,6 +3409,7 @@ export class Orchestrator {
         authKind: account.authKind,
         execEnv: {},
       })),
+      { preferredId },
     );
     return accounts.find((account) => account.credentialId === picked?.id);
   }
@@ -4586,6 +4666,7 @@ export class Orchestrator {
    * could silently restart canceled work on the new generation.
    */
   private retireRunnerGeneration(channel: Channel, agentId: string): void {
+    this.forgetEngineUsage(channel.taskId, agentId);
     const aborted = channel.interrupted.delete(agentId);
     channel.activeTurns.delete(agentId);
     channel.acceptedPrompts.delete(agentId);
@@ -4929,6 +5010,108 @@ export class Orchestrator {
   ): Promise<void> {
     if (!this.isActiveChannel(channel)) return;
     switch (event.type) {
+      case "account_usage": {
+        // Only the exact live session's cloud-leased ACCOUNT may be named on
+        // the wire. A runner default slot and the Managed Engine's task-token
+        // identity are deliberately unreportable.
+        if (channel.sessions.get(agentId) !== session) break;
+        const identity = channel.leasedIdentityByAgent.get(agentId);
+        if (!identity || identity.subject !== "account") break;
+        const agent = channel.roster.find((candidate) => candidate.id === agentId);
+        if (!agent || !isEngineUsageKind(agent.kind)) break;
+        // The session's own revision: a refreshed lease may already hold a
+        // newer one, and its variable name says nothing about this session.
+        const leasedAccount = leasedEnginesFor(channel.taskId)?.accounts.find(
+          (candidate): candidate is LeasedEngineAccount =>
+            candidate.credentialId === identity.credentialId &&
+            candidate.revision === identity.revision &&
+            isLeasedEngineAccount(candidate),
+        );
+        const frame = buildEngineUsageFrame({
+          reportId: newId(),
+          taskId: channel.taskId,
+          agentId,
+          engine: agent.kind,
+          credentialId: identity.credentialId,
+          revision: identity.revision,
+          usage: event.usage,
+          leasedAccount,
+        });
+
+        const coverage = event.usage.coverage;
+        if (event.usage.status === "limited") {
+          const limitedWindows =
+            coverage?.kind === "all-windows"
+              ? event.usage.windows
+                  .filter((window) => (window.usedPercent ?? 0) >= 100)
+                  .map((window) => window.window)
+              : coverage?.kind === "window"
+                ? [coverage.window]
+                : [];
+          const causes = limitedWindows.length > 0 ? limitedWindows : [null];
+          for (const window of causes) {
+            if (window === null) {
+              if (event.usage.resetsAt === undefined) {
+                cooldownEngineAccount(identity.credentialId);
+              } else {
+                cooldownEngineAccountUntil(
+                  identity.credentialId,
+                  event.usage.resetsAt,
+                );
+              }
+            } else if (event.usage.resetsAt === undefined) {
+              cooldownEngineAccountWindow(identity.credentialId, window);
+            } else {
+              cooldownEngineAccountWindowUntil(
+                identity.credentialId,
+                window,
+                event.usage.resetsAt,
+              );
+            }
+          }
+        } else if (coverage?.kind === "window") {
+          clearEngineAccountCooldownWindow(
+            identity.credentialId,
+            coverage.window,
+          );
+        } else if (coverage?.kind === "all-windows") {
+          clearEngineAccountCooldowns(identity.credentialId);
+        }
+
+        const key = `${identity.credentialId}\0${agentId}`;
+        const payload = JSON.stringify({
+          taskId: channel.taskId,
+          engine: agent.kind,
+          credentialId: identity.credentialId,
+          billing: frame.billing,
+          revision: frame.revision,
+          status: event.usage.status,
+          resetsAt: event.usage.resetsAt,
+          usingOverage: event.usage.usingOverage,
+          windows: event.usage.windows,
+          source: event.usage.source,
+        });
+        const now = Date.now();
+        const previous = this.lastEngineUsage.get(key);
+        if (
+          previous?.payload === payload &&
+          now - previous.sentAt < ENGINE_USAGE_REFRESH_MS
+        ) {
+          break;
+        }
+        const delivered = this.emitEngineUsage(frame);
+        // A disconnected bridge returns false. Do not suppress the next
+        // identical observation unless this one actually reached the socket.
+        if (delivered) {
+          this.lastEngineUsage.set(key, {
+            payload,
+            sentAt: now,
+            taskId: channel.taskId,
+            agentId,
+          });
+        }
+        break;
+      }
       case "message_delta": {
         this.markActiveTurn(channel, agentId);
         channel.openTurns.add(agentId);
@@ -5063,6 +5246,7 @@ export class Orchestrator {
             agentId,
             agent,
             abortBoundaryOnRosterChange,
+            event.resetsAt,
           ))
         ) {
           break;
@@ -5583,6 +5767,7 @@ export class Orchestrator {
     agentId: string,
     agent: RosterAgent,
     abortBoundaryOnRosterChange = false,
+    resetsAt?: number,
   ): Promise<boolean> {
     if (!this.isActiveChannel(channel)) return true;
     if (channel.rosterSessionChanges.has(agentId)) {
@@ -5606,11 +5791,15 @@ export class Orchestrator {
     if (budget > MAX_ROTATIONS_PER_AGENT) return false;
 
     const current = channel.accountByAgent.get(agentId);
-    if (current) cooldownEngineAccount(current);
+    if (current) {
+      if (resetsAt === undefined) cooldownEngineAccount(current);
+      else cooldownEngineAccountUntil(current, resetsAt);
+    }
     const next = this.pickAccount(
       channel,
       agent.kind,
       current ? new Set([current]) : undefined,
+      agent.accountId,
     );
     if (!next) return false;
 
@@ -6156,6 +6345,7 @@ export class Orchestrator {
     this.channelSpecs.delete(taskId);
     const ch = this.channels.get(taskId);
     if (!ch) return Promise.resolve();
+    this.forgetEngineUsage(taskId);
     // Invalidate the generation BEFORE the first await. Browser setup and the
     // start/reconcile factory continuations all check this identity, so none
     // can repopulate an orphan channel while its sessions close.
@@ -6477,6 +6667,9 @@ function rosterLaunchChangeReason(
   if (previous.kind !== next.kind) changed.push("engine");
   if ((previous.model ?? "") !== (next.model ?? "")) changed.push("model");
   if ((previous.effort ?? "") !== (next.effort ?? "")) changed.push("effort");
+  if ((previous.accountId ?? "") !== (next.accountId ?? "")) {
+    changed.push("account");
+  }
   // ADR-157 §3: the session holds a token minted for its generation, so a new
   // one is a new agent under the handle (or one an older cloud release lost),
   // and only a fresh launch carries a token the cloud accepts.
@@ -6888,8 +7081,8 @@ export function buildSystemPreamble(
           "  (at least one of the three; `default` as the model or effort clears it to",
           "  the engine's own default)",
           "- `crew remove @agent --why \"…\"`",
-          "Use the smallest crew the job needs, often none: do small work yourself and",
-          "hire only when parallel work or a different skill or model pays for itself.",
+          "Use the smallest crew the job needs, often none, and hire only when",
+          "parallel work or a different skill or model pays for itself.",
           "A new agent is idle until you `dispatch` to it, so brief it then. Remove an",
           "agent when its part is done; its handle is not reused, so hiring that",
           "persona again gives it a new one. A model change restarts that agent and drops",
@@ -6914,18 +7107,24 @@ export function buildSystemPreamble(
               "connections and persona permissions of any task agent, except native",
               "subagents: helpers your engine starts on its own would work outside the",
               "crew, unpriced and unseen by the humans, so they are switched off. Work",
-              "for another agent goes to a crew agent through `dispatch`. Your default",
-              "job is to communicate,",
+              "for another agent goes to a crew agent through `dispatch`.",
+              // One rule for who does the work, the plan's, so this section and
+              // "Your crew" cannot disagree: the crew may be nobody.
+              "Who does each step is your plan's call: do it yourself when one agent",
+              "is enough, hand it to the crew when parallel work or another skill or",
+              "model pays for itself. A human's request for you to do something",
+              "yourself overrides the plan.",
+              "",
             ]
           : [
               "Your Secretary role is prompt-guided, not tool-restricted. You have the",
               "same normal tools, approved MCP connections, model choice, and persona",
               "permissions as any other task agent. Your default job is to communicate,",
+              "coordinate, and dispatch implementation work rather than doing it yourself.",
+              "If the human explicitly asks YOU to make a change, you may use those tools",
+              "and do it directly; otherwise hand mutations to a crew agent.",
+              "",
             ]),
-        "coordinate, and dispatch implementation work rather than doing it yourself.",
-        "If the human explicitly asks YOU to make a change, you may use those tools",
-        "and do it directly; otherwise hand mutations to a crew agent.",
-        "",
       ]
     : [];
   const groupMessageBrief = isSecretary

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.9.162",
+  "version": "0.9.164",
   "description": "Uai host — runs ephemeral AI tasks in containers on a machine you control.",
   "license": "MIT",
   "author": "Uai Tech <team@runuai.com>",
@@ -72,6 +72,14 @@
     "./project-env-wording": {
       "types": "./src/project-env-wording.ts",
       "default": "./src/project-env-wording.ts"
+    },
+    "./engine-models": {
+      "types": "./src/engine-models.ts",
+      "default": "./src/engine-models.ts"
+    },
+    "./engine-usage": {
+      "types": "./src/engine-usage.ts",
+      "default": "./src/engine-usage.ts"
     }
   },
   "scripts": {

package/src/engine-models.ts

@@ -0,0 +1,31 @@
+/**
+ * The models each engine adapter offers, by the id the runner passes its
+ * CLI: one list per engine, read by the adapters (`supportedModels`) and by
+ * the cloud's model guide (lib/model-guide.ts), whose test fails when a model
+ * here has no guide entry. Pure data: no runtime imports.
+ */
+
+// Claude Code's aliases, which follow its own model table (2.1.307:
+// fable = Claude Fable 5.1, opus = Opus 5.5, sonnet = Sonnet 5.5,
+// haiku = Haiku 5.5). Update alongside the CLI.
+export const CLAUDE_MODELS: readonly string[] = ["fable", "opus", "sonnet", "haiku"];
+
+// Codex model slugs accepted via `-c model=<slug>`. Hardcoded: Codex has no
+// machine-readable "list models" command — the canonical list is the
+// interactive `codex` model picker (and `codex -m <slug>` / config.toml).
+// Sourced from that picker; UPDATE WHEN MODELS CHANGE. Order = display order
+// in the cloud picker. Legacy models remain reachable via config.toml.
+export const CODEX_MODELS: readonly string[] = [
+  "gpt-6-astra",
+  "gpt-5.6-sol",
+  "gpt-5.6-terra",
+  "gpt-5.6-luna",
+  "gpt-5.5",
+  "gpt-5.4",
+  "gpt-5.4-mini",
+  "gpt-5.3-codex",
+  "gpt-5.3-codex-spark",
+  "gpt-5.2",
+];
+
+export const GROK_MODELS: readonly string[] = ["grok-4.5"];

package/src/engine-usage.ts

@@ -0,0 +1,104 @@
+/**
+ * Build the secret-free account usage report sent to Uai Cloud.
+ *
+ * A leased env account carries both a variable name and its secret value in
+ * runner memory. Billing is deliberately inferred from the NAME alone. Some
+ * file-backed accounts use the same `auth.json` name for a subscription and
+ * an API key, so they carry no hint.
+ *
+ * The hint names the revision it was read from, and is given only when that is
+ * the revision the reporting session runs on: after a re-paste, a lease
+ * refresh can hand the runner newer material than an agent is still using.
+ */
+
+import type { EngineUsageFrame, EngineUsageWindow } from "./protocol";
+
+type EngineUsageBilling = NonNullable<EngineUsageFrame["billing"]>;
+
+export interface LeasedBillingAccount {
+  credentialId: string;
+  revision: string;
+  engineKind: string;
+  authKind: "env" | "config-dir";
+  env: Readonly<Record<string, string>> | null;
+}
+
+export interface EngineUsageObservation {
+  status: EngineUsageFrame["status"];
+  resetsAt?: number;
+  usingOverage?: boolean;
+  windows: EngineUsageWindow[];
+  source: EngineUsageFrame["source"];
+  observedAt: number;
+}
+
+const BILLING_BY_VARIABLE: Readonly<
+  Record<string, Readonly<Record<string, EngineUsageBilling>>>
+> = Object.freeze({
+  claude: Object.freeze({
+    // Capture files every pasted Claude secret that is NOT `sk-ant-api…` under
+    // this name (engine-accounts.ts `pastedSecretMaterial`), so the name alone
+    // also covers a token whose prefix told capture nothing, which the cloud
+    // left unknown. Subscription is still right for a report: usage is read
+    // from a session that worked, and Claude Code authenticates this variable
+    // only as an OAuth (subscription) token, so a session that ran on it was
+    // one. Do not "correct" it to unknown.
+    CLAUDE_CODE_OAUTH_TOKEN: "subscription",
+    ANTHROPIC_API_KEY: "api-key",
+  }),
+  cursor: Object.freeze({ CURSOR_API_KEY: "api-key" }),
+  grok: Object.freeze({ XAI_API_KEY: "api-key" }),
+});
+
+/** The billing lane when one leased variable name tells it unambiguously. */
+export function billingFromLeasedVariableName(
+  account: LeasedBillingAccount | null | undefined,
+): EngineUsageBilling | undefined {
+  if (!account || account.authKind !== "env" || account.env === null) {
+    return undefined;
+  }
+  const names = Object.keys(account.env);
+  if (names.length !== 1) return undefined;
+  return BILLING_BY_VARIABLE[account.engineKind]?.[names[0]!];
+}
+
+/** Construct the exact wire frame for one adapter usage observation.
+ *  `revision` is the one the reporting session runs on; a leased account at
+ *  any other revision gives no hint. */
+export function buildEngineUsageFrame(input: {
+  reportId: string;
+  taskId: string;
+  agentId: string;
+  engine: EngineUsageFrame["engine"];
+  credentialId: string;
+  revision?: string;
+  usage: EngineUsageObservation;
+  leasedAccount?: LeasedBillingAccount | null;
+}): EngineUsageFrame {
+  const { usage } = input;
+  const account =
+    input.revision !== undefined &&
+    input.leasedAccount?.credentialId === input.credentialId &&
+    input.leasedAccount.revision === input.revision &&
+    input.leasedAccount.engineKind === input.engine
+      ? input.leasedAccount
+      : null;
+  const billing = billingFromLeasedVariableName(account);
+  return {
+    kind: "engine.usage",
+    reportId: input.reportId,
+    taskId: input.taskId,
+    agentId: input.agentId,
+    engine: input.engine,
+    credentialId: input.credentialId,
+    ...(billing === undefined ? {} : { billing, revision: account!.revision }),
+    status: usage.status,
+    ...(usage.resetsAt === undefined ? {} : { resetsAt: usage.resetsAt }),
+    ...(usage.usingOverage === undefined
+      ? {}
+      : { usingOverage: usage.usingOverage }),
+    windows: usage.windows,
+    source: usage.source,
+    observedAt: usage.observedAt,
+  };
+}

package/src/main.ts

@@ -285,6 +285,7 @@ import { hostCommands, hostEvents, setManagedHostRestartHook } from "./index";
 import { EventOutbox, transmitEventOutbox } from "./event-outbox";
 import {
   HostErrorCode,
+  ENGINE_USAGE_PROTOCOL_FEATURE,
   EVENT_REPLAY_PROTOCOL_FEATURE,
   GITHUB_CREDENTIAL_GENERATION_PROTOCOL_FEATURE,
   GITHUB_INSTALLATION_VERIFICATION_PROTOCOL_FEATURE,
@@ -1486,6 +1487,7 @@ function buildCapabilities(): HostCapabilities {
       HOST_ENGINE_ACCOUNT_SCOPES_PROTOCOL_FEATURE,
       HOST_ENGINE_ACCOUNT_MANAGE_PROTOCOL_FEATURE,
       HOST_ENGINE_DISCONNECT_PROTOCOL_FEATURE,
+      ENGINE_USAGE_PROTOCOL_FEATURE,
       LIVE_ROSTER_EDIT_PROTOCOL_FEATURE,
       AGENT_TOKEN_GENERATION_PROTOCOL_FEATURE,
       // The echo adapter cannot execute the in-task CLI. Advertising typed
@@ -2874,6 +2876,11 @@ async function connect(): Promise<void> {
       return false;
     }
   };
+  const stopEngineUsageSubscription = getOrchestrator().subscribeEngineUsageFrames(
+    (frame) => {
+      return sendRemoteOperationFrame(frame);
+    },
+  );
 
   let projectEnvOperationTail = Promise.resolve();
   const projectEnvGenerationIsCurrent = (): boolean =>
@@ -2916,6 +2923,7 @@ async function connect(): Promise<void> {
   };
 
   const cleanup = (): void => {
+    stopEngineUsageSubscription();
     // Connection loss revokes the serving gate before deferred transport
     // cleanup yields. A late close from a superseded socket must not revoke a
     // replacement generation that has already committed its fresh snapshot.
@@ -5528,6 +5536,14 @@ function expectTaskAgents(value: unknown): TaskAgent[] {
     // effort was previously dropped here even though the protocol + adapters
     // carry it — fixed alongside skills (ADR-046).
     if (typeof row.effort === "string") out.effort = row.effort;
+    if (
+      typeof row.accountId === "string" &&
+      row.accountId.length > 0 &&
+      row.accountId.length <= 128 &&
+      /^[A-Za-z0-9_.:-]+$/.test(row.accountId)
+    ) {
+      out.accountId = row.accountId;
+    }
     if (row.uaiProvider === "anthropic" || row.uaiProvider === "openai") {
       out.uaiProvider = row.uaiProvider;
     }

package/src/protocol.ts

@@ -156,6 +156,68 @@ export const HOST_ENGINE_ACCOUNT_MANAGE_PROTOCOL_FEATURE =
   "host-engine-account-manage-v1";
 export const HOST_ENGINE_ACCOUNT_SCOPES_PROTOCOL_FEATURE =
   "host-engine-account-scopes-v1";
+/** AI-account usage (ADR-157 slice 3, amended 2026-10-21): the host reports
+ * what an engine CLI said about the account an agent runs on — Claude Code's
+ * `rate_limit_event`, Codex's `account/rateLimits` — and the reset time of a
+ * cut-off, as `engine.usage` frames. Reports are best-effort and
+ * self-superseding: a lost one is replaced by the next. The cloud keeps the
+ * latest per account and never asks the provider itself (subscription
+ * sign-ins are for the engine CLIs only). A host advertises this once it
+ * sends the frames; the cloud needs nothing from a host without it. */
+export const ENGINE_USAGE_PROTOCOL_FEATURE = "engine-usage-v1";
+export const MAX_ENGINE_USAGE_WINDOWS = 8;
+
+/** One usage window of an AI account, in the engine's own terms. Every
+ *  measurement is optional: an engine reports what it reports. */
+export interface EngineUsageWindow {
+  /** The engine's name for the window: Claude's `rateLimitType`
+   *  (`five_hour`, `seven_day`, `seven_day_opus`, …) or Codex's `primary` /
+   *  `secondary`. At most 64 characters. */
+  window: string;
+  /** Window length in minutes. */
+  windowMinutes?: number;
+  /** Share of the window used, 0–100. */
+  usedPercent?: number;
+  /** When the window resets, epoch ms. */
+  resetsAt?: number;
+}
+
+/** One usage report for one leased AI account (ADR-154 `credentialId`).
+ *  Accounts that are not cloud credentials (a host's own default slot) are
+ *  never reported. */
+export interface EngineUsageFrame {
+  kind: "engine.usage";
+  /** Host-minted, unique per report; a repeat is ignored. */
+  reportId: string;
+  taskId: string;
+  agentId: string;
+  engine: "claude" | "codex" | "grok" | "cursor" | "opencode";
+  /** The `uai_credentials` id the agent's session runs on. */
+  credentialId: string;
+  /** How this account is paid for, when the leased variable's NAME tells the
+   *  runner unambiguously. Derived only from that name, never from its value. */
+  billing?: "subscription" | "api-key";
+  /** The credential revision whose variable name gave `billing`: the one the
+   *  agent's session runs on. Sent only with `billing`; an id, not a secret.
+   *  The cloud records the hint only while this is still the account's active
+   *  revision, so a task on an older lease cannot describe newer material. */
+  revision?: string;
+  /** `allowed`: working; `warning`: the engine says it is close to a limit;
+   *  `limited`: cut off until `resetsAt` (or an unknown time). */
+  status: "allowed" | "warning" | "limited";
+  /** When a `limited` account should work again, epoch ms, if known. */
+  resetsAt?: number;
+  /** Whether the engine says it is now billing past the plan (Claude
+   *  "overage"), when it says. */
+  usingOverage?: boolean;
+  windows: EngineUsageWindow[];
+  /** What the report was read from. */
+  source: "claude-rate-limit-event" | "codex-rate-limits" | "error-text";
+  /** When the engine said it, epoch ms (host clock). The cloud keeps the
+   *  newest per account, so a late report never overwrites a newer one. */
+  observedAt: number;
+}
+
 /** ADR-049 addendum: live roster edits. On channel.ensure the host diffs the
  * live roster against the spec — an agent whose kind, model or effort changed
  * has its session recycled so the reconciler respawns it on the new settings,
@@ -3067,6 +3129,8 @@ export interface TaskAgent {
   kind: string;
   model?: string;
   effort?: string;
+  /** ADR-157 addendum §7: preferred cloud-leased AI account. */
+  accountId?: string;
   defaultPrompt?: string;
   initialPrompt?: string;
   /** ADR-046 reference material resolved from the agent's persona + team.
@@ -4806,6 +4870,7 @@ export type HostToCloud =
   // cloud's replay watermark only applies within a matching boot. Optional
   // for pre-103 hosts (which also never send seq'd events).
   | { kind: "auth"; token: string; hostId: string; bootId?: string }
+  | EngineUsageFrame
   | { kind: "host.capabilities"; capabilities: HostCapabilities }
   | {
       kind: "host.inventory.page";