pi-subagents 0.69.0 → 0.70.0

package/src/runs/shared/task-intent.js

@@ -0,0 +1,213 @@
+/**
+ * Shared task mutation-intent classifier.
+ *
+ * Single authority for reading a task's wording, answering two different
+ * questions from one prohibition analysis:
+ *
+ * - `classifyTaskMutationIntent` / `expectsImplementationMutation`: does the
+ *   task REQUIRE file changes? Consumed by the completion mutation guard,
+ *   which blocks completion, so its vocabulary is deliberately narrow.
+ *   Verbs inside filenames and path-like tokens do not count.
+ * - `taskMayMutate`: COULD the task plausibly change files? Consumed by
+ *   acceptance level inference, which only raises evidence gates, so its
+ *   vocabulary is deliberately broad (any bare write verb).
+ *
+ * Explicit read-only wording ("do not modify", "review only") is a task-level
+ * intent only when no write imperative survives outside those phrases. A task
+ * like "Do not modify tests; implement the fix" is an implementation task with
+ * a scoped constraint, not a read-only task.
+ */
+const REVIEW_ONLY_PATTERNS = [
+    /\b(?:review|read)[- ]only\b/i,
+    /\bno\s+(?:source\s+)?edits?\b/i,
+    /\bwithout\s+edits?\b/i,
+    /\bsuggest fixes only\b/i,
+    /\bonly return findings\b/i,
+    /\breturn findings only\b/i,
+];
+const NO_EDIT_BOUNDARY_ASSERTION_PATTERN = /\bno\s+(?:source\s+)?edits?\s*,\s*(?:commits?|pushes?|merges?|installs?|changes?|writes?)\b/i;
+const REVIEWER_REQUIRED_EDIT_PATTERNS = [
+    /\bmust\s+(?:edit|modify|change|fix|patch|apply|implement)\b/i,
+    /\brequired\s+to\s+(?:edit|modify|change|fix|patch|apply|implement)\b/i,
+    /(?:^|[.!?:;,\n]\s*)implement\s+(?:the\s+)?(?:approved|requested|specified|file|code|source|fix(?:es)?|changes?)\b/i,
+    /\bregardless\s+of\s+findings\b/i,
+    /\balways\s+(?:edit|modify|change|fix|patch|apply|implement)\b/i,
+    /\bapply\s+(?:the\s+)?fix(?:es)?\s+directly\b/i,
+    /\bmake\s+(?:the\s+)?code\s+changes\b/i,
+];
+// The prohibition's object ends at punctuation, a serialized line separator,
+// or a coordinating word (but/and/then), so a follow-on clause like "but
+// implement the fix" stays in the text for write-intent testing instead of
+// being swallowed as the object.
+// Accept serialized line separators too: workflow prompts can carry literal
+// `\\n`/`\\r\\n` between clauses instead of decoded newlines.
+const NO_EDIT_PROHIBITION_PATTERN = /(?:\b|\\(?:r\\n|n))(?:do not|don't|must not)\s+(?:edit|modify|write(?:\s+to)?|touch|change|implement)\b((?:(?!\b(?:but|and|then)\b|\\(?:r\\n|n))[^.;,:!?\n–—-])*)/gi;
+const COORDINATED_NO_EDIT_PROHIBITION_PATTERN = /(?:\b|\\(?:r\\n|n))(?:do not|don't|must not)\s+((?=(?:(?!\\(?:r\\n|n))[^.;:!?\n–—-])*\b(?:and|or)\s+(?:edit|modify|write(?:\s+to)?|touch|change)\b)(?:(?!\\(?:r\\n|n))[^.;:!?\n–—-])*?\b(?:and|or)\s+(?:edit|modify|write(?:\s+to)?|touch|change)\b(?:(?!\b(?:but|and|then)\b|\\(?:r\\n|n))[^.;,:!?\n–—-])*)/gi;
+/** Objects of a no-edit prohibition that mean "the codebase in general" rather than a named scope. */
+const GENERIC_PROHIBITION_OBJECT = /^\s*(?:(?:any|all|the|these|those|your|our|existing|project|product|source|sources|config|configs|repo|repository)[\s/,-]*)*(?:files?|code|codebase|sources?|anything|repo(?:sitory)?)?\s*$/i;
+const SCOPED_PROHIBITION_CONTINUATION = /^(?:\\(?:r\\n|n)|\r?\n)\s*(?:in|inside|under|within|outside|except|other\s+than|besides)\b/i;
+const OUTPUT_INSTRUCTION_CONTINUATION = /^(?:\\(?:r\\n|n)|\r?\n)\s*(?:in|inside|within)\s+(?:(?:(?:your|the)\s+)(?:final\s+)?|final\s+)(?:output|response|report|answer|reply|message|summary|findings?|analysis|recommendations?)(?:\s*\/\s*(?:output|response|report|answer|reply|message|summary|findings?|analysis|recommendations?))*\b(?![\\/])/i;
+function hasScopedProhibitionContinuation(text) {
+    return SCOPED_PROHIBITION_CONTINUATION.test(text) && !OUTPUT_INSTRUCTION_CONTINUATION.test(text);
+}
+const SCOPED_NO_EDIT_CONSTRAINT_PATTERNS = [
+    /\bdo not edit files?\s+outside\b/i,
+    /\bdo not edit\s+outside\b/i,
+    /\bdo not edit\s+unrelated files?\b/i,
+    /\bdo not change\s+unrelated files?\b/i,
+    /\bdo not modify\s+unrelated files?\b/i,
+];
+const NO_TOOL_INTENT_PATTERNS = [
+    /\bno tools? needed\b/i,
+    /\bno tools? required\b/i,
+    /\bwithout using tools\b/i,
+    /\bdo not use tools\b/i,
+    /\bdon't use tools\b/i,
+];
+const READ_ONLY_DELIVERABLE_PATTERNS = [
+    /\b(?:draft|write|compose|prepare|produce)\s+(?:(?:a|an|the)\s+)?(?:github\s+)?(?:issue|bug report|issue draft|issue body|proposal|plan|report|summary|findings?|analysis|recommendations?)\b/i,
+    /\b(?:issue|bug report)\s+(?:draft|body|template)\b/i,
+    /\b(?:return|provide|produce)\s+(?:text|markdown|answer|findings?|recommendations?)\s+only\b/i,
+];
+const RESEARCH_AGENT_PATTERNS = [
+    /\binvestigate\b/i,
+    /\bscout\b/i,
+    /\bresearch(?:er)?\b/i,
+];
+// Review/severity vocabulary like "must-fix items" or "should-fix tests" is not
+// the verb. Rather than dash-guarding every pattern (which would also suppress
+// CLI flags like "--fix" and genuine clause-level dashes like "branch—fix it"),
+// strip the known severity compounds (must|should|needs + dash + verb) from the
+// task text before matching. Dash coverage: ASCII hyphen + U+2010..U+2015.
+const SEVERITY_COMPOUND_PATTERN = /\b(?:must|should|needs)[-\u2010-\u2015](?:fix|edit|update|add|remove|replace|create|apply|make|do|implement|modify|delete|patch)\b/gi;
+function stripSeverityCompounds(task) {
+    return task.replace(SEVERITY_COMPOUND_PATTERN, " ");
+}
+export { stripSeverityCompounds };
+// Quoted categories in a finding-classification request describe fixes, not
+// instructions to perform them. Strip only that request, leaving sibling
+// imperatives (including another "must fix") subject to the normal guards.
+const FINDING_CLASSIFICATION_PATTERN = /\b(?:classify|categorize|weigh)\s+(?:(?:the|remaining)\s+)*(?:findings?|items?|issues?)\s+as\s+["“]must\s+fix\s+before\s+[^"”\n]+["”]\s+(?:vs\.?|versus)\s+["“]must\s+fix\s+before\s+[^"”\n]+["”]/gi;
+const PATH_LIKE_TOKEN_PATTERN = /[^\s]+[/\\][^\s]+|[^\s/\\]+\.[A-Za-z][A-Za-z0-9]{0,9}\b/g;
+const PATH_INTERNAL_IMPLEMENTATION_VERB = /\b(?:implement|edit|modify|refactor|delete|update|add|remove|replace|create)\b/i;
+function stripPathLikeTokens(task) {
+    return task.replace(PATH_LIKE_TOKEN_PATTERN, (token) => (PATH_INTERNAL_IMPLEMENTATION_VERB.test(token) ? " " : token));
+}
+const FIX_OR_PATCH_IMPLEMENTATION_PATTERN = /\b(?:fix|patch)\s+(?:(?:it|this|that|them|each|any|all|these|those)\b|(?:(?:a|an|the|any|all)\s+)?(?:(?:failing|failed|broken|flaky|red|cold|start|current|existing|reported|approved|known|regression|unit|integration|e2e|source|typescript|type-?script|ts|type-?check|compiler)\s+)*(?:bug|defect|issues?|problems?|failures?|regressions?|tests?|errors?|items?|typos?|code|source|implementation|component|function|module|class|method|logic|file|files|readme|docs?|changelog|package\.json|config|manifest|extension|prompt|command|lint(?:ing)?|build|ci|type-?check|type\s+checking)\b)/i;
+const WORKER_IMPLEMENTATION_PATTERNS = [
+    /\b(?:implement|edit|modify|refactor|delete)\b/i,
+    FIX_OR_PATCH_IMPLEMENTATION_PATTERN,
+    /\b(?:update|add|remove|replace|create)\b(?!\s+(?:(?:a|an|the)\s+)?(?:report|summary|findings?)(?:\b|$))/i,
+    /\bapply\s+(?:the\s+)?(?:(?:suggested|proposed|recommended)\s+)?(?:changes?|fix(?:es)?|patch)\b/i,
+    /\bmake\s+(?:the\s+)?changes\b/i,
+    /\bdo those fixes\b/i,
+];
+const FOLLOW_ON_IMPLEMENTATION_PATTERN = /(?:^|[.!?:;,\n])\s*(?:fix|patch|update|add|remove|replace|create|delete)\s+(?:(?:the|a|an|this|that|these|those|requested|specified|current|existing|approved|your|our)\s+)(?!(?:report|summary|findings?|analysis|recommendations?|answer|response|proposal|plan|issue|bug report)\b)[a-z][\w./-]*/i;
+const ADVISORY_INFINITIVE_PATTERN = /\b(?:explain|recommend|describe)\s+how\s+to\s+(?:fix|patch|update|add|remove|replace|create|delete|implement|edit|modify|refactor)\b/i;
+const EXPLICIT_IMPLEMENTATION_PATTERNS = [
+    /\b(?:implement|edit|modify|refactor)\b/i,
+    /\bapply\s+(?:the\s+)?(?:(?:suggested|proposed|recommended)\s+)?(?:changes?|fix(?:es)?|patch)\b/i,
+    /\bmake\s+(?:the\s+)?changes\b/i,
+    /\bdo those fixes\b/i,
+];
+const GENERAL_IMPLEMENTATION_PATTERNS = [
+    ...EXPLICIT_IMPLEMENTATION_PATTERNS,
+    FIX_OR_PATCH_IMPLEMENTATION_PATTERN,
+    /\b(?:update|add|remove|replace|delete|create)\s+(?:the\s+)?(?:file|files|code|source|implementation|test|tests|component|function|module|class|method|logic|import|imports|readme|docs?|changelog|package\.json|config|manifest|extension|prompt|command)\b/i,
+];
+function stripFrameworkInstructions(task) {
+    return task
+        .split("\n")
+        .filter((line) => !/^\s*\[(?:Write to|Read from):/i.test(line))
+        .filter((line) => !/^\s*(?:Create and maintain progress at:|Update progress at:|\*\*Output:\*\*|Write your findings to(?: exactly this path)?:|Return the complete artifact in your final response\.|The runtime will persist it to exactly this path:|Do not call contact_supervisor merely because no write-capable tool is available\.|This path is authoritative for this run\.|Ignore any other output filename or output path mentioned elsewhere)/i.test(line))
+        .join("\n");
+}
+function stripPatterns(task, patterns) {
+    let stripped = task;
+    for (const pattern of patterns) {
+        const flags = pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`;
+        stripped = stripped.replace(new RegExp(pattern.source, flags), " ");
+    }
+    return stripped;
+}
+function analyzeNoEditProhibitions(taskText) {
+    const readOnlyBoundary = NO_EDIT_BOUNDARY_ASSERTION_PATTERN.test(taskText);
+    let present = REVIEW_ONLY_PATTERNS.some((pattern) => pattern.test(taskText))
+        || NO_TOOL_INTENT_PATTERNS.some((pattern) => pattern.test(taskText))
+        || readOnlyBoundary;
+    let blanket = false;
+    let strippedText = stripPatterns(taskText, [...REVIEW_ONLY_PATTERNS, ...NO_TOOL_INTENT_PATTERNS, ADVISORY_INFINITIVE_PATTERN]);
+    if (readOnlyBoundary)
+        strippedText = stripPatterns(strippedText, [NO_EDIT_BOUNDARY_ASSERTION_PATTERN]);
+    const stripNoEditProhibition = (match, object, offset, source) => {
+        present = true;
+        if (GENERIC_PROHIBITION_OBJECT.test(object) && !hasScopedProhibitionContinuation(source.slice(offset + match.length)))
+            blanket = true;
+        return " ";
+    };
+    strippedText = strippedText.replace(new RegExp(COORDINATED_NO_EDIT_PROHIBITION_PATTERN.source, COORDINATED_NO_EDIT_PROHIBITION_PATTERN.flags), stripNoEditProhibition);
+    strippedText = strippedText.replace(new RegExp(NO_EDIT_PROHIBITION_PATTERN.source, NO_EDIT_PROHIBITION_PATTERN.flags), stripNoEditProhibition);
+    // Restore boundaries after stripping a prohibition from serialized prompts.
+    strippedText = strippedText.replace(/\\(?:r\\n|n)/g, "\n");
+    return { present, blanket, strippedText };
+}
+function taskHasReadOnlyDeliverable(taskText) {
+    return READ_ONLY_DELIVERABLE_PATTERNS.some((pattern) => pattern.test(taskText));
+}
+function isReviewerStyleAgent(agent) {
+    return /\b(?:advisor|reviewer|oracle)\b/i.test(agent);
+}
+function hasImplementationIntent(agent, taskText) {
+    if (isReviewerStyleAgent(agent))
+        return REVIEWER_REQUIRED_EDIT_PATTERNS.some((pattern) => pattern.test(taskText));
+    if (agent === "worker")
+        return WORKER_IMPLEMENTATION_PATTERNS.some((pattern) => pattern.test(taskText));
+    return GENERAL_IMPLEMENTATION_PATTERNS.some((pattern) => pattern.test(taskText));
+}
+export function classifyTaskMutationIntent(agent, task) {
+    const taskText = stripPatterns(stripSeverityCompounds(stripFrameworkInstructions(task)), [FINDING_CLASSIFICATION_PATTERN]);
+    const taskTextWithoutScopedConstraints = stripPatterns(taskText, SCOPED_NO_EDIT_CONSTRAINT_PATTERNS);
+    const prohibitions = analyzeNoEditProhibitions(taskTextWithoutScopedConstraints);
+    if (prohibitions.present) {
+        if (prohibitions.blanket)
+            return { kind: "read-only" };
+        const remaining = stripPathLikeTokens(prohibitions.strippedText);
+        if (isReviewerStyleAgent(agent)) {
+            return hasImplementationIntent(agent, remaining) ? { kind: "implementation" } : { kind: "read-only" };
+        }
+        return EXPLICIT_IMPLEMENTATION_PATTERNS.some((pattern) => pattern.test(remaining))
+            || FOLLOW_ON_IMPLEMENTATION_PATTERN.test(remaining)
+            ? { kind: "implementation" }
+            : { kind: "read-only" };
+    }
+    if (RESEARCH_AGENT_PATTERNS.some((pattern) => pattern.test(agent)))
+        return { kind: "read-only" };
+    if (hasImplementationIntent(agent, stripPathLikeTokens(taskText)))
+        return { kind: "implementation" };
+    if (isReviewerStyleAgent(agent))
+        return { kind: "read-only" };
+    return taskHasReadOnlyDeliverable(taskTextWithoutScopedConstraints) ? { kind: "read-only" } : { kind: "unknown" };
+}
+export function expectsImplementationMutation(agent, task) {
+    return classifyTaskMutationIntent(agent, task).kind === "implementation";
+}
+/** Bare write verbs that make a task write-capable for acceptance inference.
+ * Severity compounds ("must-fix items") are stripped before matching, so they
+ * are not write imperatives, while CLI flags ("--fix", "-w"), clause-level
+ * dashes ("branch—fix it"), and hyphenated imperatives ("hot-fix the bug")
+ * all stay write-capable. */
+const MAY_MUTATE_VERB_PATTERN = /\b(?:fix|implement|update|write|edit|modify|migrate|delete|remove|refactor|commit)\b/i;
+/**
+ * Whether the task could plausibly change files. Blanket prohibitions win;
+ * write verbs inside a scoped prohibition's object or a read-only deliverable
+ * phrase ("write a summary report") do not count; any other bare write verb
+ * does.
+ */
+export function taskMayMutate(task) {
+    const taskText = stripPatterns(stripSeverityCompounds(stripFrameworkInstructions(task)), [FINDING_CLASSIFICATION_PATTERN, ...SCOPED_NO_EDIT_CONSTRAINT_PATTERNS]);
+    const prohibitions = analyzeNoEditProhibitions(taskText);
+    if (prohibitions.blanket)
+        return false;
+    return MAY_MUTATE_VERB_PATTERN.test(stripPatterns(prohibitions.strippedText, READ_ONLY_DELIVERABLE_PATTERNS));
+}
+//# sourceMappingURL=task-intent.js.map

package/src/runs/shared/task-intent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-intent.js","sourceRoot":"","sources":["../../../../src/runs/shared/task-intent.ts"],"names":[],"mappings":"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"}

package/src/runs/shared/tool-availability.d.ts

@@ -0,0 +1,17 @@
+export interface ChildToolDiagnostic {
+    agent?: string;
+    required: string[];
+    available: string[];
+    missing: string[];
+    missingMcpDirectTools?: string[];
+}
+/**
+ * Explain missing child tools. Foreground children run inside the parent
+ * process and never load the parent's ambient extensions, so tools an ambient
+ * extension registers (MCP tools, provider tools) only exist for background
+ * children; the diagnostic says so instead of reporting a generic gap.
+ */
+export declare function formatChildToolDiagnostic(diagnostic: ChildToolDiagnostic, options?: {
+    host?: "parent" | "runner";
+}): string;
+//# sourceMappingURL=tool-availability.d.ts.map

package/src/runs/shared/tool-availability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-availability.d.ts","sourceRoot":"","sources":["../../../../src/runs/shared/tool-availability.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,mBAAmB;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;CACjC;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,mBAAmB,EAAE,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAA;CAAO,GAAG,MAAM,CAsB/H"}

package/src/runs/shared/tool-availability.js

@@ -0,0 +1,30 @@
+/**
+ * Explain missing child tools. Foreground children run inside the parent
+ * process and never load the parent's ambient extensions, so tools an ambient
+ * extension registers (MCP tools, provider tools) only exist for background
+ * children; the diagnostic says so instead of reporting a generic gap.
+ */
+export function formatChildToolDiagnostic(diagnostic, options = {}) {
+    const subject = diagnostic.agent ? `Agent '${diagnostic.agent}'` : "Subagent";
+    if (options.host === "parent") {
+        return [
+            `${subject} ran as a foreground child, which never loads the parent's ambient extensions, and these child tools were unavailable: ${diagnostic.missing.join(", ")}.`,
+            "The `tools` field is a strict allowlist; it does not load extension code.",
+            ...(diagnostic.missingMcpDirectTools?.length
+                ? [`MCP direct tools missing from the child registry: ${diagnostic.missingMcpDirectTools.join(", ")}.`]
+                : []),
+            "Agents that need MCP tools (`mcpDirectTools`, or MCP tools from an ambient adapter such as pi-mcp-adapter) or models from a provider extension must run as background children (`async: true`), which load the ambient extensions.",
+            "For extension tools a foreground child can load, add the provider path to `subagentOnlyExtensions` (child-only), `extensions`, or as a path-like entry in `tools`, while keeping each registered tool name in `tools`.",
+        ].join("\n");
+    }
+    return [
+        `${subject} requested unavailable child tools: ${diagnostic.missing.join(", ")}.`,
+        "The `tools` field is a strict allowlist; it does not load extension code.",
+        ...(diagnostic.missingMcpDirectTools?.length
+            ? [`Resolved MCP direct tools missing from the child registry: ${diagnostic.missingMcpDirectTools.join(", ")}. This indicates a host/pi-mcp-adapter registration problem, not a tool-call failure.`]
+            : []),
+        "For extension tools, add the provider path to `subagentOnlyExtensions` (child-only), `extensions`, or as a path-like entry in `tools`, while keeping each registered tool name in `tools`.",
+        "For MCP tools, verify the MCP adapter configuration and selected tool names. For builtin tools, verify the name against the installed Pi version.",
+    ].join("\n");
+}
+//# sourceMappingURL=tool-availability.js.map

package/src/runs/shared/tool-availability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-availability.js","sourceRoot":"","sources":["../../../../src/runs/shared/tool-availability.ts"],"names":[],"mappings":"AAQA;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,UAA+B,EAAE,UAA0C,EAAE;IACtH,MAAM,OAAO,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,UAAU,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC;IAC9E,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO;YACN,GAAG,OAAO,0HAA0H,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;YACpK,2EAA2E;YAC3E,GAAG,CAAC,UAAU,CAAC,qBAAqB,EAAE,MAAM;gBAC3C,CAAC,CAAC,CAAC,qDAAqD,UAAU,CAAC,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;gBACvG,CAAC,CAAC,EAAE,CAAC;YACN,oOAAoO;YACpO,wNAAwN;SACxN,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,CAAC;IACD,OAAO;QACN,GAAG,OAAO,uCAAuC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;QACjF,2EAA2E;QAC3E,GAAG,CAAC,UAAU,CAAC,qBAAqB,EAAE,MAAM;YAC3C,CAAC,CAAC,CAAC,8DAA8D,UAAU,CAAC,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,uFAAuF,CAAC;YACpM,CAAC,CAAC,EAAE,CAAC;QACN,4LAA4L;QAC5L,mJAAmJ;KACnJ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACd,CAAC"}

package/src/runs/shared/tool-budget.d.ts

@@ -0,0 +1,22 @@
+import type { ResolvedToolBudget, ToolBudgetConfig, ToolBudgetState } from "../../shared/types.ts";
+export declare const DEFAULT_TOOL_BUDGET_BLOCK: readonly ["read", "grep", "find", "ls"];
+export declare function normalizeToolBudgetBlock(block: ToolBudgetConfig["block"] | undefined): "*" | string[];
+export declare function validateToolBudgetConfig(raw: unknown, label?: string, options?: {
+    minimumHard?: 0 | 1;
+}): {
+    budget?: ResolvedToolBudget;
+    error?: string;
+};
+export declare function initialToolBudgetState(budget: ResolvedToolBudget): ToolBudgetState;
+export declare function toolBudgetState(budget: ResolvedToolBudget, toolCount: number, blockedTool?: string): ToolBudgetState;
+export declare function shouldBlockToolForBudget(budget: ResolvedToolBudget, toolName: string, nextToolCount: number): boolean;
+export declare function toolBudgetSoftNudge(budget: ResolvedToolBudget, toolCount: number): string;
+export declare function toolBudgetBlockedMessage(budget: ResolvedToolBudget, toolName: string, toolCount: number): string;
+/**
+ * Recognizes a hard-block reason generated by toolBudgetBlockedMessage for this exact budget
+ * and tool. A tool result only counts as a budget block when the entire message matches the
+ * runtime format and the embedded hard limit and tool name belong to this run; incidental
+ * occurrences of the phrase inside ordinary tool output are rejected.
+ */
+export declare function isToolBudgetBlockedMessage(budget: ResolvedToolBudget, resultText: string, blockedTool: string | undefined): boolean;
+//# sourceMappingURL=tool-budget.d.ts.map

package/src/runs/shared/tool-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-budget.d.ts","sourceRoot":"","sources":["../../../../src/runs/shared/tool-budget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAEnG,eAAO,MAAM,yBAAyB,yCAA0C,CAAC;AAEjF,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC,GAAG,SAAS,GAAG,GAAG,GAAG,MAAM,EAAE,CAIrG;AAED,wBAAgB,wBAAwB,CACvC,GAAG,EAAE,OAAO,EACZ,KAAK,SAAe,EACpB,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,CAAC,GAAG,CAAC,CAAA;CAAO,GACnC;IAAE,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAsBjD;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,kBAAkB,GAAG,eAAe,CAElF;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,eAAe,CAUpH;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAGrH;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEzF;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEhH;AAID;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACzC,MAAM,EAAE,kBAAkB,EAC1B,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAAG,SAAS,GAC7B,OAAO,CAOT"}

package/src/runs/shared/tool-budget.js

@@ -0,0 +1,79 @@
+export const DEFAULT_TOOL_BUDGET_BLOCK = ["read", "grep", "find", "ls"];
+export function normalizeToolBudgetBlock(block) {
+    if (block === "*")
+        return "*";
+    if (block === undefined)
+        return [...DEFAULT_TOOL_BUDGET_BLOCK];
+    return [...new Set(block.map((tool) => tool.trim()).filter(Boolean))];
+}
+export function validateToolBudgetConfig(raw, label = "toolBudget", options = {}) {
+    if (raw === undefined)
+        return {};
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return { error: `${label} must be an object with hard and optional soft/block.` };
+    const value = raw;
+    const minimumHard = options.minimumHard ?? 1;
+    if (typeof value.hard !== "number" || !Number.isInteger(value.hard) || value.hard < minimumHard) {
+        return { error: `${label}.hard must be an integer >= ${minimumHard}.` };
+    }
+    if (value.soft !== undefined && (typeof value.soft !== "number" || !Number.isInteger(value.soft) || value.soft < 1)) {
+        return { error: `${label}.soft must be an integer >= 1 when provided.` };
+    }
+    if (value.soft !== undefined && value.soft > value.hard) {
+        return { error: `${label}.soft must be <= ${label}.hard.` };
+    }
+    if (value.block !== undefined && value.block !== "*") {
+        if (!Array.isArray(value.block))
+            return { error: `${label}.block must be "*" or an array of tool names.` };
+        if (value.block.length === 0)
+            return { error: `${label}.block must contain at least one tool name.` };
+        for (const item of value.block) {
+            if (typeof item !== "string" || !item.trim())
+                return { error: `${label}.block must contain non-empty tool names.` };
+        }
+    }
+    return { budget: { hard: value.hard, ...(value.soft !== undefined ? { soft: value.soft } : {}), block: normalizeToolBudgetBlock(value.block) } };
+}
+export function initialToolBudgetState(budget) {
+    return { ...budget, toolCount: 0, outcome: "within-budget" };
+}
+export function toolBudgetState(budget, toolCount, blockedTool) {
+    const overHard = toolCount > budget.hard;
+    const overSoft = budget.soft !== undefined && toolCount >= budget.soft;
+    return {
+        ...budget,
+        toolCount,
+        outcome: overHard ? "hard-blocked" : overSoft ? "soft-reached" : "within-budget",
+        ...(overSoft ? { softReachedAt: budget.soft } : {}),
+        ...(overHard ? { hardReachedAt: budget.hard, blockedTool } : {}),
+    };
+}
+export function shouldBlockToolForBudget(budget, toolName, nextToolCount) {
+    if (nextToolCount <= budget.hard)
+        return false;
+    return budget.block === "*" || budget.block.includes(toolName);
+}
+export function toolBudgetSoftNudge(budget, toolCount) {
+    return `Tool budget soft limit reached after ${toolCount} tool call${toolCount === 1 ? "" : "s"} (soft ${budget.soft}, hard ${budget.hard}). Stop starting new browsing/search work and finalize from the context you already have.`;
+}
+export function toolBudgetBlockedMessage(budget, toolName, toolCount) {
+    return `Tool budget hard limit reached after ${toolCount} tool call${toolCount === 1 ? "" : "s"} (hard ${budget.hard}). The '${toolName}' tool is blocked so you can finalize from the context you already have.`;
+}
+const TOOL_BUDGET_BLOCKED_MESSAGE = /^Tool budget hard limit reached after (\d+) tool calls? \(hard (\d+)\)\. The '([^']+)' tool is blocked so you can finalize from the context you already have\.$/;
+/**
+ * Recognizes a hard-block reason generated by toolBudgetBlockedMessage for this exact budget
+ * and tool. A tool result only counts as a budget block when the entire message matches the
+ * runtime format and the embedded hard limit and tool name belong to this run; incidental
+ * occurrences of the phrase inside ordinary tool output are rejected.
+ */
+export function isToolBudgetBlockedMessage(budget, resultText, blockedTool) {
+    const tool = blockedTool?.trim();
+    if (!tool)
+        return false;
+    const match = TOOL_BUDGET_BLOCKED_MESSAGE.exec(resultText.trim());
+    if (!match)
+        return false;
+    const [, blockedToolCount, hard, namedTool] = match;
+    return Number(hard) === budget.hard && Number(blockedToolCount) > budget.hard && namedTool === tool;
+}
+//# sourceMappingURL=tool-budget.js.map

