@drisp/protocol 0.8.3 → 0.8.5

package/dist/v2.d.ts

@@ -26,10 +26,50 @@ declare function attemptCost(attempt: {
     tokenCap: number;
     closed: boolean;
 }): number;
+/** A class needs this many finished Runs of a harness before its forecast is measured (DRI-244). */
+declare const CALIBRATION_MIN_RUNS = 10;
+/** Only Runs closed within this many days count. */
+declare const CALIBRATION_WINDOW_DAYS = 90;
+/** What one size class measured to: the figure the plan uses, and how many finished Runs it rests on. */
+type ClassCalibration = Readonly<Partial<Record<SizeClass, {
+    forecast: number;
+    runs: number;
+}>>>;
+/** The measured classes per harness name; a harness or class with too few Runs is absent. */
+type Calibration = Readonly<Partial<Record<string, ClassCalibration>>>;
+/** One finished Run's final counted tokens (cache reads excluded), by its harness and the class its cap belongs to. */
+type CalibrationSample = {
+    harness: string;
+    sizeClass: SizeClass;
+    counted: number | undefined;
+};
+/**
+ * The forecast of each class and harness with at least `CALIBRATION_MIN_RUNS` samples: max(constant, p90 of the
+ * samples), the p90 by nearest rank. The constants are the floor, so calibration only raises a forecast. A sample with
+ * no figure is ignored. Which Runs are samples (completed, first attempt, in the window) is the Hub's to say.
+ */
+declare function calibrate(samples: readonly CalibrationSample[]): Calibration;
+/** `GET /calibration`: the measured classes per harness name. */
+declare const calibrationSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    S: z.ZodOptional<z.ZodObject<{
+        forecast: z.ZodNumber;
+        runs: z.ZodNumber;
+    }, z.core.$strict>>;
+    M: z.ZodOptional<z.ZodObject<{
+        forecast: z.ZodNumber;
+        runs: z.ZodNumber;
+    }, z.core.$strict>>;
+    L: z.ZodOptional<z.ZodObject<{
+        forecast: z.ZodNumber;
+        runs: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>>;
+/** A class's forecast: its measured figure when `calibration` has one, else the constant. */
+declare function forecastOfClass(sizeClass: SizeClass, calibration: ClassCalibration | undefined): number;
 
 declare const protocolVersion: {
     readonly major: 2;
-    readonly minor: 2;
+    readonly minor: 3;
 };
 declare const conversationContinuationCapability = "conversation_continuation";
 declare const abandonedConversationContinuationCapability = "abandoned_conversation_continuation";
@@ -41,6 +81,12 @@ declare const workflowInstallCapability = "workflow_install_v1";
  * token to the agent as `DRISP_RUN_TOKEN`. A start with `delegation` is never sent to a runner without it.
  */
 declare const runDelegationCapability = "run_delegation_v1";
+/**
+ * The runner takes grants marked `reportUsage` (protocol minor 3, root ADR-0011) and, for those only, reports the
+ * Run's usage: on `run.attention` and `run.finished`, and as `run.usage` while it executes. A Hub that does not know
+ * these fields never marks a grant, so it never receives them.
+ */
+declare const runUsageCapability = "run_usage_v1";
 /** The prefix of every delegation token; the Hub keeps only its digest. */
 declare const delegationTokenPrefix = "drisp_dlg_";
 /** A `run.artifact` history record's `name`, and the most its `json` may take serialized. */
@@ -168,6 +214,15 @@ declare const runCloseReasonSchema: z.ZodEnum<{
     legacy_force_failed: "legacy_force_failed";
 }>;
 type RunCloseReason = z.infer<typeof runCloseReasonSchema>;
+/**
+ * A Run's cumulative usage (root ADR-0011): `counted` is its tokens without cache reads (`total − cacheRead`), the unit
+ * the Run cap counts on every harness, and `cacheRead` the cache reads left out of it.
+ */
+declare const runUsageSchema: z.ZodObject<{
+    counted: z.ZodNumber;
+    cacheRead: z.ZodNumber;
+}, z.core.$strict>;
+type RunUsage = z.infer<typeof runUsageSchema>;
 declare const controlRecordSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"workflows.changed">;
     workflows: z.ZodArray<z.ZodObject<{
@@ -227,6 +282,10 @@ declare const controlRecordSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     emittedAt: z.ZodISODateTime;
     kind: z.ZodLiteral<"run.resumed">;
 }, z.core.$strict>, z.ZodObject<{
+    usage: z.ZodOptional<z.ZodObject<{
+        counted: z.ZodNumber;
+        cacheRead: z.ZodNumber;
+    }, z.core.$strict>>;
     interruption: z.ZodObject<{
         interruptionId: z.ZodString;
         revision: z.ZodNumber;
@@ -263,6 +322,10 @@ declare const controlRecordSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     emittedAt: z.ZodISODateTime;
     kind: z.ZodLiteral<"run.attention">;
 }, z.core.$strict>, z.ZodObject<{
+    usage: z.ZodOptional<z.ZodObject<{
+        counted: z.ZodNumber;
+        cacheRead: z.ZodNumber;
+    }, z.core.$strict>>;
     status: z.ZodEnum<{
         completed: "completed";
         failed: "failed";
@@ -281,6 +344,12 @@ declare const controlRecordSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     executionRevision: z.ZodNumber;
     emittedAt: z.ZodISODateTime;
     kind: z.ZodLiteral<"run.finished">;
+}, z.core.$strict>, z.ZodObject<{
+    counted: z.ZodNumber;
+    cacheRead: z.ZodNumber;
+    kind: z.ZodLiteral<"run.usage">;
+    runId: z.ZodString;
+    attemptId: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"command.applied">;
     runId: z.ZodString;
@@ -531,6 +600,7 @@ declare const grantSchema: z.ZodObject<{
         runId: z.ZodString;
         tokenCap: z.ZodNumber;
     }, z.core.$strict>>;
+    reportUsage: z.ZodOptional<z.ZodLiteral<true>>;
 }, z.core.$strict>;
 declare const historyRecordSchema: z.ZodObject<{
     eventId: z.ZodString;
@@ -645,6 +715,10 @@ declare const runnerFrameSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         emittedAt: z.ZodISODateTime;
         kind: z.ZodLiteral<"run.resumed">;
     }, z.core.$strict>, z.ZodObject<{
+        usage: z.ZodOptional<z.ZodObject<{
+            counted: z.ZodNumber;
+            cacheRead: z.ZodNumber;
+        }, z.core.$strict>>;
         interruption: z.ZodObject<{
             interruptionId: z.ZodString;
             revision: z.ZodNumber;
@@ -681,6 +755,10 @@ declare const runnerFrameSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         emittedAt: z.ZodISODateTime;
         kind: z.ZodLiteral<"run.attention">;
     }, z.core.$strict>, z.ZodObject<{
+        usage: z.ZodOptional<z.ZodObject<{
+            counted: z.ZodNumber;
+            cacheRead: z.ZodNumber;
+        }, z.core.$strict>>;
         status: z.ZodEnum<{
             completed: "completed";
             failed: "failed";
@@ -699,6 +777,12 @@ declare const runnerFrameSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         executionRevision: z.ZodNumber;
         emittedAt: z.ZodISODateTime;
         kind: z.ZodLiteral<"run.finished">;
+    }, z.core.$strict>, z.ZodObject<{
+        counted: z.ZodNumber;
+        cacheRead: z.ZodNumber;
+        kind: z.ZodLiteral<"run.usage">;
+        runId: z.ZodString;
+        attemptId: z.ZodString;
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"command.applied">;
         runId: z.ZodString;
@@ -779,6 +863,10 @@ declare const runViewSchema: z.ZodObject<{
     delegation: z.ZodOptional<z.ZodObject<{
         maxChildren: z.ZodNumber;
         tokenBudget: z.ZodNumber;
+    }, z.core.$strip>>;
+    usage: z.ZodOptional<z.ZodObject<{
+        counted: z.ZodNumber;
+        cacheRead: z.ZodNumber;
     }, z.core.$strict>>;
     workflow: z.ZodOptional<z.ZodObject<{
         name: z.ZodString;
@@ -1068,6 +1156,7 @@ declare const checkpointSchema: z.ZodObject<{
             runId: z.ZodString;
             tokenCap: z.ZodNumber;
         }, z.core.$strict>>;
+        reportUsage: z.ZodOptional<z.ZodLiteral<true>>;
     }, z.core.$strict>;
     gitHead: z.ZodString;
     gitBase: z.ZodOptional<z.ZodString>;
@@ -1427,4 +1516,4 @@ type ConnectPendingResponse = z.infer<typeof connectPendingResponseSchema>;
 type TeamDefault = z.infer<typeof teamDefaultSchema>;
 type RunsGoTo = z.infer<typeof runsGoToSchema>;
 
-export { type Audience, type BuildCloseReason, type Checkpoint, type Command, type ConnectAlreadyConnected, type ConnectPendingResponse, type ConnectRedeemRequest, type ConnectRedeemResponse, type ConnectStartRequest, type ConnectStartResponse, type ControlRecord, type Delegation, type ExecutionFact, type Grant, type Harness, type HarnessReadiness, type HistoryRecord, type InstalledWorkflow, type RepositoryBinding, type RepositorySource, type RunCloseReason, type RunParent, type RunView, type RunnerAdoptRequest, type RunnerDisconnectPreview, type RunnerDisconnectResponse, type RunnerFrame, type RunnerList, type RunnerListEntry, type RunnerReadiness, type RunsGoTo, SIZE_CLASS_CAPS, SIZE_CLASS_FORECASTS, type Scope, type SizeClass, type TeamDefault, type WorkflowIdentity, type WorkflowInstallReference, type WorkflowReference, abandonedConversationContinuationCapability, attemptCost, audienceSchema, buildCloseReasonSchema, canonicalJson, checkpointPathSchema, checkpointSchema, classOfCap, clientFrameSchema, commandSchema, connectAlreadyConnectedSchema, connectApproveRequestSchema, connectCodeAlphabet, connectCodeRequestSchema, connectCodeResponseSchema, connectCodeSchema, connectDenyRequestSchema, connectPendingResponseSchema, connectPollRequestSchema, connectRedeemRequestSchema, connectRedeemResponseSchema, connectStartRequestSchema, connectStartResponseSchema, controlRecordSchema, conversationContinuationCapability, delegationSchema, delegationTokenPrefix, forecastOfCap, grantSchema, harnessReadinessSchema, harnessSchema, historyRecordSchema, hubEpochRequestSchema, installReference, installedWorkflowsSchema, interruptionSchema, permissionAnswerSchema, protocolVersion, readableHistory, readinessFixCommand, repositoryAccessCapability, repositoryBindingSchema, repositoryRefSchema, repositorySourceSchema, repositoryWorkingDirectorySchema, runArtifactMaxBytes, runArtifactNameSchema, runCloseReasonSchema, runDelegationCapability, runKeySchema, runParentIntentSchema, runParentSchema, runSpecSchema, runViewSchema, runnerAdoptRequestSchema, runnerDisconnectPreviewSchema, runnerDisconnectRequestSchema, runnerDisconnectResponseSchema, runnerFrameSchema, runnerListEntrySchema, runnerListSchema, runnerReadinessSchema, runnerUpdateCommand, runnerUpdateRequestSchema, runsGoToSchema, sameWorkflow, scopeSchema, secretEnvironmentSchema, sequence, teamDefaultRequestSchema, teamDefaultSchema, workflowIdentitySchema, workflowInstallCapability, workflowName, workflowReferenceSchema, workflowSourceSchema };
+export { type Audience, type BuildCloseReason, CALIBRATION_MIN_RUNS, CALIBRATION_WINDOW_DAYS, type Calibration, type CalibrationSample, type Checkpoint, type ClassCalibration, type Command, type ConnectAlreadyConnected, type ConnectPendingResponse, type ConnectRedeemRequest, type ConnectRedeemResponse, type ConnectStartRequest, type ConnectStartResponse, type ControlRecord, type Delegation, type ExecutionFact, type Grant, type Harness, type HarnessReadiness, type HistoryRecord, type InstalledWorkflow, type RepositoryBinding, type RepositorySource, type RunCloseReason, type RunParent, type RunUsage, type RunView, type RunnerAdoptRequest, type RunnerDisconnectPreview, type RunnerDisconnectResponse, type RunnerFrame, type RunnerList, type RunnerListEntry, type RunnerReadiness, type RunsGoTo, SIZE_CLASS_CAPS, SIZE_CLASS_FORECASTS, type Scope, type SizeClass, type TeamDefault, type WorkflowIdentity, type WorkflowInstallReference, type WorkflowReference, abandonedConversationContinuationCapability, attemptCost, audienceSchema, buildCloseReasonSchema, calibrate, calibrationSchema, canonicalJson, checkpointPathSchema, checkpointSchema, classOfCap, clientFrameSchema, commandSchema, connectAlreadyConnectedSchema, connectApproveRequestSchema, connectCodeAlphabet, connectCodeRequestSchema, connectCodeResponseSchema, connectCodeSchema, connectDenyRequestSchema, connectPendingResponseSchema, connectPollRequestSchema, connectRedeemRequestSchema, connectRedeemResponseSchema, connectStartRequestSchema, connectStartResponseSchema, controlRecordSchema, conversationContinuationCapability, delegationSchema, delegationTokenPrefix, forecastOfCap, forecastOfClass, grantSchema, harnessReadinessSchema, harnessSchema, historyRecordSchema, hubEpochRequestSchema, installReference, installedWorkflowsSchema, interruptionSchema, permissionAnswerSchema, protocolVersion, readableHistory, readinessFixCommand, repositoryAccessCapability, repositoryBindingSchema, repositoryRefSchema, repositorySourceSchema, repositoryWorkingDirectorySchema, runArtifactMaxBytes, runArtifactNameSchema, runCloseReasonSchema, runDelegationCapability, runKeySchema, runParentIntentSchema, runParentSchema, runSpecSchema, runUsageCapability, runUsageSchema, runViewSchema, runnerAdoptRequestSchema, runnerDisconnectPreviewSchema, runnerDisconnectRequestSchema, runnerDisconnectResponseSchema, runnerFrameSchema, runnerListEntrySchema, runnerListSchema, runnerReadinessSchema, runnerUpdateCommand, runnerUpdateRequestSchema, runsGoToSchema, sameWorkflow, scopeSchema, secretEnvironmentSchema, sequence, teamDefaultRequestSchema, teamDefaultSchema, workflowIdentitySchema, workflowInstallCapability, workflowName, workflowReferenceSchema, workflowSourceSchema };

package/dist/v2.js

@@ -3,7 +3,7 @@ import {
 } from "./chunk-HMYWICNI.js";
 
 // src/v2.ts
-import { z } from "zod";
+import { z as z2 } from "zod";
 
 // src/history.ts
 function readableHistory(records) {
@@ -48,6 +48,7 @@ function readableHistory(records) {
 }
 
 // src/budget.ts
+import { z } from "zod";
 var SIZE_CLASS_CAPS = {
   S: 3e6,
   M: 6e6,
@@ -71,38 +72,68 @@ function attemptCost(attempt) {
   const forecast = forecastOfCap(attempt.tokenCap);
   return attempt.tokenCap > 0 ? Math.min(attempt.tokenCap, forecast) : forecast;
 }
+var CALIBRATION_MIN_RUNS = 10;
+var CALIBRATION_WINDOW_DAYS = 90;
+function calibrate(samples) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const { harness, sizeClass, counted } of samples) {
+    if (counted === void 0 || !Number.isFinite(counted) || counted < 0) continue;
+    const key = `${harness}\0${sizeClass}`;
+    const group = byKey.get(key) ?? { harness, sizeClass, counted: [] };
+    group.counted.push(counted);
+    byKey.set(key, group);
+  }
+  const result = {};
+  for (const { harness, sizeClass, counted } of byKey.values()) {
+    if (counted.length < CALIBRATION_MIN_RUNS) continue;
+    const sorted = [...counted].sort((a, b) => a - b);
+    const p90 = sorted[Math.ceil(sorted.length * 0.9) - 1];
+    (result[harness] ??= {})[sizeClass] = { forecast: Math.max(SIZE_CLASS_FORECASTS[sizeClass], p90), runs: sorted.length };
+  }
+  return result;
+}
+var classCalibrationSchema = z.strictObject({
+  S: z.strictObject({ forecast: z.number(), runs: z.number() }).optional(),
+  M: z.strictObject({ forecast: z.number(), runs: z.number() }).optional(),
+  L: z.strictObject({ forecast: z.number(), runs: z.number() }).optional()
+});
+var calibrationSchema = z.record(z.string(), classCalibrationSchema);
+function forecastOfClass(sizeClass, calibration) {
+  return calibration?.[sizeClass]?.forecast ?? SIZE_CLASS_FORECASTS[sizeClass];
+}
 
 // src/v2.ts
-var protocolVersion = { major: 2, minor: 2 };
+var protocolVersion = { major: 2, minor: 3 };
 var conversationContinuationCapability = "conversation_continuation";
 var abandonedConversationContinuationCapability = "abandoned_conversation_continuation";
 var repositoryAccessCapability = "repository_checkout_v1";
 var workflowInstallCapability = "workflow_install_v1";
 var runDelegationCapability = "run_delegation_v1";
+var runUsageCapability = "run_usage_v1";
 var delegationTokenPrefix = "drisp_dlg_";
-var runArtifactNameSchema = z.string().regex(/^[a-z][a-z0-9_]{0,63}$/);
+var runArtifactNameSchema = z2.string().regex(/^[a-z][a-z0-9_]{0,63}$/);
 var runArtifactMaxBytes = 64 * 1024;
-var secretEnvironmentSchema = z.record(
-  z.string().regex(/^(?:OPENAI_API_KEY|ANTHROPIC_API_KEY|CLAUDE_CODE_OAUTH_TOKEN|NPM_TOKEN|NODE_AUTH_TOKEN|PIP_INDEX_URL|PIP_EXTRA_INDEX_URL|UV_INDEX_URL|DRISP_TEST_[A-Z0-9_]+)$/),
-  z.string().regex(/^projects\/[a-zA-Z0-9-]+\/secrets\/[a-zA-Z0-9_-]+\/versions\/(?:latest|[0-9]+)$/)
+var secretEnvironmentSchema = z2.record(
+  z2.string().regex(/^(?:OPENAI_API_KEY|ANTHROPIC_API_KEY|CLAUDE_CODE_OAUTH_TOKEN|NPM_TOKEN|NODE_AUTH_TOKEN|PIP_INDEX_URL|PIP_EXTRA_INDEX_URL|UV_INDEX_URL|DRISP_TEST_[A-Z0-9_]+)$/),
+  z2.string().regex(/^projects\/[a-zA-Z0-9-]+\/secrets\/[a-zA-Z0-9_-]+\/versions\/(?:latest|[0-9]+)$/)
 );
-var permissionAnswerSchema = z.strictObject({
-  kind: z.literal("permission"),
-  decision: z.enum(["allow", "deny"]),
-  reason: z.string().max(4096).optional()
+var permissionAnswerSchema = z2.strictObject({
+  kind: z2.literal("permission"),
+  decision: z2.enum(["allow", "deny"]),
+  reason: z2.string().max(4096).optional()
 });
-var id = z.string().min(1).max(160);
-var sequence = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+var id = z2.string().min(1).max(160);
+var sequence = z2.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
 var positive = sequence.refine((n) => n > 0);
-var timestamp = z.iso.datetime();
-var scopeSchema = z.discriminatedUnion("visibility", [
-  z.strictObject({ visibility: z.literal("organization") }),
-  z.strictObject({ visibility: z.literal("private"), ownerUserId: id })
+var timestamp = z2.iso.datetime();
+var scopeSchema = z2.discriminatedUnion("visibility", [
+  z2.strictObject({ visibility: z2.literal("organization") }),
+  z2.strictObject({ visibility: z2.literal("private"), ownerUserId: id })
 ]);
-var installedWorkflowsSchema = z.array(InstalledWorkflowSchema).max(256);
-var harnessSchema = z.enum(["claude-code", "codex"]);
-var harnessReadinessSchema = z.strictObject({ installed: z.boolean(), signedIn: z.boolean() });
-var runnerReadinessSchema = z.strictObject({
+var installedWorkflowsSchema = z2.array(InstalledWorkflowSchema).max(256);
+var harnessSchema = z2.enum(["claude-code", "codex"]);
+var harnessReadinessSchema = z2.strictObject({ installed: z2.boolean(), signedIn: z2.boolean() });
+var runnerReadinessSchema = z2.strictObject({
   "claude-code": harnessReadinessSchema.optional(),
   codex: harnessReadinessSchema.optional()
 });
@@ -117,25 +148,25 @@ function readinessFixCommand(harness, readiness) {
   return void 0;
 }
 var runnerUpdateCommand = "npm i -g @drisp/cli";
-var interruptionSchema = z.strictObject({
+var interruptionSchema = z2.strictObject({
   interruptionId: id,
   revision: positive,
   /** `waiting` (root ADR-0008) is non-human: a Run parked until one of its children closes or parks. */
-  kind: z.enum(["permission", "question", "guidance", "recovery", "waiting"]),
-  message: z.string().max(16384),
+  kind: z2.enum(["permission", "question", "guidance", "recovery", "waiting"]),
+  message: z2.string().max(16384),
   requestId: id.optional()
 });
-var workflowIdentitySchema = z.strictObject({
-  name: z.string().min(1).max(128),
-  version: z.string().min(1).max(128).optional()
+var workflowIdentitySchema = z2.strictObject({
+  name: z2.string().min(1).max(128),
+  version: z2.string().min(1).max(128).optional()
 });
-var buildCloseReasonSchema = z.enum([
+var buildCloseReasonSchema = z2.enum([
   "workflow_template_mismatch",
   "child_project_dir_invalid",
   "build_not_approved",
   "approval_question_missing"
 ]);
-var runCloseReasonSchema = z.enum([
+var runCloseReasonSchema = z2.enum([
   "execution_terminal",
   "cancelled_before_start",
   "admission_failed",
@@ -158,129 +189,138 @@ var factIdentity = {
   executionRevision: positive,
   emittedAt: timestamp
 };
-var controlRecordSchema = z.discriminatedUnion("kind", [
+var runUsageSchema = z2.strictObject({ counted: sequence, cacheRead: sequence });
+var reportedUsage = { usage: runUsageSchema.optional() };
+var controlRecordSchema = z2.discriminatedUnion("kind", [
   /** Instance-scoped, not tied to a Run: the full replacement inventory of installed Workflows. */
-  z.strictObject({ kind: z.literal("workflows.changed"), workflows: installedWorkflowsSchema }),
+  z2.strictObject({ kind: z2.literal("workflows.changed"), workflows: installedWorkflowsSchema }),
   /** Instance-scoped, not tied to a Run: the Runner's full Readiness, sent when it changes after hello. */
-  z.strictObject({ kind: z.literal("readiness.changed"), readiness: runnerReadinessSchema }),
-  z.strictObject({ kind: z.literal("assignment.accepted"), runId: id, attemptId: id }),
-  z.strictObject({
-    kind: z.literal("assignment.rejected"),
+  z2.strictObject({ kind: z2.literal("readiness.changed"), readiness: runnerReadinessSchema }),
+  z2.strictObject({ kind: z2.literal("assignment.accepted"), runId: id, attemptId: id }),
+  z2.strictObject({
+    kind: z2.literal("assignment.rejected"),
     runId: id,
     attemptId: id,
-    reason: z.string().max(1024)
+    reason: z2.string().max(1024)
   }),
-  z.strictObject({
-    kind: z.literal("run.started"),
+  z2.strictObject({
+    kind: z2.literal("run.started"),
     ...factIdentity,
     /** Absent from runners that predate Workflow reporting. */
     workflow: workflowIdentitySchema.optional()
   }),
-  z.strictObject({ kind: z.literal("run.resumed"), ...factIdentity }),
-  z.strictObject({
-    kind: z.literal("run.attention"),
+  z2.strictObject({ kind: z2.literal("run.resumed"), ...factIdentity }),
+  z2.strictObject({
+    kind: z2.literal("run.attention"),
     ...factIdentity,
     interruption: interruptionSchema,
-    occupancy: z.enum(["held", "released"]),
+    occupancy: z2.enum(["held", "released"]),
     historyThrough: sequence,
-    continuation: z.discriminatedUnion("kind", [
-      z.strictObject({ kind: z.literal("live_request") }),
-      z.strictObject({ kind: z.literal("local_checkpoint"), checkpointId: id }),
-      z.strictObject({ kind: z.literal("portable_checkpoint"), checkpointId: id }),
-      z.strictObject({ kind: z.literal("repair_required"), detail: z.string().max(4096) })
-    ])
+    continuation: z2.discriminatedUnion("kind", [
+      z2.strictObject({ kind: z2.literal("live_request") }),
+      z2.strictObject({ kind: z2.literal("local_checkpoint"), checkpointId: id }),
+      z2.strictObject({ kind: z2.literal("portable_checkpoint"), checkpointId: id }),
+      z2.strictObject({ kind: z2.literal("repair_required"), detail: z2.string().max(4096) })
+    ]),
+    ...reportedUsage
   }),
-  z.strictObject({
-    kind: z.literal("run.finished"),
+  z2.strictObject({
+    kind: z2.literal("run.finished"),
     ...factIdentity,
-    status: z.enum(["completed", "failed", "cancelled"]),
+    status: z2.enum(["completed", "failed", "cancelled"]),
     historyThrough: sequence,
     /** No setup/harness executed and no workspace was produced; safe to retire without export. */
-    workspaceUnavailable: z.literal(true).optional(),
+    workspaceUnavailable: z2.literal(true).optional(),
     /**
      * Why a Build Run failed, as its close reason (docs/specs/build-orchestrator.md). Sent only for a grant with
      * `parent` or `delegationToken`, which only a Hub that knows this field issues.
      */
-    reason: buildCloseReasonSchema.optional()
+    reason: buildCloseReasonSchema.optional(),
+    ...reportedUsage
   }),
-  z.strictObject({ kind: z.literal("command.applied"), runId: id, attemptId: id, commandId: id }),
-  z.strictObject({
-    kind: z.literal("command.rejected"),
+  /**
+   * The usage of a Run while it executes, for a grant marked `reportUsage`. Not an execution fact: it carries no
+   * execution revision, so it never advances, parks or closes the Run, and never wakes its parent.
+   */
+  z2.strictObject({ kind: z2.literal("run.usage"), runId: id, attemptId: id, ...runUsageSchema.shape }),
+  z2.strictObject({ kind: z2.literal("command.applied"), runId: id, attemptId: id, commandId: id }),
+  z2.strictObject({
+    kind: z2.literal("command.rejected"),
     runId: id,
     attemptId: id,
     commandId: id,
-    reason: z.string().max(1024)
+    reason: z2.string().max(1024)
   }),
-  z.strictObject({ kind: z.literal("revoked_not_started"), runId: id, attemptId: id })
+  z2.strictObject({ kind: z2.literal("revoked_not_started"), runId: id, attemptId: id })
 ]);
-var repositoryRefSchema = z.string().min(1).max(512).regex(
+var repositoryRefSchema = z2.string().min(1).max(512).regex(
   /^(?![-/])(?!.*\.\.)(?!.*@\{)(?!.*(?:^|\/)\.)(?!.*\.lock(?:\/|$))(?!.*\/\/)[^\x00-\x20\x7f~^:?*\[\\]+(?<![/.])$/
 );
-var repositoryWorkingDirectorySchema = z.string().min(1).max(1024).regex(
+var repositoryWorkingDirectorySchema = z2.string().min(1).max(1024).regex(
   /^(?:\.|(?!\/)(?!.*(?:^|\/)\.\.?(?:\/|$))(?!.*(?:^|\/)\.git(?:\/|$))[^\x00-\x1f\x7f\\:]+(?<!\/))$/
 );
 var repositoryIdentity = {
-  repositoryId: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
-  installationId: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
-  owner: z.string().min(1).max(100).regex(/^[a-zA-Z0-9][a-zA-Z0-9-]*$/),
-  name: z.string().min(1).max(100).regex(/^(?!\.{1,2}$)[a-zA-Z0-9_.-]+$/)
+  repositoryId: z2.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+  installationId: z2.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+  owner: z2.string().min(1).max(100).regex(/^[a-zA-Z0-9][a-zA-Z0-9-]*$/),
+  name: z2.string().min(1).max(100).regex(/^(?!\.{1,2}$)[a-zA-Z0-9_.-]+$/)
 };
-var repositoryBindingSchema = z.strictObject({
+var repositoryBindingSchema = z2.strictObject({
   id,
-  label: z.string().min(1).max(160),
+  label: z2.string().min(1).max(160),
   ...repositoryIdentity,
   defaultRef: repositoryRefSchema,
   workingDirectory: repositoryWorkingDirectorySchema,
-  setupCommands: z.array(z.string().min(1).max(8192)).max(16),
+  setupCommands: z2.array(z2.string().min(1).max(8192)).max(16),
   revision: positive,
-  enabled: z.boolean()
+  enabled: z2.boolean()
 });
-var repositorySourceSchema = z.strictObject({
+var repositorySourceSchema = z2.strictObject({
   bindingId: id,
   ...repositoryIdentity,
   ref: repositoryRefSchema,
-  commitSha: z.string().regex(/^[0-9a-f]{40}$/),
+  commitSha: z2.string().regex(/^[0-9a-f]{40}$/),
   branch: repositoryRefSchema,
   workingDirectory: repositoryWorkingDirectorySchema,
-  setupCommands: z.array(z.string().min(1).max(8192)).max(16),
+  setupCommands: z2.array(z2.string().min(1).max(8192)).max(16),
   configRevision: positive
 });
-var workflowSourceSchema = z.string().max(201).regex(/^[A-Za-z0-9][A-Za-z0-9_.-]*\/[A-Za-z0-9][A-Za-z0-9_.-]*$/);
-var workflowReferenceSchema = z.union([
-  z.string().max(512),
-  z.strictObject({
-    name: z.string().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9_-]*$/),
+var workflowSourceSchema = z2.string().max(201).regex(/^[A-Za-z0-9][A-Za-z0-9_.-]*\/[A-Za-z0-9][A-Za-z0-9_.-]*$/);
+var workflowReferenceSchema = z2.union([
+  z2.string().max(512),
+  z2.strictObject({
+    name: z2.string().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9_-]*$/),
     source: workflowSourceSchema.optional(),
-    ref: z.string().min(1).max(512).optional(),
-    version: z.string().min(1).max(128).regex(/^\d[A-Za-z0-9_.+-]*$/).optional()
+    ref: z2.string().min(1).max(512).optional(),
+    version: z2.string().min(1).max(128).regex(/^\d[A-Za-z0-9_.+-]*$/).optional()
   })
 ]);
 var workflowName = (workflow) => typeof workflow === "object" ? workflow.name : workflow;
 var installReference = (workflow) => typeof workflow === "object" && workflow.source !== void 0 ? workflow : void 0;
 var sameWorkflow = (a, b) => canonicalJson(a ?? null) === canonicalJson(b ?? null);
-var runSpecSchema = z.strictObject({
-  prompt: z.string().min(1).max(131072),
-  projectDir: z.string().min(1).max(4096),
+var runSpecSchema = z2.strictObject({
+  prompt: z2.string().min(1).max(131072),
+  projectDir: z2.string().min(1).max(4096),
   harness: harnessSchema,
   workflow: workflowReferenceSchema.optional(),
   repository: repositorySourceSchema.optional()
 });
-var runKeySchema = z.string().min(1).max(160);
-var delegationSchema = z.strictObject({
-  maxChildren: z.number().int().min(1).max(8),
-  tokenBudget: z.number().int().positive().max(Number.MAX_SAFE_INTEGER)
+var runKeySchema = z2.string().min(1).max(160);
+var delegationSchema = z2.strictObject({
+  maxChildren: z2.number().int().min(1).max(8),
+  tokenBudget: z2.number().int().positive().max(Number.MAX_SAFE_INTEGER)
 });
-var tokenCapSchema = z.number().int().positive().max(Number.MAX_SAFE_INTEGER);
-var runParentIntentSchema = z.strictObject({ runId: id, tokenCap: tokenCapSchema.optional() });
-var runParentSchema = z.strictObject({ runId: id, tokenCap: tokenCapSchema });
-var commandSchema = z.strictObject({
+var tokenCapSchema = z2.number().int().positive().max(Number.MAX_SAFE_INTEGER);
+var runParentIntentSchema = z2.strictObject({ runId: id, tokenCap: tokenCapSchema.optional() });
+var runParentSchema = z2.strictObject({ runId: id, tokenCap: tokenCapSchema });
+var commandSchema = z2.strictObject({
   commandId: id,
   hubEpoch: id,
   runId: id,
   expectedRecordRevision: sequence.optional(),
-  intent: z.discriminatedUnion("kind", [
-    z.strictObject({
-      kind: z.literal("start"),
+  intent: z2.discriminatedUnion("kind", [
+    z2.strictObject({
+      kind: z2.literal("start"),
       sessionId: id,
       /**
        * Absent: the Hub resolves the Runner member-first (root ADR-0005): the Session's conversation Runner, else
@@ -296,24 +336,24 @@ var commandSchema = z.strictObject({
       /** Delegated starts only, and required on them. */
       parent: runParentIntentSchema.optional()
     }),
-    z.strictObject({ kind: z.literal("cancel") }),
-    z.strictObject({ kind: z.literal("abandon") }),
-    z.strictObject({ kind: z.literal("steer"), text: z.string().min(1).max(131072) }),
-    z.strictObject({
-      kind: z.literal("answer"),
+    z2.strictObject({ kind: z2.literal("cancel") }),
+    z2.strictObject({ kind: z2.literal("abandon") }),
+    z2.strictObject({ kind: z2.literal("steer"), text: z2.string().min(1).max(131072) }),
+    z2.strictObject({
+      kind: z2.literal("answer"),
       interruptionId: id,
       expectedInterruptionRevision: positive,
       requestId: id.optional(),
-      answer: z.json()
+      answer: z2.json()
     }),
-    z.strictObject({
-      kind: z.literal("resume"),
+    z2.strictObject({
+      kind: z2.literal("resume"),
       interruptionId: id,
-      guidance: z.string().max(131072).optional()
+      guidance: z2.string().max(131072).optional()
     })
   ])
 });
-var grantSchema = z.strictObject({
+var grantSchema = z2.strictObject({
   commandId: id,
   hubEpoch: id,
   runId: id,
@@ -325,113 +365,121 @@ var grantSchema = z.strictObject({
   baseExecutionRevision: sequence,
   baseHistorySeq: sequence,
   cloudHistoryThrough: sequence,
-  purpose: z.enum(["start", "resume"]),
+  purpose: z2.enum(["start", "resume"]),
   spec: runSpecSchema,
-  continuation: z.json().optional(),
+  continuation: z2.json().optional(),
   /** A new Run in a durable conversation; never resumes the predecessor's lifecycle. */
-  previousRun: z.strictObject({
+  previousRun: z2.strictObject({
     runId: id,
     executionRevision: sequence,
     historyProduced: sequence,
     /** Hub-confirmed administrative closure; allows an exact parked predecessor snapshot. */
-    closeReason: z.literal("abandoned").optional(),
-    checkpoint: z.strictObject({ checkpointId: id, checksum: z.string().regex(/^[a-f0-9]{64}$/) }).optional()
+    closeReason: z2.literal("abandoned").optional(),
+    checkpoint: z2.strictObject({ checkpointId: id, checksum: z2.string().regex(/^[a-f0-9]{64}$/) }).optional()
   }).optional(),
-  checkpoint: z.strictObject({ checkpointId: id, checksum: z.string().regex(/^[a-f0-9]{64}$/) }).optional(),
+  checkpoint: z2.strictObject({ checkpointId: id, checksum: z2.string().regex(/^[a-f0-9]{64}$/) }).optional(),
   /** This attempt's delegation token: only for a Run started with `delegation`, only to a `run_delegation_v1` Runner. */
-  delegationToken: z.string().min(32).max(256).optional(),
+  delegationToken: z2.string().min(32).max(256).optional(),
   /** Copied from the start intent of a delegated child. */
-  parent: runParentSchema.optional()
+  parent: runParentSchema.optional(),
+  /** The runner reports this attempt's usage: set only for a `run_usage_v1` Runner. */
+  reportUsage: z2.literal(true).optional()
 });
-var historyRecordSchema = z.strictObject({
+var historyRecordSchema = z2.strictObject({
   eventId: id,
   attemptId: id,
   emittedAt: timestamp,
-  kind: z.string().min(1).max(128),
-  data: z.json()
+  kind: z2.string().min(1).max(128),
+  data: z2.json()
 });
-var runnerFrameSchema = z.discriminatedUnion("type", [
-  z.strictObject({
-    type: z.literal("hello"),
-    role: z.literal("runner"),
-    protocol: z.strictObject({ major: z.literal(2), minor: sequence }),
+var runnerFrameSchema = z2.discriminatedUnion("type", [
+  z2.strictObject({
+    type: z2.literal("hello"),
+    role: z2.literal("runner"),
+    protocol: z2.strictObject({ major: z2.literal(2), minor: sequence }),
     runnerId: id,
     installationId: id,
-    softwareVersion: z.string().max(128),
-    capabilities: z.array(z.string().max(128)).max(64),
+    softwareVersion: z2.string().max(128),
+    capabilities: z2.array(z2.string().max(128)).max(64),
     /** Absent from older runners: the Hub treats the inventory as unknown, never as empty. */
     workflows: installedWorkflowsSchema.optional(),
     /** Absent from older runners, and from a runner that has not finished its first check: unknown, not "not ready". */
     readiness: runnerReadinessSchema.optional(),
-    control: z.strictObject({ firstRetainedSeq: positive, lastProducedSeq: sequence })
+    control: z2.strictObject({ firstRetainedSeq: positive, lastProducedSeq: sequence })
   }),
-  z.strictObject({
-    type: z.literal("control.batch"),
+  z2.strictObject({
+    type: z2.literal("control.batch"),
     firstSeq: positive,
-    records: z.array(controlRecordSchema).min(1).max(128)
+    records: z2.array(controlRecordSchema).min(1).max(128)
   }),
-  z.strictObject({
-    type: z.literal("history.batch"),
+  z2.strictObject({
+    type: z2.literal("history.batch"),
     runId: id,
     firstSeq: positive,
-    records: z.array(historyRecordSchema).min(1).max(128)
+    records: z2.array(historyRecordSchema).min(1).max(128)
   }),
-  z.strictObject({ type: z.literal("ping"), nonce: id }),
-  z.strictObject({
-    type: z.literal("reconcile.page"),
+  z2.strictObject({ type: z2.literal("ping"), nonce: id }),
+  z2.strictObject({
+    type: z2.literal("reconcile.page"),
     inventoryId: id.default("single-page"),
     page: sequence.default(0),
-    complete: z.boolean(),
-    runs: z.array(
-      z.strictObject({
+    complete: z2.boolean(),
+    runs: z2.array(
+      z2.strictObject({
         runId: id,
         attemptId: id,
         executionRevision: sequence,
-        phase: z.enum(["admitted", "prepared", "executing", "parked", "terminal", "recovery"])
+        phase: z2.enum(["admitted", "prepared", "executing", "parked", "terminal", "recovery"])
       })
     ).max(128)
   })
 ]);
-var runViewSchema = z.object({
+var runViewSchema = z2.object({
   runId: id,
   sessionId: id,
   runnerId: id,
   computeProfileId: id.optional(),
   scope: scopeSchema,
   recordRevision: positive,
-  label: z.string().max(160).optional(),
+  label: z2.string().max(160).optional(),
   key: runKeySchema.optional(),
   parent: runParentSchema.optional(),
-  delegation: delegationSchema.optional(),
+  /**
+   * Not strict, unlike the start intent's: a Hub keeps more on the Run's delegation (`initialTokenBudget`) than it
+   * shows, and a client never refuses a view for a field it does not read.
+   */
+  delegation: z2.object(delegationSchema.shape).optional(),
+  /** The largest cumulative usage the Run's Runner reported; absent until one does (an older Runner never does). */
+  usage: runUsageSchema.optional(),
   /** Resolved by the runner at start; absent until the Run starts and for runners that predate reporting. */
   workflow: workflowIdentitySchema.optional(),
-  execution: z.object({
-    status: z.enum(["running", "awaiting_attention", "completed", "failed", "cancelled"]),
+  execution: z2.object({
+    status: z2.enum(["running", "awaiting_attention", "completed", "failed", "cancelled"]),
     revision: positive,
     attemptId: id,
-    occupancy: z.enum(["held", "released"]),
+    occupancy: z2.enum(["held", "released"]),
     startedAt: timestamp.optional(),
     endedAt: timestamp.optional(),
     interruption: interruptionSchema.optional()
   }).nullable(),
-  scheduling: z.enum(["queued", "dispatching", "admitted", "idle"]),
-  closed: z.boolean(),
-  closeReason: z.string().optional(),
+  scheduling: z2.enum(["queued", "dispatching", "admitted", "idle"]),
+  closed: z2.boolean(),
+  closeReason: z2.string().optional(),
   cancellation: id.optional(),
   pendingResume: commandSchema.shape.intent.optional(),
   /** Derived per viewer; absent on older Hubs. Never grants execution authority. */
-  runnerStopped: z.boolean().optional(),
-  canAbandon: z.boolean().optional(),
+  runnerStopped: z2.boolean().optional(),
+  canAbandon: z2.boolean().optional(),
   historyThrough: sequence,
   expectedHistoryThrough: sequence.optional(),
   createdAt: sequence,
-  checkpoint: z.object({ id, state: z.enum(["pending", "ready"]), checksum: z.string().optional() }).optional()
+  checkpoint: z2.object({ id, state: z2.enum(["pending", "ready"]), checksum: z2.string().optional() }).optional()
 });
-var clientFrameSchema = z.discriminatedUnion("type", [
-  z.strictObject({ type: z.literal("watch"), hubEpoch: id, runIds: z.array(id).max(100) }),
-  z.strictObject({ type: z.literal("watch.ack"), subscriptionId: id, through: sequence }),
-  z.strictObject({ type: z.literal("command.submit"), command: commandSchema }),
-  z.strictObject({ type: z.literal("ping"), nonce: id })
+var clientFrameSchema = z2.discriminatedUnion("type", [
+  z2.strictObject({ type: z2.literal("watch"), hubEpoch: id, runIds: z2.array(id).max(100) }),
+  z2.strictObject({ type: z2.literal("watch.ack"), subscriptionId: id, through: sequence }),
+  z2.strictObject({ type: z2.literal("command.submit"), command: commandSchema }),
+  z2.strictObject({ type: z2.literal("ping"), nonce: id })
 ]);
 function canonicalJson(value) {
   if (value === null || typeof value !== "object") {
@@ -442,76 +490,76 @@ function canonicalJson(value) {
   if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
   return `{${Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(",")}}`;
 }
-var checkpointPathSchema = z.string().min(1).max(4096).refine(
+var checkpointPathSchema = z2.string().min(1).max(4096).refine(
   (path) => !path.startsWith("/") && !path.includes("\\") && path.split("/").every((part) => part !== "" && part !== "." && part !== ".." && part !== ".git")
 );
-var checkpointSchema = z.strictObject({
-  version: z.literal(1),
-  checkpointId: z.string().min(1),
-  orgId: z.string().min(1),
-  phase: z.enum(["parked", "terminal"]),
-  runId: z.string().min(1),
-  sessionId: z.string().min(1),
-  sourceAttemptId: z.string().min(1),
-  executionRevision: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
-  historyProduced: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
-  historyAck: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+var checkpointSchema = z2.strictObject({
+  version: z2.literal(1),
+  checkpointId: z2.string().min(1),
+  orgId: z2.string().min(1),
+  phase: z2.enum(["parked", "terminal"]),
+  runId: z2.string().min(1),
+  sessionId: z2.string().min(1),
+  sourceAttemptId: z2.string().min(1),
+  executionRevision: z2.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+  historyProduced: z2.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+  historyAck: z2.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
   grant: grantSchema,
-  gitHead: z.string().regex(/^[0-9a-f]{40,64}$/),
-  gitBase: z.string().regex(/^[0-9a-f]{40,64}$/).optional(),
-  gitBundle: z.string(),
-  indexPatch: z.string(),
-  files: z.array(
-    z.strictObject({ path: checkpointPathSchema, content: z.string(), executable: z.boolean() })
+  gitHead: z2.string().regex(/^[0-9a-f]{40,64}$/),
+  gitBase: z2.string().regex(/^[0-9a-f]{40,64}$/).optional(),
+  gitBundle: z2.string(),
+  indexPatch: z2.string(),
+  files: z2.array(
+    z2.strictObject({ path: checkpointPathSchema, content: z2.string(), executable: z2.boolean() })
   ).max(1e5),
-  deleted: z.array(checkpointPathSchema).max(1e5),
-  sessionRows: z.array(z.strictObject({ kind: z.string(), id: z.string(), payload: z.string() })),
-  history: z.array(
-    z.strictObject({ seq: z.number().int().positive(), record: historyRecordSchema })
+  deleted: z2.array(checkpointPathSchema).max(1e5),
+  sessionRows: z2.array(z2.strictObject({ kind: z2.string(), id: z2.string(), payload: z2.string() })),
+  history: z2.array(
+    z2.strictObject({ seq: z2.number().int().positive(), record: historyRecordSchema })
   )
 });
 var connectCodeAlphabet = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";
-var connectCodeSchema = z.string().regex(/^[A-HJKMNP-Z2-9]{8}$/);
-var connectCodeRequestSchema = z.strictObject({ hubEpoch: z.string() });
-var connectCodeResponseSchema = z.strictObject({
+var connectCodeSchema = z2.string().regex(/^[A-HJKMNP-Z2-9]{8}$/);
+var connectCodeRequestSchema = z2.strictObject({ hubEpoch: z2.string() });
+var connectCodeResponseSchema = z2.strictObject({
   code: connectCodeSchema,
   expiresAt: sequence
 });
-var connectRedeemRequestSchema = z.strictObject({
-  code: z.string().min(8).max(16),
+var connectRedeemRequestSchema = z2.strictObject({
+  code: z2.string().min(8).max(16),
   installationId: id,
-  hostname: z.string().min(1).max(255),
-  os: z.string().min(1).max(64),
-  softwareVersion: z.string().min(1).max(128)
+  hostname: z2.string().min(1).max(255),
+  os: z2.string().min(1).max(64),
+  softwareVersion: z2.string().min(1).max(128)
 });
-var connectRedeemResponseSchema = z.strictObject({
+var connectRedeemResponseSchema = z2.strictObject({
   orgId: id,
-  hubEpoch: z.string(),
+  hubEpoch: z2.string(),
   runnerId: id,
   installationId: id,
-  name: z.string(),
-  token: z.string().min(32),
+  name: z2.string(),
+  token: z2.string().min(32),
   credentialId: id,
   expiresAt: sequence
 });
-var connectAlreadyConnectedSchema = z.strictObject({
-  error: z.literal("runner_already_connected"),
+var connectAlreadyConnectedSchema = z2.strictObject({
+  error: z2.literal("runner_already_connected"),
   orgId: id,
   runnerId: id,
-  name: z.string()
+  name: z2.string()
 });
-var audienceSchema = z.enum(["personal", "team"]);
-var runnerListEntrySchema = z.object({
+var audienceSchema = z2.enum(["personal", "team"]);
+var runnerListEntrySchema = z2.object({
   id,
-  online: z.number(),
-  capacity: z.number(),
-  managed: z.number(),
-  draining: z.number(),
-  stopped: z.number(),
-  name: z.string().nullable(),
-  connectedBy: z.string().nullable(),
+  online: z2.number(),
+  capacity: z2.number(),
+  managed: z2.number(),
+  draining: z2.number(),
+  stopped: z2.number(),
+  name: z2.string().nullable(),
+  connectedBy: z2.string().nullable(),
   audience: audienceSchema.nullable(),
-  softwareVersion: z.string().nullable(),
+  softwareVersion: z2.string().nullable(),
   /** Milliseconds since the epoch of the last hello or disconnect; null before the first connection. */
   lastSeen: sequence.nullable(),
   /** Absent when the runner has not reported an inventory: unknown, not none. */
@@ -521,115 +569,119 @@ var runnerListEntrySchema = z.object({
    * Runner seen by an admin (who may still Disconnect it), or a Runner a member did not connect. Absent from Hubs
    * older than Audience, like the list's `viewer`, `teamDefault` and `runsGoTo`.
    */
-  readOnly: z.boolean().optional(),
+  readOnly: z2.boolean().optional(),
   /** What the Runner last reported; absent when it never has (an older runner, or one not yet connected). */
   readiness: runnerReadinessSchema.optional(),
   /**
    * True when the Runner reported a version below the Hub's minimum: it is listed as "Update required" and takes no
    * Runs until it is updated (`runnerUpdateCommand`). Absent from Hubs older than Readiness.
    */
-  updateRequired: z.boolean().optional(),
+  updateRequired: z2.boolean().optional(),
   /**
    * True while it is paused as "Needs an owner": the member who connected this Team Runner left the Team, so it
    * takes no Runs until an admin adopts it (`/runners/{id}/adopt`) or Disconnects it. Absent from older Hubs.
    */
-  needsOwner: z.boolean().optional()
+  needsOwner: z2.boolean().optional()
 });
-var teamDefaultSchema = z.discriminatedUnion("kind", [
-  z.strictObject({ kind: z.literal("runner"), runnerId: id }),
-  z.strictObject({ kind: z.literal("profile"), profileId: id })
+var teamDefaultSchema = z2.discriminatedUnion("kind", [
+  z2.strictObject({ kind: z2.literal("runner"), runnerId: id }),
+  z2.strictObject({ kind: z2.literal("profile"), profileId: id })
 ]);
-var teamDefaultRequestSchema = z.strictObject({
-  hubEpoch: z.string(),
+var teamDefaultRequestSchema = z2.strictObject({
+  hubEpoch: z2.string(),
   teamDefault: teamDefaultSchema.nullable()
 });
-var runnerUpdateRequestSchema = z.strictObject({
-  hubEpoch: z.string(),
-  name: z.string().max(100).optional(),
-  capacity: z.number().int().min(1).max(64).optional(),
+var runnerUpdateRequestSchema = z2.strictObject({
+  hubEpoch: z2.string(),
+  name: z2.string().max(100).optional(),
+  capacity: z2.number().int().min(1).max(64).optional(),
   audience: audienceSchema.optional()
 }).refine(
   (update) => update.name !== void 0 || update.capacity !== void 0 || update.audience !== void 0,
   { message: "nothing to update" }
 );
-var runsGoToSchema = z.union([
+var runsGoToSchema = z2.union([
   /** The viewer's own Runner: Personal, or one they connected that was widened to Team (DRI-42). */
-  z.strictObject({ via: z.literal("personal"), runnerId: id }),
-  z.strictObject({ via: z.literal("team_default"), runnerId: id }),
-  z.strictObject({ via: z.literal("team_default"), profileId: id }),
+  z2.strictObject({ via: z2.literal("personal"), runnerId: id }),
+  z2.strictObject({ via: z2.literal("team_default"), runnerId: id }),
+  z2.strictObject({ via: z2.literal("team_default"), profileId: id }),
   /** `runner_needs_owner`: the Team default is a Runner paused because the member who connected it left. */
-  z.strictObject({ via: z.literal("none"), reason: z.enum(["no_runner_available", "runner_needs_owner"]) })
+  z2.strictObject({ via: z2.literal("none"), reason: z2.enum(["no_runner_available", "runner_needs_owner"]) })
 ]);
-var runnerListSchema = z.object({
-  capabilities: z.record(z.string(), z.boolean()).optional(),
-  historyRetentionDays: z.number().int().positive().nullable().optional(),
+var runnerListSchema = z2.object({
+  capabilities: z2.record(z2.string(), z2.boolean()).optional(),
+  historyRetentionDays: z2.number().int().positive().nullable().optional(),
   /** Who the list was filtered for: a member sees their own and Team Runners, an admin every Runner. */
-  viewer: z.object({ userId: z.string(), admin: z.boolean() }).optional(),
+  viewer: z2.object({ userId: z2.string(), admin: z2.boolean() }).optional(),
   teamDefault: teamDefaultSchema.nullable().optional(),
   runsGoTo: runsGoToSchema.optional(),
   /** The lowest Runner version this Hub sends Runs to. Absent from Hubs older than Readiness. */
-  minimumRunnerVersion: z.string().optional(),
-  runners: z.array(runnerListEntrySchema),
-  profiles: z.array(z.object({
-    id: z.string(),
-    label: z.string(),
-    projectDir: z.string(),
-    repositoryRequired: z.boolean().optional(),
+  minimumRunnerVersion: z2.string().optional(),
+  runners: z2.array(runnerListEntrySchema),
+  profiles: z2.array(z2.object({
+    id: z2.string(),
+    label: z2.string(),
+    projectDir: z2.string(),
+    repositoryRequired: z2.boolean().optional(),
     /** Marketplace refs baked into the profile's image; absent when the profile declares none. */
-    workflows: z.array(z.string()).optional(),
-    workflowSources: z.array(z.string()).optional()
+    workflows: z2.array(z2.string()).optional(),
+    workflowSources: z2.array(z2.string()).optional()
   }))
 });
-var runnerDisconnectRequestSchema = z.strictObject({ hubEpoch: z.string() });
+var runnerDisconnectRequestSchema = z2.strictObject({ hubEpoch: z2.string() });
 var hubEpochRequestSchema = runnerDisconnectRequestSchema;
-var runnerDisconnectPreviewSchema = z.object({
+var runnerDisconnectPreviewSchema = z2.object({
   runnerId: id,
-  name: z.string().nullable(),
-  runs: z.array(z.object({
+  name: z2.string().nullable(),
+  runs: z2.array(z2.object({
     runId: id,
-    label: z.string().optional(),
+    label: z2.string().optional(),
     /** Working: executing now. Parked: waiting for a person, Runner released. Queued: not started yet. */
-    state: z.enum(["working", "parked", "queued"])
+    state: z2.enum(["working", "parked", "queued"])
   })),
-  hiddenRuns: z.number().int().nonnegative()
+  hiddenRuns: z2.number().int().nonnegative()
 });
-var runnerDisconnectResponseSchema = z.object({
-  disconnected: z.literal(true),
+var runnerDisconnectResponseSchema = z2.object({
+  disconnected: z2.literal(true),
   /** How many Runs were Stopped with the reason `runner_disconnected`. */
-  stoppedRuns: z.number().int().nonnegative()
+  stoppedRuns: z2.number().int().nonnegative()
 });
 var runnerAdoptRequestSchema = hubEpochRequestSchema;
 var connectStartRequestSchema = connectRedeemRequestSchema.omit({ code: true });
-var connectStartResponseSchema = z.strictObject({
+var connectStartResponseSchema = z2.strictObject({
   /** The machine's secret for polling; never shown. */
-  deviceCode: z.string().min(32).max(160),
+  deviceCode: z2.string().min(32).max(160),
   code: connectCodeSchema,
   expiresAt: sequence,
-  intervalSec: z.number().int().positive(),
+  intervalSec: z2.number().int().positive(),
   /** The web console page that approves `code`. */
-  verificationUrl: z.string().url()
+  verificationUrl: z2.string().url()
 });
-var connectPollRequestSchema = z.strictObject({ deviceCode: z.string().min(32).max(160) });
-var connectPendingResponseSchema = z.strictObject({
-  hostname: z.string(),
-  os: z.string(),
-  softwareVersion: z.string(),
+var connectPollRequestSchema = z2.strictObject({ deviceCode: z2.string().min(32).max(160) });
+var connectPendingResponseSchema = z2.strictObject({
+  hostname: z2.string(),
+  os: z2.string(),
+  softwareVersion: z2.string(),
   requestedAt: sequence,
   expiresAt: sequence
 });
-var connectApproveRequestSchema = z.strictObject({
-  code: z.string().min(8).max(16),
+var connectApproveRequestSchema = z2.strictObject({
+  code: z2.string().min(8).max(16),
   audience: audienceSchema,
-  hubEpoch: z.string().optional()
+  hubEpoch: z2.string().optional()
 });
-var connectDenyRequestSchema = z.strictObject({ code: z.string().min(8).max(16) });
+var connectDenyRequestSchema = z2.strictObject({ code: z2.string().min(8).max(16) });
 export {
+  CALIBRATION_MIN_RUNS,
+  CALIBRATION_WINDOW_DAYS,
   SIZE_CLASS_CAPS,
   SIZE_CLASS_FORECASTS,
   abandonedConversationContinuationCapability,
   attemptCost,
   audienceSchema,
   buildCloseReasonSchema,
+  calibrate,
+  calibrationSchema,
   canonicalJson,
   checkpointPathSchema,
   checkpointSchema,
@@ -654,6 +706,7 @@ export {
   delegationSchema,
   delegationTokenPrefix,
   forecastOfCap,
+  forecastOfClass,
   grantSchema,
   harnessReadinessSchema,
   harnessSchema,
@@ -679,6 +732,8 @@ export {
   runParentIntentSchema,
   runParentSchema,
   runSpecSchema,
+  runUsageCapability,
+  runUsageSchema,
   runViewSchema,
   runnerAdoptRequestSchema,
   runnerDisconnectPreviewSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drisp/protocol",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "description": "Wire contract between a drisp runner and the hub: zod schemas, inferred types, and JSON Schema for the instance-socket frames, Run, Turn, Interruption, and the event stream",
   "repository": {
     "type": "git",

package/schema/v2/checkpoint.json

@@ -357,6 +357,10 @@
             "tokenCap"
           ],
           "additionalProperties": false
+        },
+        "reportUsage": {
+          "type": "boolean",
+          "const": true
         }
       },
       "required": [

package/schema/v2/grant.json

@@ -308,6 +308,10 @@
         "tokenCap"
       ],
       "additionalProperties": false
+    },
+    "reportUsage": {
+      "type": "boolean",
+      "const": true
     }
   },
   "required": [

package/schema/v2/run.json

@@ -112,6 +112,26 @@
       ],
       "additionalProperties": false
     },
+    "usage": {
+      "type": "object",
+      "properties": {
+        "counted": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "cacheRead": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        }
+      },
+      "required": [
+        "counted",
+        "cacheRead"
+      ],
+      "additionalProperties": false
+    },
     "workflow": {
       "type": "object",
       "properties": {

package/schema/v2/runner.json

@@ -720,6 +720,26 @@
                         "additionalProperties": false
                       }
                     ]
+                  },
+                  "usage": {
+                    "type": "object",
+                    "properties": {
+                      "counted": {
+                        "type": "integer",
+                        "minimum": 0,
+                        "maximum": 9007199254740991
+                      },
+                      "cacheRead": {
+                        "type": "integer",
+                        "minimum": 0,
+                        "maximum": 9007199254740991
+                      }
+                    },
+                    "required": [
+                      "counted",
+                      "cacheRead"
+                    ],
+                    "additionalProperties": false
                   }
                 },
                 "required": [
@@ -787,6 +807,26 @@
                       "build_not_approved",
                       "approval_question_missing"
                     ]
+                  },
+                  "usage": {
+                    "type": "object",
+                    "properties": {
+                      "counted": {
+                        "type": "integer",
+                        "minimum": 0,
+                        "maximum": 9007199254740991
+                      },
+                      "cacheRead": {
+                        "type": "integer",
+                        "minimum": 0,
+                        "maximum": 9007199254740991
+                      }
+                    },
+                    "required": [
+                      "counted",
+                      "cacheRead"
+                    ],
+                    "additionalProperties": false
                   }
                 },
                 "required": [
@@ -800,6 +840,43 @@
                 ],
                 "additionalProperties": false
               },
+              {
+                "type": "object",
+                "properties": {
+                  "kind": {
+                    "type": "string",
+                    "const": "run.usage"
+                  },
+                  "runId": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 160
+                  },
+                  "attemptId": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 160
+                  },
+                  "counted": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 9007199254740991
+                  },
+                  "cacheRead": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 9007199254740991
+                  }
+                },
+                "required": [
+                  "kind",
+                  "runId",
+                  "attemptId",
+                  "counted",
+                  "cacheRead"
+                ],
+                "additionalProperties": false
+              },
               {
                 "type": "object",
                 "properties": {