@drisp/protocol 0.8.5 → 0.8.7

package/dist/v2.d.ts

@@ -18,14 +18,40 @@ 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
- * declared cap. A closed attempt whose cap is no positive number counts its forecast.
+ * What an attempt declaring `declaredCap` is expected to use: its class's forecast, never more than its own cap (so
+ * the rule stays looser than the cap sum it replaces). A cap that is no positive number counts the `S` forecast.
  */
-declare function attemptCost(attempt: {
+declare function attemptForecast(declaredCap: number): number;
+/**
+ * One attempt of a child: its declared cap, whether it has closed, and the counted tokens (cache reads excluded) its
+ * Runner reported, if any. An older Runner never reports, so its attempts count their forecast.
+ */
+type BudgetAttempt = {
     tokenCap: number;
     closed: boolean;
-}): number;
+    spent?: number;
+};
+/**
+ * What one attempt holds against the budget: a closed attempt (finished, failed, cancelled) what it reported, else its
+ * forecast; a running or queued one the larger of its forecast and what it reported, so a resumed attempt never counts
+ * the same tokens twice and an overrun counts once reported. Never more than its own positive declared cap: a Run
+ * reports a little past its cap before it is stopped, and the rule must stay looser than the cap sum it replaces, so
+ * the Hub never refuses a start the declared-cap rule accepted.
+ */
+declare function attemptCost(attempt: BudgetAttempt): number;
+/**
+ * The budget rule the CLI and the Hub share (root ADR-0011). `used` is the sum over every attempt of every child, a
+ * retry being a new attempt; the next start, forecast at `next`, fits when `used + next` is within the budget. Issues
+ * not yet started never enter it: the app warns of them on the plan sheet (Kit `shortfallNote`) and nothing parks.
+ */
+declare function budgetCheck(input: {
+    tokenBudget: number;
+    attempts: readonly BudgetAttempt[];
+    next: number;
+}): {
+    used: number;
+    fits: boolean;
+};
 /** 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. */
@@ -81,6 +107,8 @@ 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";
+/** Authenticated Orchestrator guidance retains its source in prompts and history. */
+declare const orchestratorGuidanceCapability = "orchestrator_guidance_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
@@ -172,6 +200,9 @@ declare const interruptionSchema: z.ZodObject<{
         waiting: "waiting";
     }>;
     message: z.ZodString;
+    respondent: z.ZodOptional<z.ZodEnum<{
+        orchestrator: "orchestrator";
+    }>>;
     requestId: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 /** The Workflow a Run resolved on its runner: the registry name and, when the Workflow declares one, its version. */
@@ -297,6 +328,9 @@ declare const controlRecordSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             waiting: "waiting";
         }>;
         message: z.ZodString;
