specpi 0.16.0 → 0.17.0

package/extensions/delegation/core.mjs

@@ -1,8 +1,8 @@
 import { randomUUID } from "node:crypto";
 import { createSnapshot } from "./snapshot.mjs";
-import { LIMITS, digest, timeoutLimits, validateOperation } from "./protocol.mjs";
+import { LIMITS, digest, timeoutLimits, budgetLimits, validateOperation } from "./protocol.mjs";
 import { runWorker } from "./worker.mjs";
-import { DelegationError, publicErrorMessage } from "./errors.mjs";
+import { DelegationError, publicErrorMessage, workerFailureMessage } from "./errors.mjs";
 
 const terminal = new Set(["complete", "partial", "needs_context", "failed", "cancelled", "expired", "stale"]);
 const quiet = new Set(["cancelled", "expired", "stale"]);
@@ -21,7 +21,11 @@ export function createDelegationController({
         Object.fromEntries(
             Object.entries(LIMITS).map(([key, maximum]) => {
                 const value = limits[key] ?? maximum;
-                if (!Number.isSafeInteger(value) || value < 1 || value > maximum) {
+                const modelDefault = key === "outputTokens" && value === null;
+                if (
+                    !modelDefault &&
+                    (!Number.isSafeInteger(value) || value < 1 || (maximum !== null && value > maximum))
+                ) {
                     throw new DelegationError("Limits may only lower the fixed delegation ceilings");
                 }
 
@@ -137,6 +141,7 @@ export function createDelegationController({
         !batch.retired &&
         !quiet.has(job.state) &&
         !job.disposition &&
+        !job.limitReason &&
         Date.now() < Math.min(job.deadline, batch.deadline) &&
         (!terminal.has(job.state) || job.followUps < 1);
 
@@ -346,6 +351,7 @@ export function createDelegationController({
                                     batch.calls >= policy.batchCalls ||
                                     totalCalls >= policy.sessionCalls
                                 ) {
+                                    job.limitReason = "model-call allowance";
                                     throw new DelegationError("Delegation model-call allowance exhausted");
                                 }
 
@@ -370,14 +376,16 @@ export function createDelegationController({
                         assertJobLive();
                         checkSources(batch);
                         finish(batch, job, result.status, result);
-                    } catch {
+                    } catch (error) {
                         // Provider errors can contain URLs, credentials, or user content. Do not return them.
                         finish(
                             batch,
                             job,
                             "failed",
                             undefined,
-                            "Worker failed or exhausted a bound; inspect status and use one changed-input follow-up if appropriate.",
+                            job.limitReason
+                                ? `Worker exhausted its ${job.limitReason}. Review /delegate limits; a human can raise /delegate budget while off and start a fresh batch.`
+                                : workerFailureMessage(error),
                         );
                     } finally {
                         job.controller.abort();
@@ -520,6 +528,19 @@ export function createDelegationController({
 
         const { batch, job } = findBoundJob(input);
         if (input.operation === "follow_up") {
+            if (
+                job.limitReason ||
+                job.calls >= policy.jobCalls ||
+                batch.calls >= policy.batchCalls ||
+                totalCalls >= policy.sessionCalls ||
+                job.toolCalls >= policy.toolCalls ||
+                job.toolBytes >= policy.toolBytes
+            ) {
+                throw new DelegationError(
+                    "Follow-up has no usable budget remaining. A human can raise /delegate budget while off, then start a fresh batch.",
+                );
+            }
+
             if (
                 job.settling ||
                 job.followUps >= 1 ||
@@ -685,7 +706,7 @@ export function createDelegationController({
         try {
             entry.value = mutate(input);
             // Spending and final-disposition receipts fit the fixed batch/job ceilings
-            // (at most 4 runs + 8 follow-ups + 8 final dispositions). Never evict them.
+            // (one run and at most two follow-ups/two dispositions per batch). Never evict them.
             if (input.operation === "cancel" || (input.operation === "resolve" && input.decision === "needs_check")) {
                 recentRequests.set(input.requestId, entry);
                 if (recentRequests.size > 128) {
@@ -708,6 +729,16 @@ export function createDelegationController({
         presentation,
         invalidate,
         // Human command only; never exposed through execute() or the model schema.
+        setBudgetMultiplier(multiplier) {
+            const budget = budgetLimits(multiplier);
+            if (enabled) {
+                throw new DelegationError("Turn delegation off before changing its budget: /delegate off");
+            }
+
+            invalidate("budget policy changed");
+            policy = Object.freeze({ ...policy, ...budget });
+            changed();
+        },
         setTimeoutMinutes(minutes) {
             const times = timeoutLimits(minutes);
             if (enabled) {

package/extensions/delegation/errors.mjs

@@ -1,6 +1,70 @@
 /** Only code-owned diagnostics may cross the delegation UI/model boundary. */
 export class DelegationError extends Error {}
 
+const workerStages = new Map(
+    Object.entries({
+        setup: "Worker session setup failed; check Pi provider configuration.",
+        provider: "Worker provider request failed; raw provider details were withheld.",
+        stream: "Worker response stream failed validation or exceeded its retained-response allowance.",
+        context: "Worker request exceeded its context allowance or could not be serialized.",
+        response: "Worker provider response exceeded its retained-response allowance or was invalid.",
+        tool: "Worker source-tool request failed; check the selected source IDs and tool argument limits.",
+        policy: "Worker requested an unavailable tool or changed its inference policy.",
+        lease: "Worker lease was cancelled or expired; check the original deadline and current model/Guard state.",
+        incomplete: "Worker provider returned no complete assistant response.",
+        output: "Worker hit the provider output-token limit before completing its report; narrow the review or reduce thinking effort.",
+        empty: "Worker returned no report text.",
+        json: "Worker report was not valid JSON; the follow-up must request only the required JSON object without Markdown fences.",
+        result: "Worker report failed schema or evidence validation.",
+        size: "Worker report exceeded the final-result byte allowance; request a shorter report.",
+    }),
+);
+const workerDetails = new Set([
+    "Invalid closed delegation object",
+    "Invalid delegation text",
+    "Invalid delegation identifier",
+    "Invalid delegation list",
+    "Invalid delegation integer",
+    "Invalid worker result size or status",
+    "Worker referenced an unknown source",
+    "Worker requirement coverage is invalid",
+    "Worker must cover each requirement exactly once",
+    "Invalid finding confidence",
+    "Observed findings require a source reference",
+    "Worker finding identifiers must be unique",
+    "Source is not selected for this job",
+    "Snapshot read request rejected.",
+    "Snapshot search request rejected.",
+    "Snapshot search scope rejected.",
+    "Snapshot line exceeds response quota.",
+    "Snapshot source changed.",
+    "Snapshot source unavailable or changed.",
+    "Snapshot path binding changed.",
+    "Snapshot closed.",
+]);
+const workerMessages = new WeakMap();
+
+// Retain only fixed diagnostics, never an SDK cause, stack, response, or arbitrary message.
+export function workerFailure(stage, error) {
+    if (workerMessages.has(error)) {
+        return error;
+    }
+
+    const detail =
+        error instanceof DelegationError && workerDetails.has(error.message)
+            ? ` ${error.message.replace(/\.$/u, "")}.`
+            : "";
+    const message = (workerStages.get(stage) ?? "Worker failed; no safe diagnostic was available.") + detail;
+    const failure = new DelegationError(message);
+    workerMessages.set(failure, message);
+
+    return failure;
+}
+
+export function workerFailureMessage(error) {
+    return workerMessages.get(error) ?? "Worker failed; no safe diagnostic was available.";
+}
+
 export function publicErrorMessage(error) {
     return error instanceof DelegationError
         ? error.message

package/extensions/delegation/extension.mjs

@@ -1,10 +1,11 @@
 import { DelegationError, publicErrorMessage } from "./errors.mjs";
 import { randomUUID } from "node:crypto";
 import { createDelegationController } from "./core.mjs";
-import { DEFAULT_TIMEOUT_MINUTES, timeoutLimits } from "./protocol.mjs";
+import { DEFAULT_TIMEOUT_MINUTES, DEFAULT_BUDGET_MULTIPLIER, timeoutLimits, budgetLimits } from "./protocol.mjs";
 import { createLivePanel, createToolRenderers, readableLimits, readableStatus } from "./presentation.mjs";
 
-const USAGE = "Usage: /delegate [on|off|status|limits|timeout [<minutes>|reset]|cancel <batchId>]";
+const USAGE =
+    "Usage: /delegate [on|off|status|limits|budget [<multiplier>|reset]|timeout [<minutes>|reset]|cancel <batchId>]";
 
 const integer = { type: "integer", minimum: 0 };
 const string = { type: "string" };
@@ -58,7 +59,11 @@ export const DELEGATE_SCHEMA = {
                         mode: { type: "string", enum: ["review", "scout"] },
                         question: string,
                         context: string,
-                        sources: strings,
+                        sources: {
+                            ...strings,
+                            description:
+                                "Exact workspace-relative text filenames. Ordinary auth, credential, session and history source names are allowed. Private runtime storage, credential stores and keys are excluded; no directories, globs or absolute paths.",
+                        },
                         requirements: {
                             type: "array",
                             minItems: 1,
@@ -137,7 +142,13 @@ export function createDelegationExtension(
     let timeoutLoaded = !timeoutStore;
     const loadTimeout = () => {
         if (!timeoutLoaded) {
-            controller.setTimeoutMinutes(timeoutStore.load());
+            const minutes = timeoutStore.load();
+            const multiplier = timeoutStore.loadBudget?.();
+            if (multiplier !== undefined) {
+                controller.setBudgetMultiplier(multiplier);
+            }
+
+            controller.setTimeoutMinutes(minutes);
             timeoutLoaded = true;
         }
     };
@@ -400,13 +411,19 @@ export function createDelegationExtension(
         });
         pi.registerCommand("delegate", {
             description:
-                "Control read-only delegation (on at Pi startup), inspect limits, or save timeout <minutes> (1–60; reset: 10)",
+                "Control delegation, inspect limits, or save budget <multiplier> (1–64; default 8) and timeout <minutes> (1–60; default 10)",
             getArgumentCompletions: (prefix) =>
                 [
                     "on",
                     "off",
                     "status",
                     "limits",
+                    "budget",
+                    "budget 8",
+                    "budget 16",
+                    "budget 32",
+                    "budget 64",
+                    "budget reset",
                     "timeout",
                     "timeout 5",
                     "timeout 10",
@@ -428,7 +445,7 @@ export function createDelegationExtension(
                 currentContext = ctx;
                 const [action = "status", id, extra] = args.trim().split(/\s+/u).filter(Boolean);
                 try {
-                    if (extra || (id && !["cancel", "timeout"].includes(action))) {
+                    if (extra || (id && !["cancel", "timeout", "budget"].includes(action))) {
                         throw new DelegationError(USAGE);
                     }
 
@@ -454,7 +471,36 @@ export function createDelegationExtension(
 
                         syncActiveTool(true);
                         ctx.ui.notify(
-                            `Delegation enabled: Pi child sessions for review and scout, ${state.model.provider}/${state.model.id}, thinking ${state.model.thinkingLevel ?? "Pi configured"}. At most 2 workers, 4 batches and 32 SDK inference calls per Pi process; ${state.limits.jobMs / 60_000} minutes per job, ${state.limits.batchMs / 60_000} minutes per batch. Configure with /delegate timeout <minutes> while off (saved across restarts). Workers see only supplied text and selected snapshots. Pi owns configured authentication; temporary parent provider/auth overrides and parent hooks are not inherited. No shell, edits, recursion, automatic retries or compaction. /delegate off cancels workers; SDK requests still settling retain their slots. These limits do not guarantee remote termination or a billing cap.`,
+                            `Delegation enabled: Pi child sessions for review and scout, ${state.model.provider}/${state.model.id}, thinking ${state.model.thinkingLevel ?? "Pi configured"}. At most ${state.limits.concurrency} workers, ${state.limits.sessionBatches} batches and ${state.limits.sessionCalls} SDK inference calls per Pi process; ${state.limits.jobMs / 60_000} minutes per job, ${state.limits.batchMs / 60_000} minutes per batch. Configure /delegate budget and /delegate timeout while off (saved across restarts). Workers see only supplied text and selected snapshots. Pi owns configured authentication; temporary parent provider/auth overrides and parent hooks are not inherited. No shell, edits, recursion, automatic provider retries or compaction. Workers can correct tool arguments and reports within their existing budgets. /delegate off cancels workers; SDK requests still settling retain their slots. These limits do not guarantee remote termination or a billing cap.`,
+                            "info",
+                        );
+                    } else if (action === "budget") {
+                        if (id) {
+                            if (!ctx.hasUI) {
+                                throw new DelegationError("Budget changes require a human interactive command");
+                            }
+
+                            if (requested || pending || controller.status().enabled) {
+                                throw new DelegationError(
+                                    "Turn delegation off before changing its budget: /delegate off",
+                                );
+                            }
+
+                            const multiplier =
+                                id === "reset" ? DEFAULT_BUDGET_MULTIPLIER : /^\d+$/u.test(id) ? Number(id) : NaN;
+                            budgetLimits(multiplier);
+                            if (!timeoutStore?.saveBudget) {
+                                throw new DelegationError("Persistent delegation settings are unavailable");
+                            }
+
+                            timeoutStore.saveBudget(multiplier);
+                            controller.setBudgetMultiplier(multiplier);
+                        } else {
+                            loadTimeout();
+                        }
+
+                        ctx.ui.notify(
+                            `${readableLimits(status())}\n${id ? "Budget saved. " : ""}Use /delegate budget <multiplier> (1–64; default 8) while off. Counts, source-output bytes and model-context bytes scale together; spent usage and deadlines do not reset.`,
                             "info",
                         );
                     } else if (action === "timeout") {

package/extensions/delegation/protocol.mjs

@@ -4,6 +4,25 @@ import { createHash } from "node:crypto";
 export const DEFAULT_TIMEOUT_MINUTES = 10;
 export const MAX_TIMEOUT_MINUTES = 60;
 export const MAX_JOB_MS = MAX_TIMEOUT_MINUTES * 60_000;
+export const DEFAULT_BUDGET_MULTIPLIER = 8;
+export const MAX_BUDGET_MULTIPLIER = 64;
+
+export function budgetLimits(multiplier) {
+    if (!Number.isSafeInteger(multiplier) || multiplier < 1 || multiplier > MAX_BUDGET_MULTIPLIER) {
+        throw new DelegationError(`Delegation budget must be a whole multiplier from 1 to ${MAX_BUDGET_MULTIPLIER}`);
+    }
+
+    return {
+        sessionBatches: 4 * multiplier,
+        sessionCalls: 32 * multiplier,
+        batchCalls: 8 * multiplier,
+        jobCalls: 4 * multiplier,
+        toolBytes: 64 * 1024 * multiplier,
+        toolCalls: 12 * multiplier,
+        contextBytes: 256 * 1024 * multiplier,
+        retainedResponseBytes: 128 * 1024 * multiplier,
+    };
+}
 
 export function timeoutLimits(minutes) {
     if (!Number.isSafeInteger(minutes) || minutes < 1 || minutes > MAX_TIMEOUT_MINUTES) {
@@ -15,18 +34,12 @@ export function timeoutLimits(minutes) {
 
 export const LIMITS = Object.freeze({
     concurrency: 2,
-    sessionBatches: 4,
-    sessionCalls: 32,
     batchJobs: 2,
-    batchCalls: 8,
-    jobCalls: 4,
+    ...budgetLimits(DEFAULT_BUDGET_MULTIPLIER),
     ...timeoutLimits(DEFAULT_TIMEOUT_MINUTES),
-    contextBytes: 256 * 1024,
-    retainedResponseBytes: 256 * 1024,
-    toolBytes: 64 * 1024,
-    toolCalls: 12,
+    packetBytes: 256 * 1024,
     resultBytes: 16 * 1024,
-    outputTokens: 8192,
+    outputTokens: null,
 });
 
 export function bytes(value) {
@@ -162,7 +175,7 @@ function validatePacketShape(packet) {
     if (
         !packet.jobs.length ||
         new Set(packet.jobs.map((job) => job.id)).size !== packet.jobs.length ||
-        bytes(packet) > LIMITS.contextBytes
+        bytes(packet) > LIMITS.packetBytes
     ) {
         throw new DelegationError("Delegation packet exceeds its bound or repeats job identifiers");
     }
@@ -200,7 +213,7 @@ export function validateOperation(input) {
         operations[input.operation],
         operations[input.operation].filter((key) => !optional.includes(key)),
     );
-    if (bytes(input) > LIMITS.contextBytes + 4096) {
+    if (bytes(input) > LIMITS.packetBytes + 4096) {
         throw new DelegationError("Delegation operation exceeds its bound");
     }
 

package/extensions/delegation/provider.mjs

@@ -1,8 +1,9 @@
-import { DelegationError } from "./errors.mjs";
-import { MAX_JOB_MS } from "./protocol.mjs";
+import { DelegationError, workerFailure } from "./errors.mjs";
+import { MAX_JOB_MS, MAX_BUDGET_MULTIPLIER, budgetLimits } from "./protocol.mjs";
 
 const MAX_CONTEXT_BYTES = 256 * 1024;
-const MAX_OUTPUT_TOKENS = 8192;
+const MAX_RUN_CONTEXT_BYTES = budgetLimits(MAX_BUDGET_MULTIPLIER).contextBytes;
+const MAX_RETAINED_RESPONSE_BYTES = budgetLimits(MAX_BUDGET_MULTIPLIER).retainedResponseBytes;
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
 const MODEL_FIELDS = [
     "id",
@@ -35,16 +36,16 @@ export function getPiSessionCompatibilityError(sdk) {
         : undefined;
 }
 
-function bounded(value, maximum = MAX_CONTEXT_BYTES) {
+function bounded(value, maximum = MAX_CONTEXT_BYTES, stage) {
     let serialized;
     try {
         serialized = JSON.stringify(value);
     } catch {
-        throw new DelegationError("Delegation data is not serializable");
+        throw stage ? workerFailure(stage) : new DelegationError("Delegation data is not serializable");
     }
 
     if (typeof serialized !== "string" || Buffer.byteLength(serialized, "utf8") > maximum) {
-        throw new DelegationError("Delegation data exceeds its retained data allowance");
+        throw stage ? workerFailure(stage) : new DelegationError("Delegation data exceeds its retained data allowance");
     }
 
     return serialized;
@@ -306,7 +307,7 @@ export function createNativePiHost(ctx, { id, isCurrent, sdk, thinkingLevel } =
 
     const check = (streaming = false) => {
         if (!current(streaming)) {
-            throw new DelegationError("Delegation parent lease is no longer current");
+            throw workerFailure("lease");
         }
 
         if (
@@ -459,7 +460,7 @@ export function createNativePiHost(ctx, { id, isCurrent, sdk, thinkingLevel } =
                     active.controls.signal.aborted ||
                     Date.now() >= active.controls.deadline
                 ) {
-                    throw new DelegationError("Delegation session was cancelled or expired");
+                    throw workerFailure("lease");
                 }
 
                 active.controls.assertLive(streaming);
@@ -478,7 +479,7 @@ export function createNativePiHost(ctx, { id, isCurrent, sdk, thinkingLevel } =
                 try {
                     assertRun();
                     if (!names.includes(call.toolCall.name)) {
-                        throw new DelegationError("Delegation requested an unavailable tool");
+                        throw workerFailure("policy");
                     }
 
                     const result = await beforeToolCall?.call(session.agent, call, signal);
@@ -499,27 +500,30 @@ export function createNativePiHost(ctx, { id, isCurrent, sdk, thinkingLevel } =
                     if (
                         requestModel !== childModel ||
                         !sameValue(descriptor(requestModel), selected) ||
-                        context.tools?.some((tool) => !names.includes(tool.name)) ||
-                        context.messages.some((message) => message.role === "toolResult" && message.isError)
+                        context.tools?.some((tool) => !names.includes(tool.name))
                     ) {
-                        throw new DelegationError("Delegation inference policy changed");
+                        throw workerFailure("policy");
                     }
 
-                    bounded(context, run.controls.limits.contextBytes);
+                    bounded(context, run.controls.limits.contextBytes, "context");
                     run.controls.admitCall();
                     const requestOptions = {
                         ...options,
                         signal: AbortSignal.any(
                             [options.signal, run.controls.signal, run.controller.signal].filter(Boolean),
                         ),
-                        maxTokens: Math.min(MAX_OUTPUT_TOKENS, childModel.maxTokens, run.controls.limits.outputTokens),
+                        // null uses Pi's normal provider/model output and thinking budget.
+                        maxTokens:
+                            run.controls.limits.outputTokens === null
+                                ? options.maxTokens
+                                : Math.min(childModel.maxTokens, run.controls.limits.outputTokens),
                         maxRetries: 0,
                         timeoutMs: Math.max(1, Math.min(MAX_JOB_MS, run.controls.deadline - Date.now())),
                         onPayload: async (payload, providerModel) => {
                             assertRun();
                             const result = (await options.onPayload?.(payload, providerModel)) ?? payload;
                             assertRun();
-                            bounded(result, run.controls.limits.contextBytes);
+                            bounded(result, run.controls.limits.contextBytes, "context");
 
                             return result;
                         },
@@ -536,7 +540,7 @@ export function createNativePiHost(ctx, { id, isCurrent, sdk, thinkingLevel } =
                         .then(
                             (result) => {
                                 run.controls.onUsage(result?.usage);
-                                bounded(result, run.controls.limits.retainedResponseBytes);
+                                bounded(result, run.controls.limits.retainedResponseBytes, "response");
                                 if (
                                     result?.role !== "assistant" ||
                                     !Array.isArray(result.content) ||
@@ -544,9 +548,7 @@ export function createNativePiHost(ctx, { id, isCurrent, sdk, thinkingLevel } =
                                         (part) => part.type === "toolCall" && !names.includes(part.name),
                                     )
                                 ) {
-                                    throw new DelegationError(
-                                        "Provider returned an invalid response or unavailable tool",
-                                    );
+                                    throw workerFailure("response");
                                 }
 
                                 return result;
@@ -575,7 +577,11 @@ export function createNativePiHost(ctx, { id, isCurrent, sdk, thinkingLevel } =
                             try {
                                 for await (const event of stream) {
                                     assertRun(event.type?.endsWith("_delta") === true);
-                                    inspectEvent(event);
+                                    try {
+                                        inspectEvent(event);
+                                    } catch (error) {
+                                        throw workerFailure("stream", error);
+                                    }
 
                                     yield event;
                                 }
@@ -621,14 +627,15 @@ export function createNativePiHost(ctx, { id, isCurrent, sdk, thinkingLevel } =
                         ["assertLive", "admitCall", "onUsage", "abort"].some(
                             (key) => typeof controls[key] !== "function",
                         ) ||
-                        !Number.isInteger(controls.limits?.outputTokens) ||
-                        controls.limits.outputTokens < 1 ||
-                        controls.limits.outputTokens > MAX_OUTPUT_TOKENS ||
+                        (controls.limits?.outputTokens !== null &&
+                            (!Number.isSafeInteger(controls.limits?.outputTokens) ||
+                                controls.limits.outputTokens < 1)) ||
                         ["contextBytes", "retainedResponseBytes"].some(
                             (key) =>
                                 !Number.isInteger(controls.limits[key]) ||
                                 controls.limits[key] < 1 ||
-                                controls.limits[key] > MAX_CONTEXT_BYTES,
+                                controls.limits[key] >
+                                    (key === "contextBytes" ? MAX_RUN_CONTEXT_BYTES : MAX_RETAINED_RESPONSE_BYTES),
                         )
                     ) {
                         throw new DelegationError("Invalid bounded delegation session run");
@@ -636,13 +643,13 @@ export function createNativePiHost(ctx, { id, isCurrent, sdk, thinkingLevel } =
 
                     const run = { controls, controller: new AbortController(), pending: [], failure: undefined };
                     active = run;
-                    const cancel = () => fail(new DelegationError("Delegation session was cancelled or expired"));
+                    const cancel = () => fail(workerFailure("lease"));
                     controls.signal.addEventListener("abort", cancel, { once: true });
                     const timer = setTimeout(cancel, Math.max(1, Math.min(MAX_JOB_MS, controls.deadline - Date.now())));
                     timer.unref?.();
                     try {
                         assertRun();
-                        bounded(prompt, controls.limits.contextBytes);
+                        bounded(prompt, controls.limits.contextBytes, "context");
                         await session.prompt(prompt, { expandPromptTemplates: false });
                         await Promise.allSettled(run.pending);
                         if (run.failure) {
@@ -656,12 +663,14 @@ export function createNativePiHost(ctx, { id, isCurrent, sdk, thinkingLevel } =
                             !Array.isArray(result.content) ||
                             !["stop", "length"].includes(result.stopReason)
                         ) {
-                            throw new DelegationError("Pi worker session did not return a complete assistant response");
+                            throw workerFailure("incomplete");
                         }
 
-                        bounded(result, controls.limits.retainedResponseBytes);
+                        bounded(result, controls.limits.retainedResponseBytes, "response");
 
                         return result;
+                    } catch (error) {
+                        throw workerFailure("provider", run.failure ?? error);
                     } finally {
                         clearTimeout(timer);
                         controls.signal.removeEventListener("abort", cancel);
@@ -679,7 +688,7 @@ export function createNativePiHost(ctx, { id, isCurrent, sdk, thinkingLevel } =
 
                     released = true;
                     if (active) {
-                        fail(new DelegationError("Delegation session was released"));
+                        fail(workerFailure("lease"));
                     } else {
                         dispose();
                     }

package/extensions/delegation/settings.mjs

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
-import { DEFAULT_TIMEOUT_MINUTES, timeoutLimits } from "./protocol.mjs";
+import { DEFAULT_TIMEOUT_MINUTES, DEFAULT_BUDGET_MULTIPLIER, timeoutLimits, budgetLimits } from "./protocol.mjs";
 import { DelegationError } from "./errors.mjs";
 
 const MAX_SETTINGS_BYTES = 4096;
@@ -94,18 +94,59 @@ export function createTimeoutStore(
         if (
             !settings ||
             settings.schema !== 1 ||
-            Object.keys(settings).length !== 2 ||
+            Object.keys(settings).some((key) => !["schema", "timeoutMinutes", "budgetMultiplier"].includes(key)) ||
             !Object.hasOwn(settings, "timeoutMinutes")
         ) {
             throw new Error("Invalid settings schema");
         }
 
         timeoutLimits(settings.timeoutMinutes);
+        if (Object.hasOwn(settings, "budgetMultiplier")) {
+            budgetLimits(settings.budgetMultiplier);
+        }
+
+        return { content, minutes: settings.timeoutMinutes, budgetMultiplier: settings.budgetMultiplier };
+    };
+
+    const save = (patch) => {
+        const previous = read();
+        const { dir, file } = location();
+        directory(dir, true);
+        if (previous) {
+            atomicWrite(
+                `${file}.bak`,
+                `${JSON.stringify({ sha256: createHash("sha256").update(previous.content).digest("hex"), content: previous.content })}\n`,
+                MAX_BACKUP_BYTES,
+            );
+        }
 
-        return { content, minutes: settings.timeoutMinutes };
+        const settings = {
+            schema: 1,
+            timeoutMinutes: previous?.minutes ?? DEFAULT_TIMEOUT_MINUTES,
+            ...(previous?.budgetMultiplier === undefined ? {} : { budgetMultiplier: previous.budgetMultiplier }),
+            ...patch,
+        };
+        atomicWrite(file, `${JSON.stringify(settings)}\n`);
     };
 
     return {
+        loadBudget() {
+            try {
+                return read()?.budgetMultiplier ?? DEFAULT_BUDGET_MULTIPLIER;
+            } catch {
+                throw new DelegationError(
+                    "Cannot read delegation budget settings; check the owned settings file and restart Pi.",
+                );
+            }
+        },
+        saveBudget(multiplier) {
+            budgetLimits(multiplier);
+            try {
+                save({ budgetMultiplier: multiplier });
+            } catch {
+                throw new DelegationError("Cannot save delegation budget settings; the active budget is unchanged.");
+            }
+        },
         load() {
             try {
                 return read()?.minutes ?? DEFAULT_TIMEOUT_MINUTES;
@@ -118,18 +159,7 @@ export function createTimeoutStore(
         save(minutes) {
             timeoutLimits(minutes);
             try {
-                const previous = read();
-                const { dir, file } = location();
-                directory(dir, true);
-                if (previous) {
-                    atomicWrite(
-                        `${file}.bak`,
-                        `${JSON.stringify({ sha256: createHash("sha256").update(previous.content).digest("hex"), content: previous.content })}\n`,
-                        MAX_BACKUP_BYTES,
-                    );
-                }
-
-                atomicWrite(file, `${JSON.stringify({ schema: 1, timeoutMinutes: minutes })}\n`);
+                save({ timeoutMinutes: minutes });
             } catch {
                 throw new DelegationError(
                     "Cannot save delegation settings. Check <agent-dir>/specpi/delegation/settings.json and its permissions; the active timeout is unchanged.",