package/src/runs/shared/tool-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-budget.js","sourceRoot":"","sources":["../../../../src/runs/shared/tool-budget.ts"],"names":[],"mappings":"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"}

package/src/runs/shared/tool-timeout.d.ts

@@ -0,0 +1,32 @@
+export declare const TOOL_TIMEOUT_ENV = "PI_SUBAGENT_TOOL_TIMEOUT_MS";
+export declare const DEFAULT_FAST_TOOL_TIMEOUT_MS = 300000;
+export declare const DEFAULT_FAST_TOOL_TIMEOUT_TOOLS: Set<string>;
+/** Tools whose normal job can be to wait for a person or another run. */
+export declare const TOOL_TIMEOUT_EXEMPT_TOOLS: Set<string>;
+export declare const TOOL_TIMEOUT_ALLOWLIST: Set<string>;
+export declare function isToolTimeoutExempt(toolName: string | undefined): boolean;
+export declare function defaultToolTimeoutMs(toolName: string | undefined): number | undefined;
+export declare function effectiveToolTimeoutMs(toolName: string | undefined, configuredToolTimeoutMs: number | undefined): number | undefined;
+export declare function formatToolTimeoutMessage(toolName: string, timeoutMs: number): string;
+export declare function toolTimeoutCallKey(event: {
+    toolCallId?: unknown;
+    toolName?: unknown;
+}, fallbackId: number): string;
+export interface ToolTimeoutResolutionInput {
+    /** Per-call value from the subagent tool params (highest precedence). */
+    callValue?: unknown;
+    /** Agent frontmatter default (second precedence). */
+    agentValue?: number;
+    /** Global extension config.toolTimeoutMs (third precedence). */
+    configValue?: unknown;
+    /** PI_SUBAGENT_TOOL_TIMEOUT_MS environment override (lowest precedence). */
+    envValue?: string | undefined;
+}
+/** Resolve the configured hard timeout. Default fast-tool timeouts apply later per tool name. */
+export declare function resolveToolTimeoutMs(input: ToolTimeoutResolutionInput): {
+    toolTimeoutMs?: number;
+    error?: string;
+};
+/** Read the environment override without requiring callers to know the name. */
+export declare function toolTimeoutFromEnv(env?: NodeJS.ProcessEnv): string | undefined;
+//# sourceMappingURL=tool-timeout.d.ts.map