+        respondent: z.ZodOptional<z.ZodEnum<{
+            orchestrator: "orchestrator";
+        }>>;
         requestId: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
     occupancy: z.ZodEnum<{
@@ -452,7 +486,7 @@ declare const runSpecSchema: z.ZodObject<{
 declare const runKeySchema: z.ZodString;
 /** A member start's grant to start, limit and stop its own children (root ADR-0008). */
 declare const delegationSchema: z.ZodObject<{
-    maxChildren: z.ZodNumber;
+    maxChildren: z.ZodOptional<z.ZodNumber>;
     tokenBudget: z.ZodNumber;
 }, z.core.$strict>;
 /** A child's parent and declared token cap. Required on a delegated start; the Hub refuses it without `tokenCap`. */
@@ -511,7 +545,7 @@ declare const commandSchema: z.ZodObject<{
         }, z.core.$strict>;
         key: z.ZodOptional<z.ZodString>;
         delegation: z.ZodOptional<z.ZodObject<{
-            maxChildren: z.ZodNumber;
+            maxChildren: z.ZodOptional<z.ZodNumber>;
             tokenBudget: z.ZodNumber;
         }, z.core.$strict>>;
         parent: z.ZodOptional<z.ZodObject<{
@@ -535,8 +569,90 @@ declare const commandSchema: z.ZodObject<{
         kind: z.ZodLiteral<"resume">;
         interruptionId: z.ZodString;
         guidance: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"setBudget">;
+        tokenBudget: z.ZodNumber;
+        resume: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>], "kind">;
 }, z.core.$strict>;
+/** Hub-authored provenance, never accepted on a client-submitted command. */
+declare const deliveredCommandSchema: z.ZodObject<{
+    commandId: z.ZodString;
+    hubEpoch: z.ZodString;
+    runId: z.ZodString;
+    expectedRecordRevision: z.ZodOptional<z.ZodNumber>;
+    intent: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"start">;
+        sessionId: z.ZodString;
+        runnerId: z.ZodOptional<z.ZodString>;
+        computeProfileId: z.ZodOptional<z.ZodString>;
+        scope: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            visibility: z.ZodLiteral<"organization">;
+        }, z.core.$strict>, z.ZodObject<{
+            visibility: z.ZodLiteral<"private">;
+            ownerUserId: z.ZodString;
+        }, z.core.$strict>], "visibility">;
+        spec: z.ZodObject<{
+            prompt: z.ZodString;
+            projectDir: z.ZodString;
+            harness: z.ZodEnum<{
+                "claude-code": "claude-code";
+                codex: "codex";
+            }>;
+            workflow: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                name: z.ZodString;
+                source: z.ZodOptional<z.ZodString>;
+                ref: z.ZodOptional<z.ZodString>;
+                version: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>]>>;
+            repository: z.ZodOptional<z.ZodObject<{
+                ref: z.ZodString;
+                commitSha: z.ZodString;
+                branch: z.ZodString;
+                workingDirectory: z.ZodString;
+                setupCommands: z.ZodArray<z.ZodString>;
+                configRevision: z.ZodNumber;
+                repositoryId: z.ZodNumber;
+                installationId: z.ZodNumber;
+                owner: z.ZodString;
+                name: z.ZodString;
+                bindingId: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+        key: z.ZodOptional<z.ZodString>;
+        delegation: z.ZodOptional<z.ZodObject<{
+            maxChildren: z.ZodOptional<z.ZodNumber>;
+            tokenBudget: z.ZodNumber;
+        }, z.core.$strict>>;
+        parent: z.ZodOptional<z.ZodObject<{
+            runId: z.ZodString;
+            tokenCap: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"cancel">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"abandon">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"steer">;
+        text: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"answer">;
+        interruptionId: z.ZodString;
+        expectedInterruptionRevision: z.ZodNumber;
+        requestId: z.ZodOptional<z.ZodString>;
+        answer: z.ZodJSONSchema;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"resume">;
+        interruptionId: z.ZodString;
+        guidance: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"setBudget">;
+        tokenBudget: z.ZodNumber;
+        resume: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>], "kind">;
+    orchestratorRunId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type DeliveredCommand = z.infer<typeof deliveredCommandSchema>;
 declare const grantSchema: z.ZodObject<{
     commandId: z.ZodString;
     hubEpoch: z.ZodString;
@@ -581,6 +697,7 @@ declare const grantSchema: z.ZodObject<{
         }, z.core.$strict>>;
     }, z.core.$strict>;
     continuation: z.ZodOptional<z.ZodJSONSchema>;
+    orchestratorRunId: z.ZodOptional<z.ZodString>;
     previousRun: z.ZodOptional<z.ZodObject<{
         runId: z.ZodString;
         executionRevision: z.ZodNumber;
@@ -730,6 +847,9 @@ declare const runnerFrameSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 waiting: "waiting";
             }>;
             message: z.ZodString;
+            respondent: z.ZodOptional<z.ZodEnum<{
+                orchestrator: "orchestrator";
+            }>>;
             requestId: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>;
         occupancy: z.ZodEnum<{
@@ -861,7 +981,7 @@ declare const runViewSchema: z.ZodObject<{
         tokenCap: z.ZodNumber;
     }, z.core.$strict>>;
     delegation: z.ZodOptional<z.ZodObject<{
-        maxChildren: z.ZodNumber;
+        maxChildren: z.ZodOptional<z.ZodNumber>;
         tokenBudget: z.ZodNumber;
     }, z.core.$strip>>;
     usage: z.ZodOptional<z.ZodObject<{
@@ -899,6 +1019,9 @@ declare const runViewSchema: z.ZodObject<{
                 waiting: "waiting";
             }>;
             message: z.ZodString;
+            respondent: z.ZodOptional<z.ZodEnum<{
+                orchestrator: "orchestrator";
+            }>>;
             requestId: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
     }, z.core.$strip>>;
@@ -951,7 +1074,7 @@ declare const runViewSchema: z.ZodObject<{
         }, z.core.$strict>;
         key: z.ZodOptional<z.ZodString>;
         delegation: z.ZodOptional<z.ZodObject<{
-            maxChildren: z.ZodNumber;
+            maxChildren: z.ZodOptional<z.ZodNumber>;
             tokenBudget: z.ZodNumber;
         }, z.core.$strict>>;
         parent: z.ZodOptional<z.ZodObject<{
@@ -975,6 +1098,10 @@ declare const runViewSchema: z.ZodObject<{
         kind: z.ZodLiteral<"resume">;
         interruptionId: z.ZodString;
         guidance: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"setBudget">;
+        tokenBudget: z.ZodNumber;
+        resume: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>], "kind">>;
     runnerStopped: z.ZodOptional<z.ZodBoolean>;
     canAbandon: z.ZodOptional<z.ZodBoolean>;
@@ -1046,7 +1173,7 @@ declare const clientFrameSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             }, z.core.$strict>;
             key: z.ZodOptional<z.ZodString>;
             delegation: z.ZodOptional<z.ZodObject<{
-                maxChildren: z.ZodNumber;
+                maxChildren: z.ZodOptional<z.ZodNumber>;
                 tokenBudget: z.ZodNumber;
             }, z.core.$strict>>;
             parent: z.ZodOptional<z.ZodObject<{
@@ -1070,6 +1197,10 @@ declare const clientFrameSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             kind: z.ZodLiteral<"resume">;
             interruptionId: z.ZodString;
             guidance: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"setBudget">;
+            tokenBudget: z.ZodNumber;
+            resume: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>], "kind">;
     }, z.core.$strict>;
 }, z.core.$strict>, z.ZodObject<{
@@ -1137,6 +1268,7 @@ declare const checkpointSchema: z.ZodObject<{
             }, z.core.$strict>>;
         }, z.core.$strict>;
         continuation: z.ZodOptional<z.ZodJSONSchema>;
+        orchestratorRunId: z.ZodOptional<z.ZodString>;
         previousRun: z.ZodOptional<z.ZodObject<{
             runId: z.ZodString;
             executionRevision: z.ZodNumber;
@@ -1516,4 +1648,4 @@ type ConnectPendingResponse = z.infer<typeof connectPendingResponseSchema>;
 type TeamDefault = z.infer<typeof teamDefaultSchema>;
 type RunsGoTo = z.infer<typeof runsGoToSchema>;
 
-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 };
+export { type Audience, type BudgetAttempt, 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 DeliveredCommand, 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, attemptForecast, audienceSchema, budgetCheck, 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, deliveredCommandSchema, forecastOfCap, forecastOfClass, grantSchema, harnessReadinessSchema, harnessSchema, historyRecordSchema, hubEpochRequestSchema, installReference, installedWorkflowsSchema, interruptionSchema, orchestratorGuidanceCapability, 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

@@ -67,10 +67,18 @@ function classOfCap(declaredCap) {
 function forecastOfCap(declaredCap) {
   return SIZE_CLASS_FORECASTS[classOfCap(declaredCap)];
 }
+function attemptForecast(declaredCap) {
+  const forecast = forecastOfCap(declaredCap);
+  return declaredCap > 0 ? Math.min(declaredCap, forecast) : forecast;
+}
 function attemptCost(attempt) {
-  if (!attempt.closed) return attempt.tokenCap;
-  const forecast = forecastOfCap(attempt.tokenCap);
-  return attempt.tokenCap > 0 ? Math.min(attempt.tokenCap, forecast) : forecast;
+  const forecast = attemptForecast(attempt.tokenCap);
+  const cost = attempt.closed ? attempt.spent ?? forecast : Math.max(forecast, attempt.spent ?? 0);
+  return attempt.tokenCap > 0 ? Math.min(attempt.tokenCap, cost) : cost;
+}
+function budgetCheck(input) {
+  const used = input.attempts.reduce((sum, attempt) => sum + attemptCost(attempt), 0);
+  return { used, fits: used + input.next <= input.tokenBudget };
 }
 var CALIBRATION_MIN_RUNS = 10;
 var CALIBRATION_WINDOW_DAYS = 90;
@@ -109,6 +117,7 @@ var abandonedConversationContinuationCapability = "abandoned_conversation_contin
 var repositoryAccessCapability = "repository_checkout_v1";
 var workflowInstallCapability = "workflow_install_v1";
 var runDelegationCapability = "run_delegation_v1";
+var orchestratorGuidanceCapability = "orchestrator_guidance_v1";
 var runUsageCapability = "run_usage_v1";
 var delegationTokenPrefix = "drisp_dlg_";
 var runArtifactNameSchema = z2.string().regex(/^[a-z][a-z0-9_]{0,63}$/);
@@ -154,6 +163,8 @@ var interruptionSchema = z2.strictObject({
   /** `waiting` (root ADR-0008) is non-human: a Run parked until one of its children closes or parks. */
   kind: z2.enum(["permission", "question", "guidance", "recovery", "waiting"]),
   message: z2.string().max(16384),
+  /** Explicit technical question for a parent; absent always reserves the answer to a member. */
+  respondent: z2.enum(["orchestrator"]).optional(),
   requestId: id.optional()
 });
 var workflowIdentitySchema = z2.strictObject({
@@ -307,7 +318,8 @@ var runSpecSchema = z2.strictObject({
 });
 var runKeySchema = z2.string().min(1).max(160);
 var delegationSchema = z2.strictObject({
-  maxChildren: z2.number().int().min(1).max(8),
+  // Omitted: follow the Runner capacity. An explicit value is a per-Build ceiling.
+  maxChildren: z2.number().int().min(1).max(64).optional(),
   tokenBudget: z2.number().int().positive().max(Number.MAX_SAFE_INTEGER)
 });
 var tokenCapSchema = z2.number().int().positive().max(Number.MAX_SAFE_INTEGER);
@@ -350,9 +362,20 @@ var commandSchema = z2.strictObject({
       kind: z2.literal("resume"),
       interruptionId: id,
       guidance: z2.string().max(131072).optional()
+    }),
+    /**
+     * A member rewrites an Orchestrator's `delegation.tokenBudget` (root ADR-0011), never below what its children
+     * used. With `resume`, a parked Orchestrator with no live child is resumed when the value is strictly greater.
+     * Hub-only: never delivered to a Runner.
+     */
+    z2.strictObject({
+      kind: z2.literal("setBudget"),
+      tokenBudget: delegationSchema.shape.tokenBudget,
+      resume: z2.boolean().optional()
     })
   ])
 });
+var deliveredCommandSchema = commandSchema.extend({ orchestratorRunId: id.optional() });
 var grantSchema = z2.strictObject({
   commandId: id,
   hubEpoch: id,
@@ -368,6 +391,8 @@ var grantSchema = z2.strictObject({
   purpose: z2.enum(["start", "resume"]),
   spec: runSpecSchema,
   continuation: z2.json().optional(),
+  /** Authenticated source of a delegated continuation; absence retains member semantics. */
+  orchestratorRunId: id.optional(),
   /** A new Run in a durable conversation; never resumes the predecessor's lifecycle. */
   previousRun: z2.strictObject({
     runId: id,
@@ -448,7 +473,11 @@ var runViewSchema = z2.object({
    * 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(),
+  delegation: z2.object({
+    ...delegationSchema.shape,
+    // A resolved Runner default may exceed the explicit settings ceiling on configured Runners.
+    maxChildren: z2.number().int().positive().max(Number.MAX_SAFE_INTEGER).optional()
+  }).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. */
@@ -678,7 +707,9 @@ export {
   SIZE_CLASS_FORECASTS,
   abandonedConversationContinuationCapability,
   attemptCost,
+  attemptForecast,
   audienceSchema,
+  budgetCheck,
   buildCloseReasonSchema,
   calibrate,
   calibrationSchema,
@@ -705,6 +736,7 @@ export {
   conversationContinuationCapability,
   delegationSchema,
   delegationTokenPrefix,
+  deliveredCommandSchema,
   forecastOfCap,
   forecastOfClass,
   grantSchema,
@@ -715,6 +747,7 @@ export {
   installReference,
   installedWorkflowsSchema,
   interruptionSchema,
+  orchestratorGuidanceCapability,
   permissionAnswerSchema,
   protocolVersion,
   readableHistory,

package/package.json

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

@@ -265,6 +265,11 @@
         "continuation": {
           "$ref": "#/$defs/__schema0"
         },
+        "orchestratorRunId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 160
+        },
         "previousRun": {
           "type": "object",
           "properties": {

package/schema/v2/client.json

@@ -305,7 +305,7 @@
                         "maxChildren": {
                           "type": "integer",
                           "minimum": 1,
-                          "maximum": 8
+                          "maximum": 64
                         },
                         "tokenBudget": {
                           "type": "integer",
@@ -314,7 +314,6 @@
                         }
                       },
                       "required": [
-                        "maxChildren",
                         "tokenBudget"
                       ],
                       "additionalProperties": false
@@ -448,6 +447,28 @@
                     "interruptionId"
                   ],
                   "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "kind": {
+                      "type": "string",
+                      "const": "setBudget"
+                    },
+                    "tokenBudget": {
+                      "type": "integer",
+                      "exclusiveMinimum": 0,
+                      "maximum": 9007199254740991
+                    },
+                    "resume": {
+                      "type": "boolean"
+                    }
+                  },
+                  "required": [
+                    "kind",
+                    "tokenBudget"
+                  ],
+                  "additionalProperties": false
                 }
               ]
             }

package/schema/v2/command.json

@@ -242,7 +242,7 @@
                 "maxChildren": {
                   "type": "integer",
                   "minimum": 1,
-                  "maximum": 8
+                  "maximum": 64
                 },
                 "tokenBudget": {
                   "type": "integer",
@@ -251,7 +251,6 @@
                 }
               },
               "required": [
-                "maxChildren",
                 "tokenBudget"
               ],
               "additionalProperties": false
@@ -385,6 +384,28 @@
             "interruptionId"
           ],
           "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "type": "string",
+              "const": "setBudget"
+            },
+            "tokenBudget": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991
+            },
+            "resume": {
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "kind",
+            "tokenBudget"
+          ],
+          "additionalProperties": false
         }
       ]
     }

