@runuai/host 0.8.26 → 0.8.28

package/lib/agents/claude.ts

@@ -28,6 +28,7 @@ import type {
   AgentEventHandler,
   AgentKind,
   AgentSession,
+  AgentUsage,
   RosterAgent,
 } from "./types";
 
@@ -59,6 +60,32 @@ function isObj(v: unknown): v is Record<string, unknown> {
   return typeof v === "object" && v !== null;
 }
 
+function num(v: unknown): number | undefined {
+  return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+
+/**
+ * Token + cost accounting from a Claude `result` line. Claude Code reports the
+ * exact `total_cost_usd` (no estimation needed) plus a token `usage` breakdown
+ * and per-model `modelUsage`. The billed model is the single modelUsage key
+ * (or, on a multi-model turn, joined).
+ */
+function claudeUsage(json: Record<string, unknown>): AgentUsage | undefined {
+  const u = isObj(json.usage) ? json.usage : {};
+  const cost = num(json.total_cost_usd);
+  const models = isObj(json.modelUsage) ? Object.keys(json.modelUsage) : [];
+  const usage: AgentUsage = {
+    model: models.length ? models.join(", ") : undefined,
+    inputTokens: num(u.input_tokens),
+    outputTokens: num(u.output_tokens),
+    cacheReadTokens: num(u.cache_read_input_tokens),
+    cacheCreateTokens: num(u.cache_creation_input_tokens),
+    costUsd: cost,
+  };
+  // Nothing usable reported → omit rather than send an empty object.
+  return Object.values(usage).some((v) => v !== undefined) ? usage : undefined;
+}
+
 /**
  * Map one stream-json stdout line to zero or more AgentEvents.
  *
@@ -119,15 +146,17 @@ export function mapClaudeLine(raw: string): AgentEvent[] {
   // --- turn result ------------------------------------------------------
   if (type === "result") {
     const text = typeof json.result === "string" ? json.result : "";
+    const usage = claudeUsage(json);
     if (json.is_error === true) {
+      // An errored turn still cost tokens — meter it.
       return [
         { type: "error", message: text || "claude returned an error" },
-        { type: "turn_complete" },
+        { type: "turn_complete", usage },
       ];
     }
     return [
       { type: "message_complete", text },
-      { type: "turn_complete" },
+      { type: "turn_complete", usage },
     ];
   }
 

package/lib/agents/types.ts

@@ -82,6 +82,24 @@ export function parseRoster(raw: string): Roster {
 // these to `uai_messages` and streams them to the browser.
 // ---------------------------------------------------------------------------
 
+/**
+ * Token + cost accounting for one turn, extracted from the agent CLI's result
+ * envelope where it reports it (Claude Code gives `usage` + `total_cost_usd`
+ * directly). Powers per-task cost visibility for self-hosted users and the
+ * metering pipeline for managed Uai-provided AI. All fields optional — an
+ * engine that doesn't report a dimension omits it.
+ */
+export interface AgentUsage {
+  /** Model the CLI actually billed (may differ from the configured model, e.g. a sub-agent). */
+  model?: string;
+  inputTokens?: number;
+  outputTokens?: number;
+  cacheReadTokens?: number;
+  cacheCreateTokens?: number;
+  /** Total USD for the turn, as reported by the CLI (authoritative when present). */
+  costUsd?: number;
+}
+
 export type AgentEvent =
   /** A chunk of streaming assistant text. Appended to the in-progress message. */
   | { type: "message_delta"; text: string }
@@ -93,8 +111,9 @@ export type AgentEvent =
   | { type: "permission_request"; id: string; title: string; detail: string }
   /** The agent addressed another agent — uai routes this as a peer message. */
   | { type: "peer_message"; toAgentId: string; text: string }
-  /** The turn (one request → response cycle) is done; agent is idle. */
-  | { type: "turn_complete" }
+  /** The turn (one request → response cycle) is done; agent is idle.
+   *  `usage` carries this turn's token/cost accounting when the CLI reports it. */
+  | { type: "turn_complete"; usage?: AgentUsage }
   /** A recoverable error surfaced by the agent. */
   | { type: "error"; message: string }
   /** The underlying process exited. */

package/lib/orchestrator.ts

@@ -715,6 +715,7 @@ class Orchestrator {
           taskId: channel.taskId,
           agentId,
           aborted,
+          usage: event.usage,
         });
         break;
       }

package/lib/standard-image.ts

@@ -305,13 +305,22 @@ async function upgradeVolumeAgentClis(): Promise<void> {
   }
 }
 
+/** Outcome of ensureStandardImage — `error` carries WHY when not ready, so
+ *  the taskUp path can surface a build failure to the cloud (not just the host
+ *  log). Callers that only fire-and-forget at boot ignore the return. */
+export interface StandardImageResult {
+  ok: boolean;
+  error?: string;
+}
+
 /**
  * Ensure the standard image and the shared asdf data volume exist, and that the
  * agent CLIs are present inside the volume. Builds the image only when `docker
- * image inspect` fails. Best-effort: logs and continues on any error so the
- * host keeps booting.
+ * image inspect` fails or the content hash is stale. Never throws — returns
+ * `{ ok, error? }` so the caller decides (boot: fire-and-forget; taskUp:
+ * surface the reason).
  */