package/src/runs/shared/tool-timeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-timeout.d.ts","sourceRoot":"","sources":["../../../../src/runs/shared/tool-timeout.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gBAAgB,gCAAgC,CAAC;AAK9D,eAAO,MAAM,4BAA4B,SAAU,CAAC;AAEpD,eAAO,MAAM,+BAA+B,aAQ1C,CAAC;AAEH,yEAAyE;AACzE,eAAO,MAAM,yBAAyB,aAAyD,CAAC;AAGhG,eAAO,MAAM,sBAAsB,aAA4B,CAAC;AAEhE,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAEzE;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAIrF;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,uBAAuB,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGpI;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEpF;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAIlH;AAED,MAAM,WAAW,0BAA0B;IAC1C,yEAAyE;IACzE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B;AAED,iGAAiG;AACjG,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,0BAA0B,GAAG;IAAE,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CA2BlH;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,SAAS,CAE3F"}

package/src/runs/shared/tool-timeout.js

@@ -0,0 +1,74 @@
+export const TOOL_TIMEOUT_ENV = "PI_SUBAGENT_TOOL_TIMEOUT_MS";
+/** Maximum delay a Node.js timer accepts without overflow. */
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+export const DEFAULT_FAST_TOOL_TIMEOUT_MS = 300_000;
+export const DEFAULT_FAST_TOOL_TIMEOUT_TOOLS = new Set([
+    "read",
+    "grep",
+    "find",
+    "ls",
+    "edit",
+    "write",
+    "structured_output",
+]);
+/** Tools whose normal job can be to wait for a person or another run. */
+export const TOOL_TIMEOUT_EXEMPT_TOOLS = new Set(["contact_supervisor", "intercom", "bg_wait"]);
+// Backward-compatible export name for existing callers/tests.
+export const TOOL_TIMEOUT_ALLOWLIST = TOOL_TIMEOUT_EXEMPT_TOOLS;
+export function isToolTimeoutExempt(toolName) {
+    return toolName !== undefined && TOOL_TIMEOUT_EXEMPT_TOOLS.has(toolName);
+}
+export function defaultToolTimeoutMs(toolName) {
+    return toolName !== undefined && DEFAULT_FAST_TOOL_TIMEOUT_TOOLS.has(toolName)
+        ? DEFAULT_FAST_TOOL_TIMEOUT_MS
+        : undefined;
+}
+export function effectiveToolTimeoutMs(toolName, configuredToolTimeoutMs) {
+    if (isToolTimeoutExempt(toolName))
+        return undefined;
+    return configuredToolTimeoutMs ?? defaultToolTimeoutMs(toolName);
+}
+export function formatToolTimeoutMessage(toolName, timeoutMs) {
+    return `Tool '${toolName}' exceeded its timeout of ${timeoutMs}ms.`;
+}
+export function toolTimeoutCallKey(event, fallbackId) {
+    return typeof event.toolCallId === "string" && event.toolCallId.length > 0
+        ? `id:${event.toolCallId}`
+        : `anon:${String(event.toolName ?? "tool")}:${fallbackId}`;
+}
+/** Resolve the configured hard timeout. Default fast-tool timeouts apply later per tool name. */
+export function resolveToolTimeoutMs(input) {
+    const candidates = [
+        { label: "toolTimeoutMs", value: input.callValue },
+        { label: "agent.toolTimeoutMs", value: input.agentValue },
+        { label: "config.toolTimeoutMs", value: input.configValue },
+    ];
+    let winner;
+    for (const candidate of candidates) {
+        if (candidate.value === undefined)
+            continue;
+        winner = candidate;
+        break;
+    }
+    if (winner === undefined && input.envValue !== undefined && input.envValue.trim() !== "") {
+        winner = { label: TOOL_TIMEOUT_ENV, value: input.envValue };
+    }
+    if (winner === undefined)
+        return {};
+    let raw = winner.value;
+    let parsed;
+    if (winner.label === TOOL_TIMEOUT_ENV && typeof raw === "string") {
+        parsed = Number(raw);
+        if (raw.trim() !== "" && !Number.isNaN(parsed))
+            raw = parsed;
+    }
+    if (typeof raw !== "number" || !Number.isInteger(raw) || raw <= 0 || raw > MAX_TIMER_DELAY_MS) {
+        return { error: `${winner.label} must be a positive integer no larger than ${MAX_TIMER_DELAY_MS}.` };
+    }
+    return { toolTimeoutMs: raw };
+}
+/** Read the environment override without requiring callers to know the name. */
+export function toolTimeoutFromEnv(env = process.env) {
+    return env[TOOL_TIMEOUT_ENV];
+}
+//# sourceMappingURL=tool-timeout.js.map