package/schema/v2/deliveredCommand.json

@@ -0,0 +1,458 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "commandId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 160
+    },
+    "hubEpoch": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 160
+    },
+    "runId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 160
+    },
+    "expectedRecordRevision": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "intent": {
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "type": "string",
+              "const": "start"
+            },
+            "sessionId": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 160
+            },
+            "runnerId": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 160
+            },
+            "computeProfileId": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 160
+            },
+            "scope": {
+              "oneOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "visibility": {
+                      "type": "string",
+                      "const": "organization"
+                    }
+                  },
+                  "required": [
+                    "visibility"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "visibility": {
+                      "type": "string",
+                      "const": "private"
+                    },
+                    "ownerUserId": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 160
+                    }
+                  },
+                  "required": [
+                    "visibility",
+                    "ownerUserId"
+                  ],
+                  "additionalProperties": false
+                }
+              ]
+            },
+            "spec": {
+              "type": "object",
+              "properties": {
+                "prompt": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 131072
+                },
+                "projectDir": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 4096
+                },
+                "harness": {
+                  "type": "string",
+                  "enum": [
+                    "claude-code",
+                    "codex"
+                  ]
+                },
+                "workflow": {
+                  "anyOf": [
+                    {
+                      "type": "string",
+                      "maxLength": 512
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "name": {
+                          "type": "string",
+                          "minLength": 1,
+                          "maxLength": 128,
+                          "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$"
+                        },
+                        "source": {
+                          "type": "string",
+                          "maxLength": 201,
+                          "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*\\/[A-Za-z0-9][A-Za-z0-9_.-]*$"
+                        },
+                        "ref": {
+                          "type": "string",
+                          "minLength": 1,
+                          "maxLength": 512
+                        },
+                        "version": {
+                          "type": "string",
+                          "minLength": 1,
+                          "maxLength": 128,
+                          "pattern": "^\\d[A-Za-z0-9_.+-]*$"
+                        }
+                      },
+                      "required": [
+                        "name"
+                      ],
+                      "additionalProperties": false
+                    }
+                  ]
+                },
+                "repository": {
+                  "type": "object",
+                  "properties": {
+                    "bindingId": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 160
+                    },
+                    "repositoryId": {
+                      "type": "integer",
+                      "exclusiveMinimum": 0,
+                      "maximum": 9007199254740991
+                    },
+                    "installationId": {
+                      "type": "integer",
+                      "exclusiveMinimum": 0,
+                      "maximum": 9007199254740991
+                    },
+                    "owner": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 100,
+                      "pattern": "^[a-zA-Z0-9][a-zA-Z0-9-]*$"
+                    },
+                    "name": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 100,
+                      "pattern": "^(?!\\.{1,2}$)[a-zA-Z0-9_.-]+$"
+                    },
+                    "ref": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 512,
+                      "pattern": "^(?![-/])(?!.*\\.\\.)(?!.*@\\{)(?!.*(?:^|\\/)\\.)(?!.*\\.lock(?:\\/|$))(?!.*\\/\\/)[^\\x00-\\x20\\x7f~^:?*\\[\\\\]+(?<![/.])$"
+                    },
+                    "commitSha": {
+                      "type": "string",
+                      "pattern": "^[0-9a-f]{40}$"
+                    },
+                    "branch": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 512,
+                      "pattern": "^(?![-/])(?!.*\\.\\.)(?!.*@\\{)(?!.*(?:^|\\/)\\.)(?!.*\\.lock(?:\\/|$))(?!.*\\/\\/)[^\\x00-\\x20\\x7f~^:?*\\[\\\\]+(?<![/.])$"
+                    },
+                    "workingDirectory": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 1024,
+                      "pattern": "^(?:\\.|(?!\\/)(?!.*(?:^|\\/)\\.\\.?(?:\\/|$))(?!.*(?:^|\\/)\\.git(?:\\/|$))[^\\x00-\\x1f\\x7f\\\\:]+(?<!\\/))$"
+                    },
+                    "setupCommands": {
+                      "maxItems": 16,
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 8192
+                      }
+                    },
+                    "configRevision": {
+                      "type": "integer",
+                      "minimum": 0,
+                      "maximum": 9007199254740991
+                    }
+                  },
+                  "required": [
+                    "bindingId",
+                    "repositoryId",
+                    "installationId",
+                    "owner",
+                    "name",
+                    "ref",
+                    "commitSha",
+                    "branch",
+                    "workingDirectory",
+                    "setupCommands",
+                    "configRevision"
+                  ],
+                  "additionalProperties": false
+                }
+              },
+              "required": [
+                "prompt",
+                "projectDir",
+                "harness"
+              ],
+              "additionalProperties": false
+            },
+            "key": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 160
+            },
+            "delegation": {
+              "type": "object",
+              "properties": {
+                "maxChildren": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 64
+                },
+                "tokenBudget": {
+                  "type": "integer",
+                  "exclusiveMinimum": 0,
+                  "maximum": 9007199254740991
+                }
+              },
+              "required": [
+                "tokenBudget"
+              ],
+              "additionalProperties": false
+            },
+            "parent": {
+              "type": "object",
+              "properties": {
+                "runId": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 160
+                },
+                "tokenCap": {
+                  "type": "integer",
+                  "exclusiveMinimum": 0,
+                  "maximum": 9007199254740991
+                }
+              },
+              "required": [
+                "runId"
+              ],
+              "additionalProperties": false
+            }
+          },
+          "required": [
+            "kind",
+            "sessionId",
+            "scope",
+            "spec"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "type": "string",
+              "const": "cancel"
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "type": "string",
+              "const": "abandon"
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "type": "string",
+              "const": "steer"
+            },
+            "text": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 131072
+            }
+          },
+          "required": [
+            "kind",
+            "text"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "type": "string",
+              "const": "answer"
+            },
+            "interruptionId": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 160
+            },
+            "expectedInterruptionRevision": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 9007199254740991
+            },
+            "requestId": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 160
+            },
+            "answer": {
+              "$ref": "#/$defs/__schema0"
+            }
+          },
+          "required": [
+            "kind",
+            "interruptionId",
+            "expectedInterruptionRevision",
+            "answer"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "type": "string",
+              "const": "resume"
+            },
+            "interruptionId": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 160
+            },
+            "guidance": {
+              "type": "string",
+              "maxLength": 131072
+            }
+          },
+          "required": [
+            "kind",
+            "interruptionId"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "type": "string",
+              "const": "setBudget"
+            },
+            "tokenBudget": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991
+            },
+            "resume": {
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "kind",
+            "tokenBudget"
+          ],
+          "additionalProperties": false
+        }
+      ]
+    },
+    "orchestratorRunId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 160
+    }
+  },
+  "required": [
+    "commandId",
+    "hubEpoch",
+    "runId",
+    "intent"
+  ],
+  "additionalProperties": false,
+  "$defs": {
+    "__schema0": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "number"
+        },
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        },
+        {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/__schema0"
+          }
+        },
+        {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {
+            "$ref": "#/$defs/__schema0"
+          }
+        }
+      ]
+    }
+  }
+}

