@drisp/protocol 0.8.2 → 0.8.4

package/dist/v2.d.ts

@@ -15,6 +15,8 @@ declare const SIZE_CLASS_CAPS: Readonly<Record<SizeClass, number>>;
 declare const SIZE_CLASS_FORECASTS: Readonly<Record<SizeClass, number>>;
 /** The smallest class whose cap is at least the declared one; above the largest cap is `L`. A cap that is no number reads as `S`. */
 declare function classOfCap(declaredCap: number): SizeClass;
+/** What a Run declaring `declaredCap` is expected to use: its class's forecast. */
+declare function forecastOfCap(declaredCap: number): number;
 /**
  * What one attempt holds against the budget: a closed attempt (finished, failed, cancelled) its forecast, never more
  * than its own declared cap (so the rule stays looser than the cap sum it replaces); a running or queued one still its
@@ -27,7 +29,7 @@ declare function attemptCost(attempt: {
 
 declare const protocolVersion: {
     readonly major: 2;
-    readonly minor: 2;
+    readonly minor: 3;
 };
 declare const conversationContinuationCapability = "conversation_continuation";
 declare const abandonedConversationContinuationCapability = "abandoned_conversation_continuation";
@@ -39,6 +41,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. */
@@ -166,6 +174,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<{
@@ -225,6 +242,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;
@@ -261,6 +282,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";
@@ -279,6 +304,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;
@@ -529,6 +560,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;
@@ -643,6 +675,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;
@@ -679,6 +715,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";
@@ -697,6 +737,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;
@@ -777,6 +823,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;
@@ -1066,6 +1116,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>;
@@ -1425,4 +1476,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, 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, 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 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, 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, 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

@@ -63,19 +63,23 @@ function classOfCap(declaredCap) {
   if (declaredCap <= SIZE_CLASS_CAPS.M) return "M";
   return "L";
 }
+function forecastOfCap(declaredCap) {
+  return SIZE_CLASS_FORECASTS[classOfCap(declaredCap)];
+}
 function attemptCost(attempt) {
   if (!attempt.closed) return attempt.tokenCap;
-  const forecast = SIZE_CLASS_FORECASTS[classOfCap(attempt.tokenCap)];
+  const forecast = forecastOfCap(attempt.tokenCap);
   return attempt.tokenCap > 0 ? Math.min(attempt.tokenCap, forecast) : forecast;
 }
 
 // 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 runArtifactMaxBytes = 64 * 1024;
@@ -155,6 +159,8 @@ var factIdentity = {
   executionRevision: positive,
   emittedAt: timestamp
 };
+var runUsageSchema = z.strictObject({ counted: sequence, cacheRead: sequence });
+var reportedUsage = { usage: runUsageSchema.optional() };
 var controlRecordSchema = z.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 }),
@@ -185,7 +191,8 @@ var controlRecordSchema = z.discriminatedUnion("kind", [
       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) })
-    ])
+    ]),
+    ...reportedUsage
   }),
   z.strictObject({
     kind: z.literal("run.finished"),
@@ -198,8 +205,14 @@ var controlRecordSchema = z.discriminatedUnion("kind", [
      * 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
   }),
+  /**
+   * 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.
+   */
+  z.strictObject({ kind: z.literal("run.usage"), runId: id, attemptId: id, ...runUsageSchema.shape }),
   z.strictObject({ kind: z.literal("command.applied"), runId: id, attemptId: id, commandId: id }),
   z.strictObject({
     kind: z.literal("command.rejected"),
@@ -338,7 +351,9 @@ var grantSchema = z.strictObject({
   /** 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(),
   /** 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: z.literal(true).optional()
 });
 var historyRecordSchema = z.strictObject({
   eventId: id,
@@ -399,7 +414,13 @@ var runViewSchema = z.object({
   label: z.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: z.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({
@@ -650,6 +671,7 @@ export {
   conversationContinuationCapability,
   delegationSchema,
   delegationTokenPrefix,
+  forecastOfCap,
   grantSchema,
   harnessReadinessSchema,
   harnessSchema,
@@ -675,6 +697,8 @@ export {
   runParentIntentSchema,
   runParentSchema,
   runSpecSchema,
+  runUsageCapability,
+  runUsageSchema,
   runViewSchema,
   runnerAdoptRequestSchema,
   runnerDisconnectPreviewSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drisp/protocol",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "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": {