package/src/runs/shared/tool-timeout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-timeout.js","sourceRoot":"","sources":["../../../../src/runs/shared/tool-timeout.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,gBAAgB,GAAG,6BAA6B,CAAC;AAE9D,8DAA8D;AAC9D,MAAM,kBAAkB,GAAG,aAAa,CAAC;AAEzC,MAAM,CAAC,MAAM,4BAA4B,GAAG,OAAO,CAAC;AAEpD,MAAM,CAAC,MAAM,+BAA+B,GAAG,IAAI,GAAG,CAAC;IACtD,MAAM;IACN,MAAM;IACN,MAAM;IACN,IAAI;IACJ,MAAM;IACN,OAAO;IACP,mBAAmB;CACnB,CAAC,CAAC;AAEH,yEAAyE;AACzE,MAAM,CAAC,MAAM,yBAAyB,GAAG,IAAI,GAAG,CAAC,CAAC,oBAAoB,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC;AAEhG,8DAA8D;AAC9D,MAAM,CAAC,MAAM,sBAAsB,GAAG,yBAAyB,CAAC;AAEhE,MAAM,UAAU,mBAAmB,CAAC,QAA4B;IAC/D,OAAO,QAAQ,KAAK,SAAS,IAAI,yBAAyB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AAC1E,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,QAA4B;IAChE,OAAO,QAAQ,KAAK,SAAS,IAAI,+BAA+B,CAAC,GAAG,CAAC,QAAQ,CAAC;QAC7E,CAAC,CAAC,4BAA4B;QAC9B,CAAC,CAAC,SAAS,CAAC;AACd,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,QAA4B,EAAE,uBAA2C;IAC/G,IAAI,mBAAmB,CAAC,QAAQ,CAAC;QAAE,OAAO,SAAS,CAAC;IACpD,OAAO,uBAAuB,IAAI,oBAAoB,CAAC,QAAQ,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,QAAgB,EAAE,SAAiB;IAC3E,OAAO,SAAS,QAAQ,6BAA6B,SAAS,KAAK,CAAC;AACrE,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,KAAmD,EAAE,UAAkB;IACzG,OAAO,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC;QACzE,CAAC,CAAC,MAAM,KAAK,CAAC,UAAU,EAAE;QAC1B,CAAC,CAAC,QAAQ,MAAM,CAAC,KAAK,CAAC,QAAQ,IAAI,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;AAC7D,CAAC;AAaD,iGAAiG;AACjG,MAAM,UAAU,oBAAoB,CAAC,KAAiC;IACrE,MAAM,UAAU,GAA6C;QAC5D,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,KAAK,CAAC,SAAS,EAAE;QAClD,EAAE,KAAK,EAAE,qBAAqB,EAAE,KAAK,EAAE,KAAK,CAAC,UAAU,EAAE;QACzD,EAAE,KAAK,EAAE,sBAAsB,EAAE,KAAK,EAAE,KAAK,CAAC,WAAW,EAAE;KAC3D,CAAC;IACF,IAAI,MAAqD,CAAC;IAC1D,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACpC,IAAI,SAAS,CAAC,KAAK,KAAK,SAAS;YAAE,SAAS;QAC5C,MAAM,GAAG,SAAS,CAAC;QACnB,MAAM;IACP,CAAC;IACD,IAAI,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC1F,MAAM,GAAG,EAAE,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;IAC7D,CAAC;IACD,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IAEpC,IAAI,GAAG,GAAY,MAAM,CAAC,KAAK,CAAC;IAChC,IAAI,MAAc,CAAC;IACnB,IAAI,MAAM,CAAC,KAAK,KAAK,gBAAgB,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAClE,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACrB,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC;YAAE,GAAG,GAAG,MAAM,CAAC;IAC9D,CAAC;IACD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,GAAG,GAAG,kBAAkB,EAAE,CAAC;QAC/F,OAAO,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC,KAAK,8CAA8C,kBAAkB,GAAG,EAAE,CAAC;IACtG,CAAC;IACD,OAAO,EAAE,aAAa,EAAE,GAAG,EAAE,CAAC;AAC/B,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,kBAAkB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACtE,OAAO,GAAG,CAAC,gBAAgB,CAAC,CAAC;AAC9B,CAAC"}