package/schema/v2/grant.json

@@ -216,6 +216,11 @@
     "continuation": {
       "$ref": "#/$defs/__schema0"
     },
+    "orchestratorRunId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 160
+    },
     "previousRun": {
       "type": "object",
       "properties": {

package/schema/v2/run.json

@@ -97,8 +97,8 @@
       "properties": {
         "maxChildren": {
           "type": "integer",
-          "minimum": 1,
-          "maximum": 8
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991
         },
         "tokenBudget": {
           "type": "integer",
@@ -107,7 +107,6 @@
         }
       },
       "required": [
-        "maxChildren",
         "tokenBudget"
       ],
       "additionalProperties": false
@@ -220,6 +219,12 @@
                   "type": "string",
                   "maxLength": 16384
                 },
+                "respondent": {
+                  "type": "string",
+                  "enum": [
+                    "orchestrator"
+                  ]
+                },
                 "requestId": {
                   "type": "string",
                   "minLength": 1,
@@ -488,7 +493,7 @@
                 "maxChildren": {
                   "type": "integer",
                   "minimum": 1,
-                  "maximum": 8
+                  "maximum": 64
                 },
                 "tokenBudget": {
                   "type": "integer",
@@ -497,7 +502,6 @@
                 }
               },
               "required": [
-                "maxChildren",
                 "tokenBudget"
               ],
               "additionalProperties": false
@@ -631,6 +635,28 @@
             "interruptionId"
           ],
           "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "type": "string",
+              "const": "setBudget"
+            },
+            "tokenBudget": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991
+            },
+            "resume": {
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "kind",
+            "tokenBudget"
+          ],
+          "additionalProperties": false
         }
       ]
     },

package/schema/v2/runner.json

@@ -622,6 +622,12 @@
                         "type": "string",
                         "maxLength": 16384
                       },
+                      "respondent": {
+                        "type": "string",
+                        "enum": [
+                          "orchestrator"
+                        ]
+                      },
                       "requestId": {
                         "type": "string",
                         "minLength": 1,