@runuai/host 0.9.162 → 0.9.163

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,
@@ -227,6 +233,7 @@ import {
 import { env } from "./env";
 import type {
   ChannelEnsureInput,
+  EngineUsageFrame,
   ChannelHuman,
   HostEvent,
 } from "../src/protocol";
@@ -247,6 +254,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 +586,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 +792,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 +813,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 +935,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 {
@@ -4586,6 +4649,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 +4993,105 @@ 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;
+
+        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,
+          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({
+          kind: "engine.usage",
+          reportId: newId(),
+          taskId: channel.taskId,
+          agentId,
+          engine: agent.kind,
+          credentialId: identity.credentialId,
+          status: event.usage.status,
+          ...(event.usage.resetsAt === undefined
+            ? {}
+            : { resetsAt: event.usage.resetsAt }),
+          ...(event.usage.usingOverage === undefined
+            ? {}
+            : { usingOverage: event.usage.usingOverage }),
+          windows: event.usage.windows,
+          source: event.usage.source,
+          observedAt: event.usage.observedAt,
+        });
+        // 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 +5226,7 @@ export class Orchestrator {
             agentId,
             agent,
             abortBoundaryOnRosterChange,
+            event.resetsAt,
           ))
         ) {
           break;
@@ -5583,6 +5747,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,7 +5771,10 @@ 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,
@@ -6156,6 +6324,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.
@@ -6888,8 +7057,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 +7083,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.163",
   "description": "Uai host — runs ephemeral AI tasks in containers on a machine you control.",
   "license": "MIT",
   "author": "Uai Tech <team@runuai.com>",

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.

package/src/protocol.ts

@@ -156,6 +156,60 @@ 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;
+  /** `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,
@@ -4806,6 +4860,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";