@unbrained/pm-cli 2026.9.6 → 2026.9.8

package/dist/sdk/cli-contracts/agent-output-contracts.d.ts

@@ -120,7 +120,7 @@ export interface PmProjectedTextDiagnostic {
     /** Binding diagnostic budget receipt. */
     diagnostic_output: PmDiagnosticOutputReceipt;
 }
-/** Bind human-readable diagnostics without ever truncating the corrective action away. */
+/** Bind human-readable diagnostics while retaining their first identifying line and corrective action. */
 export declare function projectPmDiagnosticText(output: string, correctiveAction: string, options?: {
     diagnosticClass?: PmDiagnosticOutputClass;
     maxEstimatedTokens?: number;

package/dist/sdk/cli-contracts/agent-output-contracts.js

@@ -1,478 +1,6 @@
-/**
- * @module sdk/cli-contracts/agent-output-contracts
- *
- * Declares the agent-facing output budget vocabulary shared by CLI, SDK,
- * packages, contract discovery, and regression gates. The contracts describe
- * output policy without coupling package authors to pm's renderer.
- */
+!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b4036040-c0b8-5d01-b490-3405722fd1c5")}catch(e2){}})();import{stripVTControlCharacters}from"node:util";import{resolvePmHistoryOperation}from"./command-aliases.js";import{PM_CORE_COMMAND_NAMES}from"./enum-contracts.js";const PM_OUTPUT_DEGRADATION_STEPS=["full","compact","brief","summary","counts"];const PM_OUTPUT_BUDGET_CLASSES=["mutation","read","discovery","governance"];const PM_DIAGNOSTIC_OUTPUT_CLASSES=["error","warning","validation_summary","recovery_bundle"];const PM_DIAGNOSTIC_DEGRADATION_STEPS=["full","omit_explanation","limit_collections","compact_recovery","action_only"];const MUTATION_COMMANDS=new Set(["append","claim","close","close-many","close-task","comments","config","copy","create","delete","docs","event","files","focus","history-author-acknowledge","history-compact","history-redact","history-repair","init","item","learnings","meet","notes","pause-task","release","remind","restore","schema","start-task","update","update-many"]);const DISCOVERY_COMMANDS=new Set(["contracts","extension","help","install","package","packages","profile","upgrade"]);const GOVERNANCE_COMMANDS=new Set(["gc","health","merge","stats","telemetry","test","test-all","validate"]);const DEFAULT_MAX_ESTIMATED_TOKENS={mutation:2e3,read:4e3,discovery:3e3,governance:6e3};const JSON_BUDGET_NUMERATOR=3;const JSON_BUDGET_DENOMINATOR=2;const MINIMUM_DIAGNOSTIC_BUDGET=192;const DIAGNOSTIC_DEFAULT_BUDGETS={error:{text:768,json:2e3},warning:{text:768,json:2e3},validation_summary:{text:1500,json:3e3},recovery_bundle:{text:768,json:2e3}};const PM_DIAGNOSTIC_OUTPUT_BUDGET_CONTRACTS=PM_DIAGNOSTIC_OUTPUT_CLASSES.map(diagnosticClass=>({diagnostic_class:diagnosticClass,default_max_estimated_tokens_by_format:DIAGNOSTIC_DEFAULT_BUDGETS[diagnosticClass],minimum_max_estimated_tokens:MINIMUM_DIAGNOSTIC_BUDGET,degradation_ladder:PM_DIAGNOSTIC_DEGRADATION_STEPS,corrective_action_paths:["required","recovery.suggested_retry","recovery.suggested_retry_args","recovery.next_best_command","next_steps[0]"],token_estimate:"ceil(utf8_bytes / 4)"}));const DIAGNOSTIC_BUDGET_BY_CLASS=new Map(PM_DIAGNOSTIC_OUTPUT_BUDGET_CONTRACTS.map(contract=>[contract.diagnostic_class,contract]));function inferPmOutputBudgetClass(command){const[rootCommand=""]=resolvePmHistoryOperation(command).split(/\s+/u);return MUTATION_COMMANDS.has(rootCommand)?"mutation":DISCOVERY_COMMANDS.has(rootCommand)?"discovery":GOVERNANCE_COMMANDS.has(rootCommand)?"governance":"read"}function createPmCommandOutputBudget(command,budgetClass=inferPmOutputBudgetClass(command)){const normalizedCommand=command.trim().replace(/\s+/gu," ");if(normalizedCommand.length===0){throw new TypeError("command must be a non-empty command path")}const toonBudget=DEFAULT_MAX_ESTIMATED_TOKENS[budgetClass];return definePmCommandOutputBudget({command:normalizedCommand,budget_class:budgetClass,default_max_estimated_tokens:toonBudget,default_max_estimated_tokens_by_format:{toon:toonBudget,json:Math.ceil(toonBudget*JSON_BUDGET_NUMERATOR/JSON_BUDGET_DENOMINATOR)},degradation_ladder:PM_OUTPUT_DEGRADATION_STEPS,allows_unbounded_opt_out:true,token_estimate:"ceil(utf8_bytes / 4)"})}function definePmCommandOutputBudget(contract){if(!Number.isSafeInteger(contract.default_max_estimated_tokens)||contract.default_max_estimated_tokens<=0){throw new RangeError("default_max_estimated_tokens must be a positive safe integer")}for(const[format,ceiling]of Object.entries(contract.default_max_estimated_tokens_by_format)){if(!Number.isSafeInteger(ceiling)||ceiling<=0){throw new RangeError(`default_max_estimated_tokens_by_format.${format} must be a positive safe integer`)}}return contract}const PM_COMMAND_OUTPUT_BUDGET_CONTRACTS=PM_CORE_COMMAND_NAMES.map(command=>createPmCommandOutputBudget(command));const OUTPUT_BUDGET_BY_COMMAND=new Map(PM_COMMAND_OUTPUT_BUDGET_CONTRACTS.map(contract=>[contract.command,contract]));function resolvePmCommandOutputBudget(command,options={}){const normalizedCommand=command.trim().replace(/\s+/gu," ");const[rootCommand]=resolvePmHistoryOperation(normalizedCommand).split(" ");const declared=OUTPUT_BUDGET_BY_COMMAND.get(rootCommand);if(declared)return{...declared,command:normalizedCommand};return options.generateFallback?createPmCommandOutputBudget(normalizedCommand):null}function estimatePmOutputTokens(utf8Bytes){return Math.ceil(Math.max(0,utf8Bytes)/4)}function resolvePmDiagnosticOutputBudget(diagnosticClass){const contract=DIAGNOSTIC_BUDGET_BY_CLASS.get(diagnosticClass);if(contract===void 0){throw new TypeError(`diagnosticClass must be one of: ${PM_DIAGNOSTIC_OUTPUT_CLASSES.join(", ")}`)}return contract}function estimateJsonDiagnosticTokens(value){return estimatePmOutputTokens(Buffer.byteLength(JSON.stringify(value,null,2),"utf8"))}function isDiagnosticRecord(value){return typeof value==="object"&&value!==null&&!Array.isArray(value)}function compactDiagnosticRecovery(value){if(!isDiagnosticRecord(value))return void 0;const compact={};for(const key of["suggested_retry","suggested_retry_args","next_best_command","allowed_values","candidate_commands","missing","missing_required_fields","option_scope","retry_after_ms"]){const candidate=value[key];if(Array.isArray(candidate)){compact[key]=key==="suggested_retry_args"?candidate:candidate.slice(0,3)}else if(candidate!==void 0)compact[key]=candidate}return Object.keys(compact).length>0?compact:void 0}function truncateDiagnosticString(value,maximum){if(typeof value!=="string"||value.length<=maximum)return value;return`${value.slice(0,Math.max(1,maximum-3))}...`}function truncateDiagnosticUtf8Text(value,maximumBytes){if(Buffer.byteLength(value,"utf8")<=maximumBytes)return value;const suffix="...";const codePoints=Array.from(value);let lower=0;let upper=codePoints.length;while(lower<upper){const middle=Math.ceil((lower+upper)/2);const candidate=`${codePoints.slice(0,middle).join("")}${suffix}`;if(Buffer.byteLength(candidate,"utf8")<=maximumBytes)lower=middle;else upper=middle-1}return`${codePoints.slice(0,lower).join("")}${suffix}`}function prioritizeDiagnosticFields(diagnostic){const prioritized={};for(const key of["code","required","recovery","next_steps","exit_code","type","title","detail","why","examples"]){if(Object.hasOwn(diagnostic,key)&&diagnostic[key]!==void 0){prioritized[key]=diagnostic[key]}}for(const[key,value]of Object.entries(diagnostic)){if(key!=="__proto__"&&!Object.hasOwn(prioritized,key)){prioritized[key]=value}}return prioritized}const DIAGNOSTIC_COLLECTION_LIMIT_STAGES=new Set(["limit_collections","compact_recovery","action_only"]);const DIAGNOSTIC_RECOVERY_COMPACTION_STAGES=new Set(["compact_recovery","action_only"]);function actionOnlyDiagnostic(candidate){const actionOnly={code:typeof candidate.code==="string"?candidate.code:"diagnostic",required:truncateDiagnosticString(candidate.required,160)??"Inspect the diagnostic code and retry with corrected input."};const recovery=compactDiagnosticRecovery(candidate.recovery);if(recovery!==void 0){actionOnly.recovery=recovery}else if(Array.isArray(candidate.next_steps)){actionOnly.next_steps=candidate.next_steps.slice(0,1)}if(candidate.exit_code!==void 0)actionOnly.exit_code=candidate.exit_code;if(candidate.type!==void 0)actionOnly.type=candidate.type;return actionOnly}function diagnosticCandidate(diagnostic,stage){const candidate=structuredClone(diagnostic);if(stage!=="full"){delete candidate.why;delete candidate.examples}if(DIAGNOSTIC_COLLECTION_LIMIT_STAGES.has(stage)){for(const[key,value]of Object.entries(candidate)){if(Array.isArray(value))candidate[key]=value.slice(0,3)}}if(DIAGNOSTIC_RECOVERY_COMPACTION_STAGES.has(stage)){const recovery=compactDiagnosticRecovery(candidate.recovery);if(recovery)candidate.recovery=recovery;else delete candidate.recovery}if(stage!=="action_only")return prioritizeDiagnosticFields(candidate);return actionOnlyDiagnostic(candidate)}function attachDiagnosticReceipt(candidate,receipt){const projected={...candidate,diagnostic_output:{...receipt,estimated_tokens:0}};for(let attempt=0;attempt<4;attempt+=1){const estimatedTokens=estimateJsonDiagnosticTokens(projected);const outputReceipt=projected.diagnostic_output;if(outputReceipt.estimated_tokens===estimatedTokens)break;outputReceipt.estimated_tokens=estimatedTokens}return projected}function shrinkMinimalDiagnosticCandidate(candidate,receipt,budget){let fallback=attachDiagnosticReceipt(candidate,receipt);for(const optionalField of["recovery","exit_code"]){if(estimateJsonDiagnosticTokens(fallback)<=budget||candidate[optionalField]===void 0){continue}delete candidate[optionalField];fallback=attachDiagnosticReceipt(candidate,receipt)}let maximumActionBytes=40;while(estimateJsonDiagnosticTokens(fallback)>budget&&maximumActionBytes>4){maximumActionBytes-=4;candidate.code=truncateDiagnosticUtf8Text(String(candidate.code),maximumActionBytes);candidate.required=truncateDiagnosticUtf8Text(String(candidate.required),maximumActionBytes);fallback=attachDiagnosticReceipt(candidate,receipt)}return fallback}function createMinimalDiagnosticFallback(projected,budget){const receipt=projected.diagnostic_output;const{estimated_tokens:_estimatedTokens,...receiptWithoutEstimate}=receipt;const boundedOmittedFields=receiptWithoutEstimate.omitted_fields.slice(0,8).map(field=>truncateDiagnosticUtf8Text(field,32));const boundedReceipt={...receiptWithoutEstimate,omitted_fields:boundedOmittedFields,...receiptWithoutEstimate.omitted_fields.length>boundedOmittedFields.length?{omitted_fields_overflow_count:receiptWithoutEstimate.omitted_fields.length-boundedOmittedFields.length}:{}};const recoveryCandidate=compactDiagnosticRecovery(projected.recovery);const recovery=recoveryCandidate&&estimateJsonDiagnosticTokens(recoveryCandidate)<=48?recoveryCandidate:void 0;const candidate={code:truncateDiagnosticUtf8Text(String(projected.code),320),required:truncateDiagnosticUtf8Text(String(projected.required),320),...recovery?{recovery}:{},...projected.exit_code!==void 0?{exit_code:projected.exit_code}:{}};let fallback=attachDiagnosticReceipt(candidate,boundedReceipt);while(estimateJsonDiagnosticTokens(fallback)>budget&&boundedReceipt.omitted_fields.length>0){boundedReceipt.omitted_fields.pop();boundedReceipt.omitted_fields_overflow_count=receiptWithoutEstimate.omitted_fields.length-boundedReceipt.omitted_fields.length;fallback=attachDiagnosticReceipt(candidate,boundedReceipt)}fallback=shrinkMinimalDiagnosticCandidate(candidate,boundedReceipt,budget);return fallback}function projectPmDiagnosticOutput(diagnostic,options={}){const diagnosticRecord=diagnostic;const diagnosticClass=options.diagnosticClass??"error";const contract=resolvePmDiagnosticOutputBudget(diagnosticClass);const explicitBudget=options.maxEstimatedTokens;if(explicitBudget!==void 0&&(!Number.isSafeInteger(explicitBudget)||explicitBudget<contract.minimum_max_estimated_tokens)){throw new RangeError(`maxEstimatedTokens must be a safe integer >= ${contract.minimum_max_estimated_tokens}`)}const budget=explicitBudget??contract.default_max_estimated_tokens_by_format.json;const originalEstimatedTokens=estimateJsonDiagnosticTokens(diagnosticRecord);const originalFields=Object.keys(diagnosticRecord);if(originalEstimatedTokens<=budget){return prioritizeDiagnosticFields(structuredClone(diagnosticRecord))}let projected;for(const[index,stage]of contract.degradation_ladder.entries()){const candidate=diagnosticCandidate(diagnosticRecord,stage);const omittedFields=originalFields.filter(field=>!Object.hasOwn(candidate,field));const withReceipt=attachDiagnosticReceipt(candidate,{diagnostic_class:diagnosticClass,format:"json",budget,budget_source:explicitBudget===void 0?"default":"explicit",original_estimated_tokens:originalEstimatedTokens,truncated:index>0,degradation_steps:contract.degradation_ladder.slice(0,index+1),omitted_fields:omittedFields});projected=withReceipt;if(estimateJsonDiagnosticTokens(withReceipt)<=budget)break}if(estimateJsonDiagnosticTokens(projected)>budget){projected=createMinimalDiagnosticFallback(projected,budget)}return projected}function sanitizeDiagnosticText(text){return stripVTControlCharacters(text).replace(/\r\n/gu,"\n").replace(/[^\P{Cc}\n]/gu," ")}function projectPmDiagnosticText(output,correctiveAction,options={}){const diagnosticClass=options.diagnosticClass??"error";const contract=resolvePmDiagnosticOutputBudget(diagnosticClass);const explicitBudget=options.maxEstimatedTokens;if(explicitBudget!==void 0&&(!Number.isSafeInteger(explicitBudget)||explicitBudget<contract.minimum_max_estimated_tokens)){throw new RangeError(`maxEstimatedTokens must be a safe integer >= ${contract.minimum_max_estimated_tokens}`)}const budget=explicitBudget??contract.default_max_estimated_tokens_by_format.text;const sanitizedOutput=sanitizeDiagnosticText(output);const originalEstimatedTokens=estimatePmOutputTokens(Buffer.byteLength(sanitizedOutput,"utf8"));const truncated=originalEstimatedTokens>budget;const actionPrefix="What is required:\n  ";const identity=truncateDiagnosticUtf8Text(sanitizedOutput.trimStart().split(/\r?\n/u,1)[0].trim(),320);const actionSuffix=`
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="1d338971-5a60-5b4e-b4c8-0705c8e8c98c")}catch(e){}}();
-import { PM_CORE_COMMAND_NAMES } from "./enum-contracts.js";
-/** Stable degradation stages applied when an output exceeds its token budget. */
-export const PM_OUTPUT_DEGRADATION_STEPS = [
-    "full",
-    "compact",
-    "brief",
-    "summary",
-    "counts",
-];
-/** Stable command-output classes used to assign conservative default budgets. */
-export const PM_OUTPUT_BUDGET_CLASSES = [
-    "mutation",
-    "read",
-    "discovery",
-    "governance",
-];
-/** Stable diagnostic families that require independent output ceilings. */
-export const PM_DIAGNOSTIC_OUTPUT_CLASSES = [
-    "error",
-    "warning",
-    "validation_summary",
-    "recovery_bundle",
-];
-/** Deterministic diagnostic degradation stages, from richest to smallest. */
-export const PM_DIAGNOSTIC_DEGRADATION_STEPS = [
-    "full",
-    "omit_explanation",
-    "limit_collections",
-    "compact_recovery",
-    "action_only",
-];
-const MUTATION_COMMANDS = new Set([
-    "append",
-    "claim",
-    "close",
-    "close-many",
-    "close-task",
-    "comments",
-    "config",
-    "copy",
-    "create",
-    "delete",
-    "docs",
-    "event",
-    "files",
-    "focus",
-    "history-author-acknowledge",
-    "history-compact",
-    "history-redact",
-    "history-repair",
-    "init",
-    "item",
-    "learnings",
-    "meet",
-    "notes",
-    "pause-task",
-    "release",
-    "remind",
-    "restore",
-    "schema",
-    "start-task",
-    "update",
-    "update-many",
-]);
-const DISCOVERY_COMMANDS = new Set([
-    "contracts",
-    "extension",
-    "help",
-    "install",
-    "package",
-    "packages",
-    "profile",
-    "upgrade",
-]);
-const GOVERNANCE_COMMANDS = new Set([
-    "gc",
-    "health",
-    "merge",
-    "stats",
-    "telemetry",
-    "test",
-    "test-all",
-    "validate",
-]);
-const DEFAULT_MAX_ESTIMATED_TOKENS = {
-    mutation: 2_000,
-    read: 4_000,
-    discovery: 3_000,
-    governance: 6_000,
-};
-const JSON_BUDGET_NUMERATOR = 3;
-const JSON_BUDGET_DENOMINATOR = 2;
-const MINIMUM_DIAGNOSTIC_BUDGET = 192;
-const DIAGNOSTIC_DEFAULT_BUDGETS = {
-    error: { text: 768, json: 2_000 },
-    warning: { text: 768, json: 2_000 },
-    validation_summary: { text: 1_500, json: 3_000 },
-    recovery_bundle: { text: 768, json: 2_000 },
-};
-/** Public default contract for every diagnostic family. */
-export const PM_DIAGNOSTIC_OUTPUT_BUDGET_CONTRACTS = PM_DIAGNOSTIC_OUTPUT_CLASSES.map((diagnosticClass) => ({
-    diagnostic_class: diagnosticClass,
-    default_max_estimated_tokens_by_format: DIAGNOSTIC_DEFAULT_BUDGETS[diagnosticClass],
-    minimum_max_estimated_tokens: MINIMUM_DIAGNOSTIC_BUDGET,
-    degradation_ladder: PM_DIAGNOSTIC_DEGRADATION_STEPS,
-    corrective_action_paths: [
-        "required",
-        "recovery.suggested_retry",
-        "recovery.suggested_retry_args",
-        "recovery.next_best_command",
-        "next_steps[0]",
-    ],
-    token_estimate: "ceil(utf8_bytes / 4)",
-}));
-const DIAGNOSTIC_BUDGET_BY_CLASS = new Map(PM_DIAGNOSTIC_OUTPUT_BUDGET_CONTRACTS.map((contract) => [contract.diagnostic_class, contract]));
-/** Infer the conservative workload class for a core or package command. */
-export function inferPmOutputBudgetClass(command) {
-    const [rootCommand = ""] = command.trim().split(/\s+/u);
-    return MUTATION_COMMANDS.has(rootCommand)
-        ? "mutation"
-        : DISCOVERY_COMMANDS.has(rootCommand)
-            ? "discovery"
-            : GOVERNANCE_COMMANDS.has(rootCommand)
-                ? "governance"
-                : "read";
-}
-/** Build the generated default budget for a core or package command. */
-export function createPmCommandOutputBudget(command, budgetClass = inferPmOutputBudgetClass(command)) {
-    const normalizedCommand = command.trim().replace(/\s+/gu, " ");
-    if (normalizedCommand.length === 0) {
-        throw new TypeError("command must be a non-empty command path");
-    }
-    const toonBudget = DEFAULT_MAX_ESTIMATED_TOKENS[budgetClass];
-    return definePmCommandOutputBudget({
-        command: normalizedCommand,
-        budget_class: budgetClass,
-        default_max_estimated_tokens: toonBudget,
-        default_max_estimated_tokens_by_format: {
-            toon: toonBudget,
-            json: Math.ceil((toonBudget * JSON_BUDGET_NUMERATOR) / JSON_BUDGET_DENOMINATOR),
-        },
-        degradation_ladder: PM_OUTPUT_DEGRADATION_STEPS,
-        allows_unbounded_opt_out: true,
-        token_estimate: "ceil(utf8_bytes / 4)",
-    });
-}
-/**
- * Declares one budget contract while preserving literal command metadata for
- * package-authored registries and test fixtures. Rejects ceilings that cannot
- * represent a positive, deterministic token allowance.
- */
-export function definePmCommandOutputBudget(contract) {
-    if (!Number.isSafeInteger(contract.default_max_estimated_tokens) ||
-        contract.default_max_estimated_tokens <= 0) {
-        throw new RangeError("default_max_estimated_tokens must be a positive safe integer");
-    }
-    for (const [format, ceiling] of Object.entries(contract.default_max_estimated_tokens_by_format)) {
-        if (!Number.isSafeInteger(ceiling) || ceiling <= 0) {
-            throw new RangeError(`default_max_estimated_tokens_by_format.${format} must be a positive safe integer`);
-        }
-    }
-    return contract;
-}
-/** Public default budget contract for every built-in pm command. */
-export const PM_COMMAND_OUTPUT_BUDGET_CONTRACTS = PM_CORE_COMMAND_NAMES.map((command) => createPmCommandOutputBudget(command));
-const OUTPUT_BUDGET_BY_COMMAND = new Map(PM_COMMAND_OUTPUT_BUDGET_CONTRACTS.map((contract) => [contract.command, contract]));
-/** Implement built-in lookup with an opt-in generated package fallback. */
-export function resolvePmCommandOutputBudget(command, options = {}) {
-    const normalizedCommand = command.trim().replace(/\s+/gu, " ");
-    const [rootCommand] = normalizedCommand.split(" ");
-    const declared = OUTPUT_BUDGET_BY_COMMAND.get(rootCommand);
-    if (declared)
-        return { ...declared, command: normalizedCommand };
-    return options.generateFallback
-        ? createPmCommandOutputBudget(normalizedCommand)
-        : null;
-}
-/** Estimate conservative token usage from UTF-8 output bytes. */
-export function estimatePmOutputTokens(utf8Bytes) {
-    return Math.ceil(Math.max(0, utf8Bytes) / 4);
-}
-/** Resolve the binding output contract for one diagnostic family. */
-export function resolvePmDiagnosticOutputBudget(diagnosticClass) {
-    const contract = DIAGNOSTIC_BUDGET_BY_CLASS.get(diagnosticClass);
-    if (contract === undefined) {
-        throw new TypeError(`diagnosticClass must be one of: ${PM_DIAGNOSTIC_OUTPUT_CLASSES.join(", ")}`);
-    }
-    return contract;
-}
-function estimateJsonDiagnosticTokens(value) {
-    return estimatePmOutputTokens(Buffer.byteLength(JSON.stringify(value, null, 2), "utf8"));
-}
-function isDiagnosticRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function compactDiagnosticRecovery(value) {
-    if (!isDiagnosticRecord(value))
-        return undefined;
-    const compact = {};
-    for (const key of [
-        "suggested_retry",
-        "suggested_retry_args",
-        "next_best_command",
-        "allowed_values",
-        "candidate_commands",
-        "missing",
-        "missing_required_fields",
-        "option_scope",
-        "retry_after_ms",
-    ]) {
-        const candidate = value[key];
-        if (Array.isArray(candidate)) {
-            compact[key] =
-                key === "suggested_retry_args" ? candidate : candidate.slice(0, 3);
-        }
-        else if (candidate !== undefined)
-            compact[key] = candidate;
-    }
-    return Object.keys(compact).length > 0 ? compact : undefined;
-}
-function truncateDiagnosticString(value, maximum) {
-    if (typeof value !== "string" || value.length <= maximum)
-        return value;
-    return `${value.slice(0, Math.max(1, maximum - 3))}...`;
-}
-function truncateDiagnosticUtf8Text(value, maximumBytes) {
-    if (Buffer.byteLength(value, "utf8") <= maximumBytes)
-        return value;
-    const suffix = "...";
-    const codePoints = Array.from(value);
-    let lower = 0;
-    let upper = codePoints.length;
-    while (lower < upper) {
-        const middle = Math.ceil((lower + upper) / 2);
-        const candidate = `${codePoints.slice(0, middle).join("")}${suffix}`;
-        if (Buffer.byteLength(candidate, "utf8") <= maximumBytes)
-            lower = middle;
-        else
-            upper = middle - 1;
-    }
-    return `${codePoints.slice(0, lower).join("")}${suffix}`;
-}
-function prioritizeDiagnosticFields(diagnostic) {
-    const prioritized = {};
-    for (const key of [
-        "code",
-        "required",
-        "recovery",
-        "next_steps",
-        "exit_code",
-        "type",
-        "title",
-        "detail",
-        "why",
-        "examples",
-    ]) {
-        if (Object.hasOwn(diagnostic, key) && diagnostic[key] !== undefined) {
-            prioritized[key] = diagnostic[key];
-        }
-    }
-    for (const [key, value] of Object.entries(diagnostic)) {
-        if (key !== "__proto__" && !Object.hasOwn(prioritized, key)) {
-            prioritized[key] = value;
-        }
-    }
-    return prioritized;
-}
-const DIAGNOSTIC_COLLECTION_LIMIT_STAGES = new Set(["limit_collections", "compact_recovery", "action_only"]);
-const DIAGNOSTIC_RECOVERY_COMPACTION_STAGES = new Set(["compact_recovery", "action_only"]);
-function actionOnlyDiagnostic(candidate) {
-    const actionOnly = {
-        code: typeof candidate.code === "string" ? candidate.code : "diagnostic",
-        required: truncateDiagnosticString(candidate.required, 160) ??
-            "Inspect the diagnostic code and retry with corrected input.",
-    };
-    const recovery = compactDiagnosticRecovery(candidate.recovery);
-    if (recovery !== undefined) {
-        actionOnly.recovery = recovery;
-    }
-    else if (Array.isArray(candidate.next_steps)) {
-        actionOnly.next_steps = candidate.next_steps.slice(0, 1);
-    }
-    if (candidate.exit_code !== undefined)
-        actionOnly.exit_code = candidate.exit_code;
-    if (candidate.type !== undefined)
-        actionOnly.type = candidate.type;
-    return actionOnly;
-}
-function diagnosticCandidate(diagnostic, stage) {
-    const candidate = structuredClone(diagnostic);
-    if (stage !== "full") {
-        delete candidate.why;
-        delete candidate.examples;
-    }
-    if (DIAGNOSTIC_COLLECTION_LIMIT_STAGES.has(stage)) {
-        for (const [key, value] of Object.entries(candidate)) {
-            if (Array.isArray(value))
-                candidate[key] = value.slice(0, 3);
-        }
-    }
-    if (DIAGNOSTIC_RECOVERY_COMPACTION_STAGES.has(stage)) {
-        const recovery = compactDiagnosticRecovery(candidate.recovery);
-        if (recovery)
-            candidate.recovery = recovery;
-        else
-            delete candidate.recovery;
-    }
-    if (stage !== "action_only")
-        return prioritizeDiagnosticFields(candidate);
-    return actionOnlyDiagnostic(candidate);
-}
-function attachDiagnosticReceipt(candidate, receipt) {
-    const projected = {
-        ...candidate,
-        diagnostic_output: { ...receipt, estimated_tokens: 0 },
-    };
-    for (let attempt = 0; attempt < 4; attempt += 1) {
-        const estimatedTokens = estimateJsonDiagnosticTokens(projected);
-        const outputReceipt = projected.diagnostic_output;
-        if (outputReceipt.estimated_tokens === estimatedTokens)
-            break;
-        outputReceipt.estimated_tokens = estimatedTokens;
-    }
-    return projected;
-}
-function shrinkMinimalDiagnosticCandidate(candidate, receipt, budget) {
-    let fallback = attachDiagnosticReceipt(candidate, receipt);
-    for (const optionalField of ["recovery", "exit_code"]) {
-        if (estimateJsonDiagnosticTokens(fallback) <= budget ||
-            candidate[optionalField] === undefined) {
-            continue;
-        }
-        delete candidate[optionalField];
-        fallback = attachDiagnosticReceipt(candidate, receipt);
-    }
-    let maximumActionBytes = 40;
-    while (estimateJsonDiagnosticTokens(fallback) > budget &&
-        maximumActionBytes > 4) {
-        maximumActionBytes -= 4;
-        candidate.code = truncateDiagnosticUtf8Text(String(candidate.code), maximumActionBytes);
-        candidate.required = truncateDiagnosticUtf8Text(String(candidate.required), maximumActionBytes);
-        fallback = attachDiagnosticReceipt(candidate, receipt);
-    }
-    return fallback;
-}
-function createMinimalDiagnosticFallback(projected, budget) {
-    const receipt = projected.diagnostic_output;
-    const { estimated_tokens: _estimatedTokens, ...receiptWithoutEstimate } = receipt;
-    const boundedOmittedFields = receiptWithoutEstimate.omitted_fields
-        .slice(0, 8)
-        .map((field) => truncateDiagnosticUtf8Text(field, 32));
-    const boundedReceipt = {
-        ...receiptWithoutEstimate,
-        omitted_fields: boundedOmittedFields,
-        ...(receiptWithoutEstimate.omitted_fields.length >
-            boundedOmittedFields.length
-            ? {
-                omitted_fields_overflow_count: receiptWithoutEstimate.omitted_fields.length -
-                    boundedOmittedFields.length,
-            }
-            : {}),
-    };
-    const recoveryCandidate = compactDiagnosticRecovery(projected.recovery);
-    const recovery = recoveryCandidate && estimateJsonDiagnosticTokens(recoveryCandidate) <= 48
-        ? recoveryCandidate
-        : undefined;
-    const candidate = {
-        code: truncateDiagnosticUtf8Text(String(projected.code), 320),
-        required: truncateDiagnosticUtf8Text(String(projected.required), 320),
-        ...(recovery ? { recovery } : {}),
-        ...(projected.exit_code !== undefined
-            ? { exit_code: projected.exit_code }
-            : {}),
-    };
-    let fallback = attachDiagnosticReceipt(candidate, boundedReceipt);
-    while (estimateJsonDiagnosticTokens(fallback) > budget &&
-        boundedReceipt.omitted_fields.length > 0) {
-        boundedReceipt.omitted_fields.pop();
-        boundedReceipt.omitted_fields_overflow_count =
-            receiptWithoutEstimate.omitted_fields.length -
-                boundedReceipt.omitted_fields.length;
-        fallback = attachDiagnosticReceipt(candidate, boundedReceipt);
-    }
-    fallback = shrinkMinimalDiagnosticCandidate(candidate, boundedReceipt, budget);
-    return fallback;
-}
-/**
- * Bind a JSON diagnostic to its declared ceiling while preserving the first
- * corrective action and reporting every top-level omission.
- */
-export function projectPmDiagnosticOutput(diagnostic, options = {}) {
-    const diagnosticRecord = diagnostic;
-    const diagnosticClass = options.diagnosticClass ?? "error";
-    const contract = resolvePmDiagnosticOutputBudget(diagnosticClass);
-    const explicitBudget = options.maxEstimatedTokens;
-    if (explicitBudget !== undefined &&
-        (!Number.isSafeInteger(explicitBudget) ||
-            explicitBudget < contract.minimum_max_estimated_tokens)) {
-        throw new RangeError(`maxEstimatedTokens must be a safe integer >= ${contract.minimum_max_estimated_tokens}`);
-    }
-    const budget = explicitBudget ?? contract.default_max_estimated_tokens_by_format.json;
-    const originalEstimatedTokens = estimateJsonDiagnosticTokens(diagnosticRecord);
-    const originalFields = Object.keys(diagnosticRecord);
-    if (originalEstimatedTokens <= budget) {
-        return prioritizeDiagnosticFields(structuredClone(diagnosticRecord));
-    }
-    let projected;
-    for (const [index, stage] of contract.degradation_ladder.entries()) {
-        const candidate = diagnosticCandidate(diagnosticRecord, stage);
-        const omittedFields = originalFields.filter((field) => !Object.hasOwn(candidate, field));
-        const withReceipt = attachDiagnosticReceipt(candidate, {
-            diagnostic_class: diagnosticClass,
-            format: "json",
-            budget,
-            budget_source: explicitBudget === undefined ? "default" : "explicit",
-            original_estimated_tokens: originalEstimatedTokens,
-            truncated: index > 0,
-            degradation_steps: contract.degradation_ladder.slice(0, index + 1),
-            omitted_fields: omittedFields,
-        });
-        projected = withReceipt;
-        if (estimateJsonDiagnosticTokens(withReceipt) <= budget)
-            break;
-    }
-    if (estimateJsonDiagnosticTokens(projected) > budget) {
-        projected = createMinimalDiagnosticFallback(projected, budget);
-    }
-    return projected;
-}
-/** Bind human-readable diagnostics without ever truncating the corrective action away. */
-export function projectPmDiagnosticText(output, correctiveAction, options = {}) {
-    const diagnosticClass = options.diagnosticClass ?? "error";
-    const contract = resolvePmDiagnosticOutputBudget(diagnosticClass);
-    const explicitBudget = options.maxEstimatedTokens;
-    if (explicitBudget !== undefined &&
-        (!Number.isSafeInteger(explicitBudget) ||
-            explicitBudget < contract.minimum_max_estimated_tokens)) {
-        throw new RangeError(`maxEstimatedTokens must be a safe integer >= ${contract.minimum_max_estimated_tokens}`);
-    }
-    const budget = explicitBudget ?? contract.default_max_estimated_tokens_by_format.text;
-    const originalEstimatedTokens = estimatePmOutputTokens(Buffer.byteLength(output, "utf8"));
-    const truncated = originalEstimatedTokens > budget;
-    const actionPrefix = "What is required:\n  ";
-    const actionSuffix = `\n\nDiagnostic output exceeded its declared ${budget}-token ceiling; rerun with structured JSON for the bounded recovery envelope.`;
-    const correctiveActionText = correctiveAction.trim() ||
-        "Inspect the diagnostic code and retry with corrected input.";
-    const availableActionBytes = Math.max(1, budget * 4 - Buffer.byteLength(`${actionPrefix}${actionSuffix}`, "utf8"));
-    const projectedOutput = truncated
-        ? `${actionPrefix}${truncateDiagnosticUtf8Text(correctiveActionText, availableActionBytes)}${actionSuffix}`
-        : output;
-    return {
-        output: projectedOutput,
-        diagnostic_output: {
-            diagnostic_class: diagnosticClass,
-            format: "text",
-            budget,
-            budget_source: explicitBudget === undefined ? "default" : "explicit",
-            original_estimated_tokens: originalEstimatedTokens,
-            estimated_tokens: estimatePmOutputTokens(Buffer.byteLength(projectedOutput, "utf8")),
-            truncated,
-            degradation_steps: truncated
-                ? [...contract.degradation_ladder]
-                : ["full"],
-            omitted_fields: truncated ? ["explanation", "collections"] : [],
-        },
-    };
-}
+${identity}
+
+Diagnostic output exceeded its declared ${budget}-token ceiling; rerun with structured JSON for the bounded recovery envelope.`;const correctiveActionText=sanitizeDiagnosticText(correctiveAction).trim()||"Inspect the diagnostic code and retry with corrected input.";const availableActionBytes=Math.max(1,budget*4-Buffer.byteLength(`${actionPrefix}${actionSuffix}`,"utf8"));const projectedOutput=truncated?`${actionPrefix}${truncateDiagnosticUtf8Text(correctiveActionText,availableActionBytes)}${actionSuffix}`:sanitizedOutput;return{output:projectedOutput,diagnostic_output:{diagnostic_class:diagnosticClass,format:"text",budget,budget_source:explicitBudget===void 0?"default":"explicit",original_estimated_tokens:originalEstimatedTokens,estimated_tokens:estimatePmOutputTokens(Buffer.byteLength(projectedOutput,"utf8")),truncated,degradation_steps:truncated?[...contract.degradation_ladder]:["full"],omitted_fields:truncated?["explanation","collections"]:[]}}}export{PM_COMMAND_OUTPUT_BUDGET_CONTRACTS,PM_DIAGNOSTIC_DEGRADATION_STEPS,PM_DIAGNOSTIC_OUTPUT_BUDGET_CONTRACTS,PM_DIAGNOSTIC_OUTPUT_CLASSES,PM_OUTPUT_BUDGET_CLASSES,PM_OUTPUT_DEGRADATION_STEPS,createPmCommandOutputBudget,definePmCommandOutputBudget,estimatePmOutputTokens,inferPmOutputBudgetClass,projectPmDiagnosticOutput,projectPmDiagnosticText,resolvePmCommandOutputBudget,resolvePmDiagnosticOutputBudget};
 //# sourceMappingURL=agent-output-contracts.js.map
-//# debugId=1d338971-5a60-5b4e-b4c8-0705c8e8c98c

package/dist/sdk/cli-contracts/bootstrap-command-scanner.js

@@ -1,80 +1,2 @@
-/**
- * @module sdk/cli-contracts/bootstrap-command-scanner
- *
- * Resolves command position from shell-free argv without loading CLI runtime
- * normalization, error, filesystem, or item-addressing dependencies.
- */
-/** Global options that consume a following value when one is present. */
-
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="9d04e30a-caf5-59b4-8853-9df39c1728aa")}catch(e){}}();
-export const GLOBAL_VALUE_CONSUMING_FLAGS = new Set([
-    "--pm-path",
-    "--path",
-    "--author",
-    "--output-include",
-    "--output-limit",
-    "--output-budget",
-    "--output-format",
-    "--output-session",
-    "--output-cursor",
-]);
-/** Boolean global options ignored while locating the command token. */
-export const BOOTSTRAP_BOOLEAN_FLAGS = new Set([
-    "--no-extensions",
-    "--no-pager",
-    "--json",
-    "--quiet",
-    "--lean",
-    "--token-accounting",
-    "--output-row-contract",
-    "--all",
-]);
-/** Whether a global value-consuming flag uses its inline `--flag=value` form. */
-export function isInlineGlobalValueToken(token) {
-    const equalsIndex = token.indexOf("=");
-    return (equalsIndex > 0 &&
-        GLOBAL_VALUE_CONSUMING_FLAGS.has(token.slice(0, equalsIndex)));
-}
-/** Whether a bootstrap value flag consumes its following token. */
-export function consumesBootstrapValue(flag, next) {
-    if (typeof next !== "string")
-        return false;
-    return flag === "--path" || flag === "--pm-path" || !next.startsWith("-");
-}
-/**
- * Locate the first command token after global flags and their values.
- *
- * A leading `--` terminates command discovery. Unknown flags are ignored so
- * later command-specific validation can return the canonical diagnostic.
- */
-export function findBootstrapCommandTokenIndex(argv) {
-    for (let index = 0; index < argv.length; index += 1) {
-        const token = argv[index];
-        if (token === "--") {
-            return undefined;
-        }
-        if (GLOBAL_VALUE_CONSUMING_FLAGS.has(token)) {
-            index += consumesBootstrapValue(token, argv[index + 1]) ? 1 : 0;
-            continue;
-        }
-        if (isInlineGlobalValueToken(token) ||
-            BOOTSTRAP_BOOLEAN_FLAGS.has(token) ||
-            token === "--profile" ||
-            token === "--id-only" ||
-            token === "--explain") {
-            continue;
-        }
-        if (token.startsWith("-")) {
-            continue;
-        }
-        return index;
-    }
-    return undefined;
-}
-/** Resolve the normalized command name from shell-free invocation arguments. */
-export function parseBootstrapCommandName(argv) {
-    const index = findBootstrapCommandTokenIndex(argv);
-    return index === undefined ? undefined : argv[index].trim().toLowerCase();
-}
+!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b18eefc1-0d1d-5c9c-b98a-b96771070301")}catch(e2){}})();const GLOBAL_VALUE_CONSUMING_FLAGS=new Set(["--pm-path","--path","--author","--output-include","--output-limit","--output-budget","--output-format","--output-session","--output-cursor"]);const BOOTSTRAP_BOOLEAN_FLAGS=new Set(["--no-extensions","--no-pager","--json","--quiet","--lean","--token-accounting","--output-row-contract","--all"]);function isInlineGlobalValueToken(token){const equalsIndex=token.indexOf("=");return equalsIndex>0&&GLOBAL_VALUE_CONSUMING_FLAGS.has(token.slice(0,equalsIndex))}function consumesBootstrapValue(flag,next){if(typeof next!=="string")return false;return flag==="--path"||flag==="--pm-path"||!next.startsWith("-")}function findBootstrapCommandTokenIndex(argv){for(let index=0;index<argv.length;index+=1){const token=argv[index];if(token==="--"){return void 0}if(GLOBAL_VALUE_CONSUMING_FLAGS.has(token)){index+=consumesBootstrapValue(token,argv[index+1])?1:0;continue}if(isInlineGlobalValueToken(token)||BOOTSTRAP_BOOLEAN_FLAGS.has(token)||token==="--profile"||token==="--id-only"||token==="--explain"){continue}if(token.startsWith("-")){continue}return index}return void 0}function parseBootstrapCommandName(argv){const index=findBootstrapCommandTokenIndex(argv);return index===void 0?void 0:argv[index].trim().toLowerCase()}export{BOOTSTRAP_BOOLEAN_FLAGS,GLOBAL_VALUE_CONSUMING_FLAGS,consumesBootstrapValue,findBootstrapCommandTokenIndex,isInlineGlobalValueToken,parseBootstrapCommandName};
 //# sourceMappingURL=bootstrap-command-scanner.js.map
-//# debugId=9d04e30a-caf5-59b4-8853-9df39c1728aa

package/dist/sdk/cli-contracts/command-aliases.d.ts

@@ -26,6 +26,10 @@ export interface PmCommandAliasContract {
     /** PM item that owns the compatibility disposition. */
     owner: string;
 }
+/** History namespace aliases preserve the existing SDK and MCP operation identities. */
+export declare const PM_HISTORY_COMMAND_ALIASES: readonly PmCommandAliasContract[];
+/** Resolve a native history leaf to its stable SDK operation; other paths retain their identity. */
+export declare function resolvePmHistoryOperation(command: string): string;
 /**
  * Public command-alias table. Deprecated aliases must remain executable but
  * are intentionally absent from default help and completion discovery.