package/src/runs/shared/usage-budget.d.ts

@@ -0,0 +1,8 @@
+import type { CostSummary, UsageBudgetConfig, UsageBudgetState } from "../../shared/types.ts";
+export declare function validateUsageBudgetConfig(value: unknown, label?: string): {
+    budget?: UsageBudgetConfig;
+    error?: string;
+};
+export declare function usageBudgetState(config: UsageBudgetConfig | undefined, totals: CostSummary | undefined): UsageBudgetState | undefined;
+export declare function usageBudgetExceededMessage(state: UsageBudgetState): string;
+//# sourceMappingURL=usage-budget.d.ts.map

package/src/runs/shared/usage-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-budget.d.ts","sourceRoot":"","sources":["../../../../src/runs/shared/usage-budget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAA0B,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAatH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAgB,GAAG;IAAE,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAmB/H;AAWD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,iBAAiB,GAAG,SAAS,EAAE,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,gBAAgB,GAAG,SAAS,CAerI;AAED,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAI1E"}

package/src/runs/shared/usage-budget.js

@@ -0,0 +1,75 @@
+function validateLimit(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return { error: `${label} must be an object.` };
+    const raw = value;
+    const unknown = Object.keys(raw).find((key) => key !== "soft" && key !== "hard");
+    if (unknown)
+        return { error: `${label}.${unknown} is not supported.` };
+    if (typeof raw.hard !== "number" || !Number.isFinite(raw.hard) || raw.hard <= 0)
+        return { error: `${label}.hard must be a positive number.` };
+    if (raw.soft !== undefined && (typeof raw.soft !== "number" || !Number.isFinite(raw.soft) || raw.soft <= 0))
+        return { error: `${label}.soft must be a positive number.` };
+    if (typeof raw.soft === "number" && raw.soft > raw.hard)
+        return { error: `${label}.soft must be less than or equal to ${label}.hard.` };
+    return { limit: { ...(typeof raw.soft === "number" ? { soft: raw.soft } : {}), hard: raw.hard } };
+}
+export function validateUsageBudgetConfig(value, label = "usageBudget") {
+    if (value === undefined)
+        return {};
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return { error: `${label} must be an object.` };
+    const raw = value;
+    const unknown = Object.keys(raw).find((key) => key !== "tokens" && key !== "costUsd");
+    if (unknown)
+        return { error: `${label}.${unknown} is not supported.` };
+    const budget = {};
+    if (raw.tokens !== undefined) {
+        const tokens = validateLimit(raw.tokens, `${label}.tokens`);
+        if (tokens.error)
+            return { error: tokens.error };
+        budget.tokens = tokens.limit;
+    }
+    if (raw.costUsd !== undefined) {
+        const costUsd = validateLimit(raw.costUsd, `${label}.costUsd`);
+        if (costUsd.error)
+            return { error: costUsd.error };
+        budget.costUsd = costUsd.limit;
+    }
+    if (!budget.tokens && !budget.costUsd)
+        return { error: `${label} must include tokens or costUsd.` };
+    return { budget };
+}
+function metricState(limit, used) {
+    if (!limit)
+        return undefined;
+    return {
+        ...limit,
+        used,
+        outcome: used >= limit.hard ? "hard-exceeded" : limit.soft !== undefined && used >= limit.soft ? "soft-exceeded" : "within-budget",
+    };
+}
+export function usageBudgetState(config, totals) {
+    if (!config)
+        return undefined;
+    const inputTokens = totals?.inputTokens ?? 0;
+    const outputTokens = totals?.outputTokens ?? 0;
+    const tokens = metricState(config.tokens, inputTokens + outputTokens);
+    const costUsd = metricState(config.costUsd, totals?.costUsd ?? 0);
+    const reason = tokens?.outcome === "hard-exceeded" ? "tokens" : costUsd?.outcome === "hard-exceeded" ? "costUsd" : undefined;
+    return {
+        version: 1,
+        source: "reported",
+        ...(tokens ? { tokens } : {}),
+        ...(costUsd ? { costUsd } : {}),
+        exhausted: reason !== undefined,
+        ...(reason ? { reason } : {}),
+    };
+}
+export function usageBudgetExceededMessage(state) {
+    if (state.reason === "tokens" && state.tokens)
+        return `Usage budget exhausted: reported tokens ${state.tokens.used} reached hard limit ${state.tokens.hard}.`;
+    if (state.reason === "costUsd" && state.costUsd)
+        return `Usage budget exhausted: reported cost $${state.costUsd.used.toFixed(6)} reached hard limit $${state.costUsd.hard.toFixed(6)}.`;
+    return "Usage budget exhausted.";
+}
+//# sourceMappingURL=usage-budget.js.map

package/src/runs/shared/usage-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-budget.js","sourceRoot":"","sources":["../../../../src/runs/shared/usage-budget.ts"],"names":[],"mappings":"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"}