-export async function ensureStandardImage(): Promise<void> {
+export async function ensureStandardImage(): Promise<StandardImageResult> {
   // 1. Shared asdf data volume — idempotent.
   const vol = await run("docker", ["volume", "create", ASDF_DATA_VOLUME]);
   if (vol.code !== 0) {
@@ -321,7 +330,9 @@ export async function ensureStandardImage(): Promise<void> {
     );
     // If docker itself is unavailable, the image step will also fail; bail
     // early so we don't double-log a confusing build error.
-    if (vol.code === null) return;
+    if (vol.code === null) {
+      return { ok: false, error: "Docker is not available on this host." };
+    }
   }
 
   // 2. Ensure the image is built AND current. "Present" is not enough — a
@@ -330,6 +341,7 @@ export async function ensureStandardImage(): Promise<void> {
   //    landed). The build context is content-hashed into an image label;
   //    a mismatch triggers a rebuild (layer cache keeps it cheap).
   let imageReady = false;
+  let buildError: string | null = null;
   // Install only the optional engines the operator has configured; the flags
   // are build args AND part of the content hash (so a new login rebuilds).
   const engines = configuredOptionalEngines();
@@ -356,7 +368,7 @@ export async function ensureStandardImage(): Promise<void> {
       "[host-agent] docker unavailable; skipping standard image build. " +
         "Tasks will fail until docker is running.",
     );
-    return;
+    return { ok: false, error: "Docker is not available on this host." };
   }
   const labeledHash = inspect.code === 0 ? inspect.stdout.trim() : null;
   if (inspect.code === 0 && contextHash !== null && labeledHash === contextHash) {
@@ -387,10 +399,13 @@ export async function ensureStandardImage(): Promise<void> {
       console.log(`[host-agent] built standard image ${STANDARD_IMAGE_TAG}`);
       imageReady = true;
     } else {
+      buildError =
+        build.stderr.trim() ||
+        `docker build exited ${build.code ?? "spawn error"}`;
       console.warn(
         `[host-agent] standard image build failed (exit ${build.code ?? "spawn"}); ` +
           "continuing. Tasks needing the image will surface this error.\n" +
-          build.stderr.trim(),
+          buildError,
       );
       // A stale-but-working image is better than none.
       imageReady = labeledHash !== null;
@@ -402,5 +417,12 @@ export async function ensureStandardImage(): Promise<void> {
   if (imageReady) {
     await ensureVolumeAgentClis();
     await upgradeVolumeAgentClis();
+    return { ok: true };
   }
+  return {
+    ok: false,
+    error:
+      buildError ??
+      "the standard base image (uai-standard:dev) is not built and no build error was captured.",
+  };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.8.26",
+  "version": "0.8.28",
   "description": "Uai host — runs ephemeral AI coding tasks in Docker on a machine you control.",
   "license": "MIT",
   "author": "Diogo Perillo <diogo.perillo@gmail.com>",

package/src/index.ts

@@ -1,4 +1,4 @@
-import { agent, AgentError } from "../lib/agent";
+import { agent, AgentError, toolStderrDetail } from "../lib/agent";
 import { ensureStandardImage } from "../lib/standard-image";
 import { cloneRepo } from "../lib/repo-clone";
 import { handleFilesOp } from "../lib/shared-files";
@@ -120,16 +120,27 @@ export const hostCommands: HostCommands = {
       storeTaskCliSecret(input.task.id, input.task.cliSecret);
     }
     recordHostEvent(input.task.id, "task.created");
-    // Self-heal the standard base image before task-up needs it. The boot-time
-    // build is best-effort + one-shot: if the host started before Docker was
-    // ready (common on Docker Desktop), uai-standard:dev was never built and
-    // every task-up died on a doomed registry pull (live 2026-07-22). This is
-    // idempotent — a fast image-inspect when present, a real build only when
-    // missing/stale (Docker is definitely up now, a task just arrived). Never
-    // throws; a build failure surfaces as a clear STANDARD_IMAGE_MISSING from
-    // task-up.sh's guard.
-    await ensureStandardImage();
-    const result = await wrapAgent(ctx, "taskUp", () => agent.taskUp(input));
+    const result = await wrapAgent(ctx, "taskUp", async () => {
+      // Self-heal the standard base image before task-up needs it. The
+      // boot-time build is best-effort + one-shot: a host that started before
+      // Docker was ready (common on Docker Desktop) never built
+      // uai-standard:dev, so every task-up died on a doomed registry pull
+      // (live 2026-07-22). This is idempotent — a fast inspect when present,
+      // a real build only when missing/stale (Docker is definitely up now, a
+      // task just arrived). On a build FAILURE, surface WHY to the cloud (not
+      // just the host log — the operator can't read a remote user's machine).
+      const img = await ensureStandardImage();
+      if (!img.ok) {
+        throw new AgentError(
+          "STANDARD_IMAGE_UNAVAILABLE",
+          img.error
+            ? `could not prepare the host base image uai-standard:dev — the build failed. ${toolStderrDetail(img.error)}`
+            : "could not prepare the host base image uai-standard:dev — see the host log.",
+          {},
+        );
+      }
+      return agent.taskUp(input);
+    });
     if (result.ok) {
       recordTaskUpResult(input.task.id, result.value);
       recordHostEvent(input.task.id, "task.started");

package/src/protocol.ts

@@ -580,6 +580,16 @@ export type HostEvent =
       taskId: string;
       agentId: string;
       aborted?: boolean;
+      /** Token/cost accounting for the turn, when the engine reports it
+       *  (ADR-071 usage metering — powers per-task cost + managed AI billing). */
+      usage?: {
+        model?: string;
+        inputTokens?: number;
+        outputTokens?: number;
+        cacheReadTokens?: number;
+        cacheCreateTokens?: number;
+        costUsd?: number;
+      };
     }
   | {
       kind: "agent.tool_call";