@unbrained/pm-cli 2026.10.31 → 2026.11.2

package/dist/sdk/lifecycle/claim.d.ts

@@ -1,4 +1,6 @@
 import { type GlobalOptions } from "../runtime-primitives.js";
+import type { ItemMetadata,PmSettings } from "../../types/index.js";
+import type { RuntimeStatusRegistry } from "../../core/schema/runtime-schema.js";
 import { type NextRecommendation,type NextOptions } from "../query/next.js";
 /** Stable warning/error code for an exhausted atomic next-work walk. */
 export declare const NO_AVAILABLE_NEXT_ITEM_CODE = "no_available_next_item";
@@ -18,6 +20,15 @@ forced:boolean;
 skipped?:boolean;
 /** Value that configures or reports warnings for this contract. */
 warnings?:string[];
+/** Lifecycle transition applied inside the claim's locked mutation when `start` was requested. */
+start?:ClaimStartReceipt;
+}
+/** Status transition recorded by a claim that also started its item. */
+export interface ClaimStartReceipt {
+/** Lifecycle status observed under the item lock before the claim. */
+from_status:string;
+/** Configured in-progress status the claimed item now carries. */
+to_status:string;
 }
 /** Result of atomically selecting and claiming the next caller-available item. */
 export interface ClaimNextAvailableResult extends ClaimResult {
@@ -90,6 +101,13 @@ message?:string;
 ifAvailable?:boolean;
 /** Maximum ranked candidates attempted by `claim --next`. */
 maxAttempts?:string | number;
+/**
+     * Move the claimed item to the configured in-progress status in the same locked
+     * mutation and history event. `runClaimNext` uses this for `claim --next --start`.
+     * The explicit-item `claim <id> --start` and `runStartTask` keep their documented
+     * claim-then-update composition and do not pass it.
+     */
+start?:boolean;
 }
 /** Documents the release mutation options payload exchanged by command, SDK, and package integrations. */
 export interface ReleaseMutationOptions extends ClaimMutationOptions {
@@ -100,6 +118,15 @@ pause?:boolean;
 }
 /** Implements run claim for the public runtime surface of this module. */
 export declare function runClaim(id:string,force:boolean,global:GlobalOptions,options?:ClaimMutationOptions):Promise<ClaimResult>;
+/** Stable warning when session attribution could not be recorded for a claim that already committed. */
+export declare const CLAIM_ATTRIBUTION_UNRECORDED_WARNING = "claim_semantic_attribution_unrecorded";
+/** Enforce the claim target XOR selection contract; refusals never ask for a flag the caller already passed. */
+export declare function requireClaimTarget(id:string | undefined,next:boolean,start?:boolean):void;
+/** Advance a just-claimed item to the in-progress status under the claim's lock, enforcing configured type workflows. */
+export declare function applyClaimStart(metadata:ItemMetadata,start:boolean,settings:PmSettings,registry:RuntimeStatusRegistry):Pick<ClaimResult,"start"> & {
+changedFields:string[];
+warnings:string[];
+};
 /** Selects ranked actionable work and claims the first candidate still available under the item lock. Conflicts caused by parallel claimers advance to the next candidate instead of returning a thundering-herd failure. */
 export declare function runClaimNext(force:boolean,global:GlobalOptions,options?:ClaimMutationOptions,nextOptions?:NextOptions):Promise<ClaimNextResult>;
 /** Parses the bounded candidate walk used by `claim --next`. */

package/dist/sdk/lifecycle/claim.js

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="45460a47-04ea-5d4d-be5d-d815cb78c0e8")}catch{}})();import{assertInitializedTracker}from"../environment/tracker-preflight.js";import{resolveRuntimeStatusRegistry,statusIsTerminal,EXIT_CODE,PmCliError,toItemRecord,mutateItem,resolvePmRoot,readSettings,resolveAuthor,resolveClaimPrincipal,normalizeStatusForRegistry}from"../runtime-primitives.js";import{wrapOwnershipConflict}from"../annotations.js";import{resolveItemOwnershipConflict}from"../ownership-source.js";import{applyReleaseHandoff,resolveReleaseHandoff}from"./release-handoff.js";import{runNext}from"../query/next.js";import{recordClaimSemanticAttribution,recordReleaseSemanticAttribution}from"../context/semantic-session-attribution.js";const NO_AVAILABLE_NEXT_ITEM_CODE="no_available_next_item";function isAlreadyClaimedError(error){if(!(error instanceof Error)||error.name!=="PmCliError")return!1;const context=error.context;return typeof context=="object"&&context!==null&&"code"in context&&context.code==="already_claimed_by"}async function runClaim(id,force,global2,options={}){const pmRoot=resolvePmRoot(process.cwd(),global2.path);await assertInitializedTracker(pmRoot);const settings=await readSettings(pmRoot),statusRegistry=resolveRuntimeStatusRegistry(settings.schema),author=resolveAuthor(options.author,settings.author_default),claimPrincipal=resolveClaimPrincipal(author);let previousAssignee=null,skipped=!1;const mutationWarnings=[],result=await mutateItem({pmRoot,settings,id,op:"claim",author,message:options.message,force,skipNoop:!0,async mutate(document){const currentAssigneeText=document.metadata.assignee??"",currentClaimPrincipal=document.metadata.claim_principal?.trim()||currentAssigneeText;if(previousAssignee=currentAssigneeText.trim().length>0?currentAssigneeText:null,statusIsTerminal(document.metadata.status,statusRegistry)&&!force)throw new PmCliError(`Cannot claim terminal item ${document.metadata.id} without --force`,EXIT_CODE.CONFLICT);if(previousAssignee!==null&&currentClaimPrincipal!==claimPrincipal){if(options.ifAvailable===!0)return skipped=!0,mutationWarnings.push(`claim_skipped_held_by:${previousAssignee}`),{changedFields:[]};if(!force){const ownership2=await resolveItemOwnershipConflict(pmRoot,document.metadata.id,currentAssigneeText);throw new PmCliError(`Item ${document.metadata.id} is already ${ownership2.phrase}. Use --force to take over, or --if-available to skip without failing.`,EXIT_CODE.CONFLICT,{code:"already_claimed_by",item_id:document.metadata.id,claimed_by:ownership2.holder,claimed_at:ownership2.since,claim_source:ownership2.source,why:"Claim is an atomic test-and-set so parallel agents never proceed believing they own the same item.",nextSteps:["Run pm next to pick a different unclaimed item.","Re-run with --if-available to treat a held item as a no-op skip.","Re-run with --force only when taking over the item is coordinated."]})}mutationWarnings.push(`claim_takeover:${previousAssignee}->${author}`)}const ownership={assignee:author,claim_principal:claimPrincipal},changedFields=["assignee","claim_principal"].filter(field=>document.metadata[field]!==ownership[field]);return Object.assign(document.metadata,ownership),{changedFields,warnings:mutationWarnings}}});return skipped||await recordClaimSemanticAttribution({pmRoot,settings,principal:claimPrincipal,itemId:result.item.id}),{item:toItemRecord(result.item),changed_fields:result.changedFields,claimed_by:skipped&&previousAssignee!==null?previousAssignee:author,previous_assignee:previousAssignee,forced:force,...skipped?{skipped:!0}:{},...mutationWarnings.length>0?{warnings:mutationWarnings}:{}}}async function runClaimNext(force,global2,options={},nextOptions={}){const maxAttempts=parseClaimNextAttempts(options.maxAttempts),settings=await readSettings(resolvePmRoot(process.cwd(),global2.path)),claimOptions={...options,author:resolveAuthor(options.author,settings.author_default)},next=await runNext({...nextOptions,callerAuthor:claimOptions.author,limit:String(maxAttempts)},global2),recommendations=[next.recommended,...next.ready].filter(entry=>entry!==null).map(entry=>({...entry,reasons:"reasons"in entry?entry.reasons:["ranked ready candidate"]}));return claimNextFromRecommendations(recommendations.slice(0,maxAttempts),force,global2,claimOptions)}function parseClaimNextAttempts(raw){if(raw===void 0)return 10;const parsed=Number(raw);if(!Number.isSafeInteger(parsed)||parsed<1||parsed>100)throw new PmCliError("--max-attempts must be an integer from 1 to 100",EXIT_CODE.USAGE);return parsed}async function claimNextFromRecommendations(recommendations,force,global2,options={},claimRunner=runClaim){let attempts=0;for(const recommendation of recommendations){attempts+=1;try{const claimed=await claimRunner(recommendation.id,force,global2,options),result={...claimed,recommendation,attempts,available:!0};if(!claimed.skipped)return result}catch(error){if(!isAlreadyClaimedError(error))throw error}}if(options.ifAvailable===!0)return{available:!1,item:null,claimed_by:resolveAuthor(options.author,""),previous_assignee:null,forced:force,skipped:!0,recommendation:null,attempts,warnings:[NO_AVAILABLE_NEXT_ITEM_CODE]};const noCandidatesMatched=attempts===0;throw new PmCliError(noCandidatesMatched?"No actionable items matched the selection filters":"No actionable item remained available to claim",noCandidatesMatched?EXIT_CODE.NOT_FOUND:EXIT_CODE.CONFLICT,{code:NO_AVAILABLE_NEXT_ITEM_CODE,why:noCandidatesMatched?"No ready items matched the specified filters or selection criteria.":"Every ranked candidate was claimed by another agent before this atomic selection completed.",nextSteps:[noCandidatesMatched?"Verify the filters or run pm next to inspect all ready work.":"Run pm claim --next again to refresh the ranked candidate set."]})}async function runRelease(id,force,global2,options={}){const pmRoot=resolvePmRoot(process.cwd(),global2.path);await assertInitializedTracker(pmRoot);const settings=await readSettings(pmRoot),author=resolveAuthor(options.author,settings.author_default),claimPrincipal=resolveClaimPrincipal(author),ownershipReleaseBypass=options.ownershipReleaseBypass===!0;let previousAssignee=null;const statusRegistry=resolveRuntimeStatusRegistry(settings.schema),handoffStatus=resolveReleaseHandoff(options,statusRegistry);if(handoffStatus!==void 0&&ownershipReleaseBypass)throw new PmCliError("Ownership-release bypass only clears ownership; it cannot change a handoff status.",EXIT_CODE.USAGE);let handoff,result;try{result=await mutateItem({pmRoot,settings,id,op:"release",author,message:options.message,force,bypassAssigneeConflict:ownershipReleaseBypass,mutate(document){previousAssignee=document.metadata.assignee??null;const transition=handoffStatus===void 0?void 0:applyReleaseHandoff(document.metadata,handoffStatus,settings,statusRegistry,options.message);return handoff=transition?.receipt,!previousAssignee&&!document.metadata.claim_principal?{changedFields:[]}:(delete document.metadata.assignee,delete document.metadata.claim_principal,{changedFields:["assignee","claim_principal",...transition?.changedFields??[]],warnings:transition?.warnings})}})}catch(error){wrapOwnershipConflict(error,{required:"For approved non-owner handoffs, prefer the ownership-release bypass before considering --force.",examples:['pm release pm-a1b2 --author "reviewer" --force'],nextSteps:["Use the package-provided ownership-release bypass for handoffs that only clear assignee metadata.","Use --force only when an explicit override is approved for broader ownership conflicts."]})}await recordReleaseSemanticAttribution({pmRoot,principal:claimPrincipal,itemId:result.item.id});const stillInProgress=normalizeStatusForRegistry(result.item.status,statusRegistry)===normalizeStatusForRegistry(statusRegistry.in_progress_status,statusRegistry);return{item:toItemRecord(result.item),released_by:author,changed_fields:result.changedFields,previous_assignee:previousAssignee,forced:force,...handoff===void 0?{}:{handoff},...result.warnings.length>0||stillInProgress?{warnings:[...result.warnings,...stillInProgress?["released_unclaimed_in_progress"]:[]]}:{},...stillInProgress?{suggestions:[`${result.item.id} remains ${result.item.status} and unclaimed. If work is paused, run pm release ${result.item.id} --pause to move it to ${statusRegistry.open_status}.`]}:{}}}export{NO_AVAILABLE_NEXT_ITEM_CODE,claimNextFromRecommendations,isAlreadyClaimedError,parseClaimNextAttempts,runClaim,runClaimNext,runRelease};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f5335488-184f-5938-a61a-b3fd26fbf3e3")}catch{}})();import{assertInitializedTracker}from"../environment/tracker-preflight.js";import{resolveRuntimeStatusRegistry,statusIsTerminal,EXIT_CODE,PmCliError,toItemRecord,mutateItem,resolvePmRoot,readSettings,resolveAuthor,resolveClaimPrincipal,normalizeStatusForRegistry}from"../runtime-primitives.js";import{wrapOwnershipConflict}from"../annotations.js";import{resolveItemOwnershipConflict}from"../ownership-source.js";import{applyReleaseHandoff,resolveReleaseHandoff}from"./release-handoff.js";import{enforceTypeWorkflowTransition}from"./workflow-transition.js";import{resolveTypeWorkflows}from"../../core/schema/type-workflows.js";import{resolveStartTaskInProgressStatus}from"../start-task-status.js";import{runNext}from"../query/next.js";import{recordClaimSemanticAttribution,recordReleaseSemanticAttribution}from"../context/semantic-session-attribution.js";const NO_AVAILABLE_NEXT_ITEM_CODE="no_available_next_item";function isAlreadyClaimedError(error){if(!(error instanceof Error)||error.name!=="PmCliError")return!1;const context=error.context;return typeof context=="object"&&context!==null&&"code"in context&&context.code==="already_claimed_by"}async function runClaim(id,force,global2,options={}){const pmRoot=resolvePmRoot(process.cwd(),global2.path);await assertInitializedTracker(pmRoot);const settings=await readSettings(pmRoot),statusRegistry=resolveRuntimeStatusRegistry(settings.schema),author=resolveAuthor(options.author,settings.author_default),claimPrincipal=resolveClaimPrincipal(author);let previousAssignee=null,skipped=!1,startEvidence={};const mutationWarnings=[],result=await mutateItem({pmRoot,settings,id,op:"claim",author,message:options.message,force,skipNoop:!0,async mutate(document){const currentAssigneeText=document.metadata.assignee??"",currentClaimPrincipal=document.metadata.claim_principal?.trim()||currentAssigneeText;if(previousAssignee=currentAssigneeText.trim().length>0?currentAssigneeText:null,statusIsTerminal(document.metadata.status,statusRegistry)&&!force)throw new PmCliError(`Cannot claim terminal item ${document.metadata.id} without --force`,EXIT_CODE.CONFLICT);if(previousAssignee!==null&&currentClaimPrincipal!==claimPrincipal){if(options.ifAvailable===!0)return skipped=!0,mutationWarnings.push(`claim_skipped_held_by:${previousAssignee}`),{changedFields:[]};if(!force){const ownership2=await resolveItemOwnershipConflict(pmRoot,document.metadata.id,currentAssigneeText);throw new PmCliError(`Item ${document.metadata.id} is already ${ownership2.phrase}. Use --force to take over, or --if-available to skip without failing.`,EXIT_CODE.CONFLICT,{code:"already_claimed_by",item_id:document.metadata.id,claimed_by:ownership2.holder,claimed_at:ownership2.since,claim_source:ownership2.source,why:"Claim is an atomic test-and-set so parallel agents never proceed believing they own the same item.",nextSteps:["Run pm next to pick a different unclaimed item.","Re-run with --if-available to treat a held item as a no-op skip.","Re-run with --force only when taking over the item is coordinated."]})}mutationWarnings.push(`claim_takeover:${previousAssignee}->${author}`)}const ownership={assignee:author,claim_principal:claimPrincipal},changedFields=["assignee","claim_principal"].filter(field=>document.metadata[field]!==ownership[field]);Object.assign(document.metadata,ownership);const{changedFields:startedFields,warnings:startWarnings,...started}=applyClaimStart(document.metadata,options.start===!0,settings,statusRegistry);return startEvidence=started,mutationWarnings.push(...startWarnings),{changedFields:[...changedFields,...startedFields],warnings:mutationWarnings}}});return skipped||mutationWarnings.push(...await recordClaimAttributionAfterCommit({pmRoot,settings,principal:claimPrincipal,itemId:result.item.id})),{item:toItemRecord(result.item),changed_fields:result.changedFields,claimed_by:skipped&&previousAssignee!==null?previousAssignee:author,previous_assignee:previousAssignee,forced:force,...skipped?{skipped:!0}:{},...mutationWarnings.length>0?{warnings:mutationWarnings}:{},...startEvidence}}const CLAIM_ATTRIBUTION_UNRECORDED_WARNING="claim_semantic_attribution_unrecorded";async function recordClaimAttributionAfterCommit(params){try{return await recordClaimSemanticAttribution(params),[]}catch{return[CLAIM_ATTRIBUTION_UNRECORDED_WARNING]}}function requireClaimTarget(id,next,start=!1){const startSuffix=start?" --start":"";if(!next&&!id)throw new PmCliError(start?"pm claim --start needs an item id, or --next to start the next available item":"Specify an item id or pass --next",EXIT_CODE.USAGE,{code:"missing_required_argument",field:"id",required:"Pass an item id, or --next to select the next available item.",nextSteps:[`Retry as pm claim <id>${startSuffix}, or pm claim --next${startSuffix}.`]});if(next&&id)throw new PmCliError("Specify either an item id or --next, not both",EXIT_CODE.USAGE,{code:"ambiguous_option_combination",required:"Pass either an item id or --next.",nextSteps:[`Retry as pm claim ${id}${startSuffix} to claim that item, or drop the id to select with --next.`]})}function applyClaimStart(metadata,start,settings,registry){if(!start)return{changedFields:[],warnings:[]};if(statusIsTerminal(metadata.status,registry))throw new PmCliError(`Cannot start terminal item ${metadata.id}; reopen it with pm item reopen before starting it`,EXIT_CODE.CONFLICT,{code:"terminal_state_conflict",item_id:metadata.id,why:"Starting work moves an active item into progress; a terminal item must be reopened so its recurrence evidence is recorded.",nextSteps:[`Run pm item reopen ${metadata.id} "<reason>", then pm claim ${metadata.id} --start.`]});const startStatus=resolveStartTaskInProgressStatus(registry),enforcement=settings.governance.workflow_enforcement??"off",warning=enforceTypeWorkflowTransition({enforcement,typeWorkflows:enforcement==="off"?[]:resolveTypeWorkflows(settings.schema),statusRegistry:registry,typeName:metadata.type,fromStatus:metadata.status,toStatus:startStatus}),receipt={from_status:metadata.status,to_status:startStatus},changedFields=metadata.status===startStatus?[]:["status"];return metadata.status=startStatus,{start:receipt,changedFields,warnings:warning?[warning]:[]}}async function runClaimNext(force,global2,options={},nextOptions={}){const maxAttempts=parseClaimNextAttempts(options.maxAttempts),settings=await readSettings(resolvePmRoot(process.cwd(),global2.path)),claimOptions={...options,author:resolveAuthor(options.author,settings.author_default)},next=await runNext({...nextOptions,callerAuthor:claimOptions.author,limit:String(maxAttempts)},global2),recommendations=[next.recommended,...next.ready].filter(entry=>entry!==null).map(entry=>({...entry,reasons:"reasons"in entry?entry.reasons:["ranked ready candidate"]}));return claimNextFromRecommendations(recommendations.slice(0,maxAttempts),force,global2,claimOptions)}function parseClaimNextAttempts(raw){if(raw===void 0)return 10;const parsed=Number(raw);if(!Number.isSafeInteger(parsed)||parsed<1||parsed>100)throw new PmCliError("--max-attempts must be an integer from 1 to 100",EXIT_CODE.USAGE);return parsed}async function claimNextFromRecommendations(recommendations,force,global2,options={},claimRunner=runClaim){let attempts=0;for(const recommendation of recommendations){attempts+=1;try{const claimed=await claimRunner(recommendation.id,force,global2,options),result={...claimed,recommendation,attempts,available:!0};if(!claimed.skipped)return result}catch(error){if(!isAlreadyClaimedError(error))throw error}}if(options.ifAvailable===!0)return{available:!1,item:null,claimed_by:resolveAuthor(options.author,""),previous_assignee:null,forced:force,skipped:!0,recommendation:null,attempts,warnings:[NO_AVAILABLE_NEXT_ITEM_CODE]};const noCandidatesMatched=attempts===0;throw new PmCliError(noCandidatesMatched?"No actionable items matched the selection filters":"No actionable item remained available to claim",noCandidatesMatched?EXIT_CODE.NOT_FOUND:EXIT_CODE.CONFLICT,{code:NO_AVAILABLE_NEXT_ITEM_CODE,why:noCandidatesMatched?"No ready items matched the specified filters or selection criteria.":"Every ranked candidate was claimed by another agent before this atomic selection completed.",nextSteps:[noCandidatesMatched?"Verify the filters or run pm next to inspect all ready work.":"Run pm claim --next again to refresh the ranked candidate set."]})}async function runRelease(id,force,global2,options={}){const pmRoot=resolvePmRoot(process.cwd(),global2.path);await assertInitializedTracker(pmRoot);const settings=await readSettings(pmRoot),author=resolveAuthor(options.author,settings.author_default),claimPrincipal=resolveClaimPrincipal(author),ownershipReleaseBypass=options.ownershipReleaseBypass===!0;let previousAssignee=null;const statusRegistry=resolveRuntimeStatusRegistry(settings.schema),handoffStatus=resolveReleaseHandoff(options,statusRegistry);if(handoffStatus!==void 0&&ownershipReleaseBypass)throw new PmCliError("Ownership-release bypass only clears ownership; it cannot change a handoff status.",EXIT_CODE.USAGE);let handoff,result;try{result=await mutateItem({pmRoot,settings,id,op:"release",author,message:options.message,force,bypassAssigneeConflict:ownershipReleaseBypass,mutate(document){previousAssignee=document.metadata.assignee??null;const transition=handoffStatus===void 0?void 0:applyReleaseHandoff(document.metadata,handoffStatus,settings,statusRegistry,options.message);return handoff=transition?.receipt,!previousAssignee&&!document.metadata.claim_principal?{changedFields:[]}:(delete document.metadata.assignee,delete document.metadata.claim_principal,{changedFields:["assignee","claim_principal",...transition?.changedFields??[]],warnings:transition?.warnings})}})}catch(error){wrapOwnershipConflict(error,{required:"For approved non-owner handoffs, prefer the ownership-release bypass before considering --force.",examples:['pm release pm-a1b2 --author "reviewer" --force'],nextSteps:["Use the package-provided ownership-release bypass for handoffs that only clear assignee metadata.","Use --force only when an explicit override is approved for broader ownership conflicts."]})}await recordReleaseSemanticAttribution({pmRoot,principal:claimPrincipal,itemId:result.item.id});const stillInProgress=normalizeStatusForRegistry(result.item.status,statusRegistry)===normalizeStatusForRegistry(statusRegistry.in_progress_status,statusRegistry);return{item:toItemRecord(result.item),released_by:author,changed_fields:result.changedFields,previous_assignee:previousAssignee,forced:force,...handoff===void 0?{}:{handoff},...result.warnings.length>0||stillInProgress?{warnings:[...result.warnings,...stillInProgress?["released_unclaimed_in_progress"]:[]]}:{},...stillInProgress?{suggestions:[`${result.item.id} remains ${result.item.status} and unclaimed. If work is paused, run pm release ${result.item.id} --pause to move it to ${statusRegistry.open_status}.`]}:{}}}export{CLAIM_ATTRIBUTION_UNRECORDED_WARNING,NO_AVAILABLE_NEXT_ITEM_CODE,applyClaimStart,claimNextFromRecommendations,isAlreadyClaimedError,parseClaimNextAttempts,requireClaimTarget,runClaim,runClaimNext,runRelease};
 //# sourceMappingURL=claim.js.map

package/dist/sdk/lifecycle/mcp-actions.d.ts

@@ -12,7 +12,7 @@ force?:boolean;
 /** Presentation-neutral global command options. */
 global:GlobalOptions;
 }
-/** Dispatch explicit and ranked claims through the same compact receipt contract. */
+/** Dispatch explicit, ranked and ranked-start claims through the same compact receipt contract. */
 export declare function runMcpClaimAction(context:LifecycleMutationActionContext):Promise<unknown>;
 /** Dispatch close through the shared MCP mutation compaction contract. */
 export declare function runMcpCloseAction(context:LifecycleMutationActionContext):Promise<unknown>;

package/dist/sdk/lifecycle/mcp-actions.js

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="04780b9d-76a4-544a-9341-7aa56c1e451b")}catch{}})();import{projectMutationResult}from"../../core/output/mutation-projection.js";import{PmCliError}from"../../core/shared/errors.js";import{runClose}from"./close.js";import{runReopen}from"./reopen.js";import{runClaim,runClaimNext,runRelease}from"./claim.js";import{runStartTask,runPauseTask,runCloseTask}from"./task-composition.js";import{readRuntimeString,withMutationCompaction,mutationOptionsWithOverrides}from"../runtime-input.js";async function runMcpClaimAction(context){const{changedFields,idOnly,runnerOptions}=withMutationCompaction(context.args,context.options),force=context.force===!0||runnerOptions.force===!0,selectionOptions={...context.args,...runnerOptions};if(selectionOptions.start===!0)return runMcpTaskCompositionAction(context,"start_task");const result=context.args.next===!0||runnerOptions.next===!0?await runClaimNext(force,context.global,selectionOptions,selectionOptions):await runClaim(requireLifecycleItemId(context,runnerOptions),force,context.global,selectionOptions);return projectMutationResult(result,{changedFields,compactEnvelope:changedFields==="compact"&&!idOnly,idOnly})}function requireLifecycleItemId(context,options){const id=context.id??readRuntimeString(options,"id");if(!id)throw new PmCliError("Missing required argument: id",64);return id}function readLifecycleReason(context,options){return readRuntimeString(context.args,"reason")??readRuntimeString(context.args,"text")??readRuntimeString(options,"reason")??readRuntimeString(options,"text")}async function runMcpCloseAction(context){const{changedFields,idOnly,runnerOptions}=withMutationCompaction(context.args,context.options);return runnerOptions.releaseAssignment===!0?runMcpTaskCompositionAction(context,"close_task"):projectMutationResult(await runClose(requireLifecycleItemId(context,runnerOptions),readLifecycleReason(context,runnerOptions),{...runnerOptions,force:context.force===!0||runnerOptions.force===!0},context.global),{changedFields,compactEnvelope:changedFields==="compact"&&!idOnly,idOnly})}async function runMcpTaskCompositionAction(context,action){const{changedFields,idOnly,runnerOptions}=withMutationCompaction(context.args,context.options),id=requireLifecycleItemId(context,runnerOptions),options=mutationOptionsWithOverrides(runnerOptions,{force:context.force===!0||runnerOptions.force===!0}),result=action==="start_task"?await runStartTask(id,options,context.global):action==="pause_task"?await runPauseTask(id,options,context.global):await runCloseTask(id,readLifecycleReason(context,runnerOptions),options,context.global);return projectMutationResult(result,{changedFields,idOnly,compactEnvelope:changedFields==="compact"&&!idOnly})}async function runMcpReleaseAction(context){const{changedFields,idOnly,runnerOptions}=withMutationCompaction(context.args,context.options),options=mutationOptionsWithOverrides(runnerOptions,{message:readRuntimeString(Object.hasOwn(runnerOptions,"message")?runnerOptions:context.args,"message")});if(options.pause===!0)return runMcpTaskCompositionAction({...context,options},"pause_task");const result=await runRelease(requireLifecycleItemId(context,options),context.force===!0||options.force===!0,context.global,options);return projectMutationResult(result,{changedFields,idOnly,compactEnvelope:changedFields==="compact"&&!idOnly})}async function runMcpReopenAction(context){const{changedFields,idOnly,runnerOptions}=withMutationCompaction(context.args,context.options);return projectMutationResult(await runReopen(requireLifecycleItemId(context,runnerOptions),readLifecycleReason(context,runnerOptions)??"",{...runnerOptions,force:context.force===!0||runnerOptions.force===!0},context.global),{changedFields,compactEnvelope:changedFields==="compact"&&!idOnly,idOnly})}export{runMcpClaimAction,runMcpCloseAction,runMcpReleaseAction,runMcpReopenAction,runMcpTaskCompositionAction};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="513b9fa5-5887-5d96-a137-ddf961f37dc8")}catch{}})();import{projectMutationResult}from"../../core/output/mutation-projection.js";import{PmCliError}from"../../core/shared/errors.js";import{runClose}from"./close.js";import{runReopen}from"./reopen.js";import{requireClaimTarget,runClaim,runClaimNext,runRelease}from"./claim.js";import{runStartTask,runPauseTask,runCloseTask}from"./task-composition.js";import{readRuntimeString,withMutationCompaction,mutationOptionsWithOverrides}from"../runtime-input.js";async function runMcpClaimAction(context){const{changedFields,idOnly,runnerOptions}=withMutationCompaction(context.args,context.options),force=context.force===!0||runnerOptions.force===!0,selectionOptions={...context.args,...runnerOptions},next=runnerOptions.next===!0,id=context.id??readRuntimeString(runnerOptions,"id");if(selectionOptions.start===!0){if(id)return runMcpTaskCompositionAction(context,"start_task");requireClaimTarget(id,next,!0)}const result=next?await runClaimNext(force,context.global,selectionOptions,selectionOptions):await runClaim(requireLifecycleItemId(context,runnerOptions),force,context.global,selectionOptions);return projectMutationResult(result,{changedFields,compactEnvelope:changedFields==="compact"&&!idOnly,idOnly})}function requireLifecycleItemId(context,options){const id=context.id??readRuntimeString(options,"id");if(!id)throw new PmCliError("Missing required argument: id",64);return id}function readLifecycleReason(context,options){return readRuntimeString(context.args,"reason")??readRuntimeString(context.args,"text")??readRuntimeString(options,"reason")??readRuntimeString(options,"text")}async function runMcpCloseAction(context){const{changedFields,idOnly,runnerOptions}=withMutationCompaction(context.args,context.options);return runnerOptions.releaseAssignment===!0?runMcpTaskCompositionAction(context,"close_task"):projectMutationResult(await runClose(requireLifecycleItemId(context,runnerOptions),readLifecycleReason(context,runnerOptions),{...runnerOptions,force:context.force===!0||runnerOptions.force===!0},context.global),{changedFields,compactEnvelope:changedFields==="compact"&&!idOnly,idOnly})}async function runMcpTaskCompositionAction(context,action){const{changedFields,idOnly,runnerOptions}=withMutationCompaction(context.args,context.options),id=requireLifecycleItemId(context,runnerOptions),options=mutationOptionsWithOverrides(runnerOptions,{force:context.force===!0||runnerOptions.force===!0}),result=action==="start_task"?await runStartTask(id,options,context.global):action==="pause_task"?await runPauseTask(id,options,context.global):await runCloseTask(id,readLifecycleReason(context,runnerOptions),options,context.global);return projectMutationResult(result,{changedFields,idOnly,compactEnvelope:changedFields==="compact"&&!idOnly})}async function runMcpReleaseAction(context){const{changedFields,idOnly,runnerOptions}=withMutationCompaction(context.args,context.options),options=mutationOptionsWithOverrides(runnerOptions,{message:readRuntimeString(Object.hasOwn(runnerOptions,"message")?runnerOptions:context.args,"message")});if(options.pause===!0)return runMcpTaskCompositionAction({...context,options},"pause_task");const result=await runRelease(requireLifecycleItemId(context,options),context.force===!0||options.force===!0,context.global,options);return projectMutationResult(result,{changedFields,idOnly,compactEnvelope:changedFields==="compact"&&!idOnly})}async function runMcpReopenAction(context){const{changedFields,idOnly,runnerOptions}=withMutationCompaction(context.args,context.options);return projectMutationResult(await runReopen(requireLifecycleItemId(context,runnerOptions),readLifecycleReason(context,runnerOptions)??"",{...runnerOptions,force:context.force===!0||runnerOptions.force===!0},context.global),{changedFields,compactEnvelope:changedFields==="compact"&&!idOnly,idOnly})}export{runMcpClaimAction,runMcpCloseAction,runMcpReleaseAction,runMcpReopenAction,runMcpTaskCompositionAction};
 //# sourceMappingURL=mcp-actions.js.map

package/dist/sdk/lifecycle/task-composition.js

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="23f3ce6b-d536-5df2-92b1-ec756d53aa02")}catch{}})();import{PmCliError}from"../../core/shared/errors.js";import{EXIT_CODE}from"../../core/shared/constants.js";import{resolveRuntimeStatusRegistry}from"../../core/schema/runtime-schema.js";import{resolvePmRoot}from"../../core/store/paths.js";import{readSettings}from"../../core/store/settings.js";import{runClaim,runRelease}from"./claim.js";import{resolveReleaseHandoff}from"./release-handoff.js";import{runClose}from"./close.js";import{runUpdate}from"./update.js";import{resolveStartTaskInProgressStatus}from"../start-task-status.js";import{mutationOptionsWithOverrides}from"../runtime-input.js";async function finishComposition(id,completed,operation){try{return await operation()}catch(error){const context=error instanceof PmCliError?error.context:{},failure=new PmCliError(error instanceof Error?error.message:String(error),error instanceof PmCliError?error.exitCode:EXIT_CODE.GENERIC_FAILURE,{...context,item_id:id,why:`${completed} completed for ${id} before the following step failed. No rollback was performed.${context.why?` ${context.why}`:""}`,nextSteps:[`Inspect the persisted state with pm get ${id} and pm history ${id} before retrying the failed step.`,...context.nextSteps??[]]});throw failure.cause=error,failure}}async function runStartTask(id,options,global2){if(options.next===!0||options.ifAvailable===!0)throw new PmCliError("--start cannot be combined with --next or --if-available for an explicit item",EXIT_CODE.USAGE,{code:"invalid_argument_value",required:"Remove --next and --if-available when starting an explicit item.",nextSteps:["Remove --next and --if-available, keep the explicit item ID and other supplied arguments, then retry."]});const settings=await readSettings(resolvePmRoot(process.cwd(),global2.path)),status=resolveStartTaskInProgressStatus(resolveRuntimeStatusRegistry(settings.schema)),claim=await runClaim(id,options.force===!0,global2,options),canonicalId=claim.item.id,update=await finishComposition(canonicalId,"claim",()=>runUpdate(canonicalId,mutationOptionsWithOverrides(options,{status},["assignee","start","next","ifAvailable","maxAttempts"]),global2));return{id:canonicalId,action:"start_task",claim,update}}async function runPauseTask(id,options,global2){const settings=await readSettings(resolvePmRoot(process.cwd(),global2.path)),registry=resolveRuntimeStatusRegistry(settings.schema);resolveReleaseHandoff({...options,pause:!0},registry);const status=registry.open_status,update=await runUpdate(id,mutationOptionsWithOverrides(options,{status},["assignee","pause"]),global2),canonicalId=update.item.id,release=await finishComposition(canonicalId,"update",()=>runRelease(canonicalId,options.force===!0,global2,options));return{id:canonicalId,action:"pause_task",update,release}}async function runCloseTask(id,reason,options,global2){const close=await runClose(id,reason,options,global2),canonicalId=close.item.id,release=await finishComposition(canonicalId,"close",()=>runRelease(canonicalId,options.force===!0,global2,options));return{id:canonicalId,action:"close_task",close,release}}export{finishComposition,runCloseTask,runPauseTask,runStartTask};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="09bc9af5-45aa-5935-b627-cdef92af2acf")}catch{}})();import{PmCliError}from"../../core/shared/errors.js";import{EXIT_CODE}from"../../core/shared/constants.js";import{resolveRuntimeStatusRegistry}from"../../core/schema/runtime-schema.js";import{resolvePmRoot}from"../../core/store/paths.js";import{readSettings}from"../../core/store/settings.js";import{runClaim,runRelease}from"./claim.js";import{resolveReleaseHandoff}from"./release-handoff.js";import{runClose}from"./close.js";import{runUpdate}from"./update.js";import{resolveStartTaskInProgressStatus}from"../start-task-status.js";import{mutationOptionsWithOverrides}from"../runtime-input.js";async function finishComposition(id,completed,operation){try{return await operation()}catch(error){const context=error instanceof PmCliError?error.context:{},failure=new PmCliError(error instanceof Error?error.message:String(error),error instanceof PmCliError?error.exitCode:EXIT_CODE.GENERIC_FAILURE,{...context,item_id:id,why:`${completed} completed for ${id} before the following step failed. No rollback was performed.${context.why?` ${context.why}`:""}`,nextSteps:[`Inspect the persisted state with pm get ${id} and pm history ${id} before retrying the failed step.`,...context.nextSteps??[]]});throw failure.cause=error,failure}}async function runStartTask(id,options,global2){if(options.next===!0||options.ifAvailable===!0)throw new PmCliError("--start cannot be combined with --next or --if-available for an explicit item",EXIT_CODE.USAGE,{code:"invalid_argument_value",required:"Remove --next and --if-available when starting an explicit item.",nextSteps:["Remove --next and --if-available, keep the explicit item ID and other supplied arguments, then retry."]});const settings=await readSettings(resolvePmRoot(process.cwd(),global2.path)),status=resolveStartTaskInProgressStatus(resolveRuntimeStatusRegistry(settings.schema)),claim=await runClaim(id,options.force===!0,global2,mutationOptionsWithOverrides(options,{},["start"])),canonicalId=claim.item.id,update=await finishComposition(canonicalId,"claim",()=>runUpdate(canonicalId,mutationOptionsWithOverrides(options,{status},["assignee","start","next","ifAvailable","maxAttempts"]),global2));return{id:canonicalId,action:"start_task",claim,update}}async function runPauseTask(id,options,global2){const settings=await readSettings(resolvePmRoot(process.cwd(),global2.path)),registry=resolveRuntimeStatusRegistry(settings.schema);resolveReleaseHandoff({...options,pause:!0},registry);const status=registry.open_status,update=await runUpdate(id,mutationOptionsWithOverrides(options,{status},["assignee","pause"]),global2),canonicalId=update.item.id,release=await finishComposition(canonicalId,"update",()=>runRelease(canonicalId,options.force===!0,global2,options));return{id:canonicalId,action:"pause_task",update,release}}async function runCloseTask(id,reason,options,global2){const close=await runClose(id,reason,options,global2),canonicalId=close.item.id,release=await finishComposition(canonicalId,"close",()=>runRelease(canonicalId,options.force===!0,global2,options));return{id:canonicalId,action:"close_task",close,release}}export{finishComposition,runCloseTask,runPauseTask,runStartTask};
 //# sourceMappingURL=task-composition.js.map

package/dist/sdk/mcp/discovery.js

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="837ee381-0838-55d3-bcdf-7352fb76661d")}catch{}})();import{createHash,createHmac,randomBytes,timingSafeEqual}from"node:crypto";import{PM_COMMAND_CAPABILITY_CONTRACTS,PM_MCP_TOOL_COMMAND_CONTRACTS,resolvePmCommandCapabilityFamily,resolvePmCommandVisibilityTier}from"../agent-capability-contracts.js";import{PmCliError}from"../runtime-primitives.js";const PM_MCP_PROGRESSIVE_DISCOVERY_EXTENSION="dev.unbrained.pm/progressive-tool-discovery",PM_MCP_PROGRESSIVE_DISCOVERY_SERVER_CAPABILITY=Object.freeze({version:1,discoveryTool:"pm_discover",canonicalResult:"structuredContent.result",compatibilityText:"pointer"}),PM_MCP_ENTRY_TOOL_NAMES=Object.freeze(["pm_discover","pm_next","pm_context","pm_search","pm_get"]),DISCOVERY_WEIGHTS=Object.freeze({lexical:.4,semantic:.2,graph:.1,permission:.15,freshness:.05,usage:.1}),DISCOVERY_CACHE_INVALIDATIONS=Object.freeze(["profile_changed","tool_contract_changed","workspace_extension_changed","authorization_changed","ranking_signal_changed","cursor_integrity_key_rotated"]),TIER_RANK={core:0,standard:1,full:2,internal:3},SELECTABLE_TIERS=Object.freeze(["core","standard","full"]),MCP_TOOL_PROFILES=new Set(["core","standard","full","custom"]),CAPABILITY_FAMILIES=new Set(PM_COMMAND_CAPABILITY_CONTRACTS.map(({family})=>family)),PROCESS_CURSOR_INTEGRITY_KEY=randomBytes(32);function boundedDiscoveryString(value,field){if(typeof value!="string")throw new PmCliError(`pm tool discovery ${field} must be a string of at most 4096 Unicode characters.`,64);const iterator=value[Symbol.iterator]();let count=0;for(let next=iterator.next();!next.done;next=iterator.next())if(count+=1,count>4096)throw new PmCliError(`pm tool discovery ${field} must be a string of at most 4096 Unicode characters.`,64);return value}function discoveryLimit(value){if(!Number.isInteger(value)||Number(value)<1||Number(value)>100)throw new PmCliError("pm tool discovery limit must be from 1 through 100.",64);return Number(value)}function discoveryOutputBudget(value){if(value!=="unbounded"&&(!Number.isInteger(value)||Number(value)<128))throw new PmCliError("pm tool discovery outputBudget must be unbounded or an integer of at least 128.",64);return value==="unbounded"?value:Number(value)}function discoveryIncludeSchema(value){if(value!==void 0&&typeof value!="boolean")throw new PmCliError("pm tool discovery includeSchema must be a boolean.",64);return value===!0}function validateDiscoveryOptionsContainer(value){if(value===null||typeof value!="object"||Array.isArray(value))throw new PmCliError("pm tool discovery options must be an object.",64)}function validateDiscoveryCandidates(candidates){if(!Array.isArray(candidates))throw new PmCliError("pm tool discovery candidates must be an array.",64);for(const[index,candidate]of candidates.entries()){if(candidate===null||typeof candidate!="object"||Array.isArray(candidate))throw new PmCliError(`pm tool discovery candidate ${index} must be an object.`,64);if(typeof candidate.name!="string"||candidate.name.trim().length===0)throw new PmCliError(`pm tool discovery candidate ${index} name must be a non-empty string.`,64);if(typeof candidate.description!="string"||candidate.description.trim().length===0)throw new PmCliError(`pm tool discovery candidate ${index} description must be a non-empty string.`,64);if(candidate.inputSchema===null||typeof candidate.inputSchema!="object"||Array.isArray(candidate.inputSchema))throw new PmCliError(`pm tool discovery candidate ${index} inputSchema must be an object.`,64);if(candidate.authorized!==void 0&&typeof candidate.authorized!="boolean")throw new PmCliError(`pm tool discovery candidate ${index} authorized must be a boolean.`,64)}}function parsePmToolDiscoveryOptions(input){if(validateDiscoveryOptionsContainer(input),input.family!==void 0&&(typeof input.family!="string"||!CAPABILITY_FAMILIES.has(input.family)))throw new PmCliError("pm tool discovery family must be a declared capability family.",64);if(input.tier!==void 0&&(typeof input.tier!="string"||!SELECTABLE_TIERS.includes(input.tier)))throw new PmCliError("pm tool discovery tier must be core, standard, or full.",64);return{...input.query!==void 0?{query:boundedDiscoveryString(input.query,"query")}:{},...input.family!==void 0?{family:input.family}:{},...input.tier!==void 0?{tier:input.tier}:{},...input.limit!==void 0?{limit:discoveryLimit(input.limit)}:{},...input.cursor!==void 0?{cursor:boundedDiscoveryString(input.cursor,"cursor")}:{},...input.includeSchema!==void 0?{includeSchema:discoveryIncludeSchema(input.includeSchema)}:{},...input.outputBudget!==void 0?{outputBudget:discoveryOutputBudget(input.outputBudget)}:{}}}function normalizedUnitInterval(value){return value===void 0||!Number.isFinite(value)?0:Math.min(1,Math.max(0,value))}function normalizedSearchTokens(value){return[...new Set(value.toLowerCase().match(/[a-z0-9]+/gu)??[])].sort()}function lexicalRelevance(query,text){const queryTokens=normalizedSearchTokens(query);if(queryTokens.length===0)return 0;const targetTokens=new Set(normalizedSearchTokens(text)),matched=queryTokens.filter(token=>targetTokens.has(token)).length,exactBonus=text.toLowerCase().includes(query.toLowerCase())?.25:0;return Math.min(1,matched/queryTokens.length+exactBonus)}function semanticRelevance(query,text){const queryTokens=normalizedSearchTokens(query);if(queryTokens.length===0)return 0;const target=text.toLowerCase(),targetTokens=normalizedSearchTokens(text),related=queryTokens.filter(queryToken=>targetTokens.some(targetToken=>targetToken.startsWith(queryToken)||queryToken.startsWith(targetToken))).length,phraseBonus=target.includes(query.toLowerCase())?.2:0;return Math.min(1,related/queryTokens.length+phraseBonus)}function hashDiscoveryValue(value){return createHash("sha256").update(JSON.stringify(value)).digest("hex").slice(0,24)}function cursorSignature(fingerprint,offset,integrityKey){return createHmac("sha256",integrityKey).update(JSON.stringify({version:1,fingerprint,offset})).digest("base64url")}function encodeDiscoveryCursor(fingerprint,offset,integrityKey){const cursor={version:1,offset,signature:cursorSignature(fingerprint,offset,integrityKey)};return Buffer.from(JSON.stringify(cursor),"utf8").toString("base64url")}function decodeDiscoveryCursor(value,fingerprint,total,integrityKey){if(value===void 0)return 0;try{const decoded=JSON.parse(Buffer.from(value,"base64url").toString("utf8"));if(decoded.version!==1||!Number.isInteger(decoded.offset)||(decoded.offset??-1)<0||Number(decoded.offset)>total||typeof decoded.signature!="string")throw new Error("cursor fields do not match the request");const expectedSignature=Buffer.from(cursorSignature(fingerprint,decoded.offset,integrityKey),"base64url"),suppliedSignature=Buffer.from(decoded.signature,"base64url");if(suppliedSignature.length!==expectedSignature.length||!timingSafeEqual(suppliedSignature,expectedSignature))throw new Error("cursor signature does not match the request");return decoded.offset}catch(error){throw new PmCliError("Invalid or stale pm tool discovery cursor; restart discovery without cursor.",64,{reason:String(error)})}}function appliedSignal(value,weight,source){return{value:normalizedUnitInterval(value),weight,available:source!=="unavailable",source}}function hostOrComputedSignal(hostValue,computedValue,weight){return appliedSignal(hostValue??computedValue,weight,hostValue===void 0?"computed":"host")}function buildRankedRow(candidate,query,includeSchema){const command=Object.hasOwn(PM_MCP_TOOL_COMMAND_CONTRACTS,candidate.name)?PM_MCP_TOOL_COMMAND_CONTRACTS[candidate.name]:"help",family=resolvePmCommandCapabilityFamily(command),searchableText=`${candidate.name} ${candidate.description} ${command} ${family}`,lexical=lexicalRelevance(query,searchableText),queryTokens=new Set(normalizedSearchTokens(query)),signals={lexical:appliedSignal(lexical,DISCOVERY_WEIGHTS.lexical,"computed"),semantic:hostOrComputedSignal(candidate.signals?.semantic,semanticRelevance(query,searchableText),DISCOVERY_WEIGHTS.semantic),graph:hostOrComputedSignal(candidate.signals?.graph,queryTokens.has(family)||queryTokens.has(command)?1:0,DISCOVERY_WEIGHTS.graph),permission:appliedSignal(1,DISCOVERY_WEIGHTS.permission,"authorization"),freshness:hostOrComputedSignal(candidate.signals?.freshness,1,DISCOVERY_WEIGHTS.freshness),usage:hostOrComputedSignal(candidate.signals?.usage,PM_MCP_ENTRY_TOOL_NAMES.includes(candidate.name)?1:0,DISCOVERY_WEIGHTS.usage)},score=Object.values(signals).reduce((total,signal)=>total+signal.value*signal.weight,0);return{name:candidate.name,description:candidate.description,command,tier:resolvePmCommandVisibilityTier(command),family,score:Number(score.toFixed(6)),signals,...includeSchema?{input_schema:structuredClone(candidate.inputSchema)}:{}}}function validateDiscoveryFilters(options){if(options.cursorIntegrityKey!==void 0&&(!(options.cursorIntegrityKey instanceof Uint8Array)||options.cursorIntegrityKey.byteLength<32))throw new PmCliError("pm tool discovery cursorIntegrityKey must contain at least 32 bytes.",64);if(options.tier!==void 0&&(typeof options.tier!="string"||!SELECTABLE_TIERS.includes(options.tier)))throw new PmCliError("pm tool discovery tier must be core, standard, or full.",64);if(options.family!==void 0&&(typeof options.family!="string"||!CAPABILITY_FAMILIES.has(options.family)))throw new PmCliError("pm tool discovery family must be a declared capability family.",64);if(options.profile!==void 0&&(typeof options.profile!="string"||!MCP_TOOL_PROFILES.has(options.profile)))throw new PmCliError("pm tool discovery profile must be core, standard, full, or custom.",64)}function resolveDiscoveryRequest(options){const query=boundedDiscoveryString(options.query===void 0?"":options.query,"query").trim().replace(/\s+/gu," ");boundedDiscoveryString(options.cursor===void 0?"":options.cursor,"cursor");const limit=discoveryLimit(options.limit===void 0?10:options.limit),budget=discoveryOutputBudget(options.outputBudget===void 0?1200:options.outputBudget);return validateDiscoveryFilters(options),{query,includeSchema:discoveryIncludeSchema(options.includeSchema),limit,budget,maximumTier:TIER_RANK[options.tier??"full"],profile:options.profile===void 0?"core":options.profile}}function estimateDiscoveryResultTokens(resultWithoutCost,budget,serializedToolRowsBytes){const toolRowsBytes=serializedToolRowsBytes??resultWithoutCost.tools.reduce((total,row,index)=>total+(index===0?0:1)+Buffer.byteLength(JSON.stringify(row),"utf8"),0),emptyToolsResult={...resultWithoutCost,tools:[]};let estimatedTokens=0;for(let iteration=0;iteration<4;iteration+=1){const envelopeBytes=Buffer.byteLength(JSON.stringify({...emptyToolsResult,token_cost:{estimated_tokens:estimatedTokens,budget,within_budget:!0}}),"utf8"),nextEstimate=Math.ceil((envelopeBytes+toolRowsBytes)/4);if(nextEstimate===estimatedTokens)break;estimatedTokens=nextEstimate}return estimatedTokens}function rankedDiscoveryRows(candidates,options,request){return candidates.filter(candidate=>candidate.authorized!==!1).map(candidate=>buildRankedRow(candidate,request.query,request.includeSchema)).filter(row=>row.tier!=="internal"&&TIER_RANK[row.tier]<=request.maximumTier&&(options.family===void 0||row.family===options.family)).sort((left,right)=>right.score-left.score||(left.name<right.name?-1:left.name>right.name?1:0))}function rowsWithinDiscoveryBudget(candidates,budget,buildResultWithoutCost){if(budget==="unbounded")return[...candidates];const selected=[];let serializedToolRowsBytes=0;for(const[index,row]of candidates.entries()){const candidateRowsBytes=serializedToolRowsBytes+(index===0?0:1)+Buffer.byteLength(JSON.stringify(row),"utf8");if(estimateDiscoveryResultTokens(buildResultWithoutCost(index+1),budget,candidateRowsBytes)>budget)break;selected.push(row),serializedToolRowsBytes=candidateRowsBytes}return selected}function discoverPmTools(candidates,options={}){validateDiscoveryCandidates(candidates),validateDiscoveryOptionsContainer(options);const request=resolveDiscoveryRequest(options),cursorIntegrityKey=options.cursorIntegrityKey??PROCESS_CURSOR_INTEGRITY_KEY,ranked=rankedDiscoveryRows(candidates,options,request),fingerprint=hashDiscoveryValue({query:request.query,family:options.family??null,tier:options.tier??"full",includeSchema:request.includeSchema,profile:request.profile,ranked}),offset=decodeDiscoveryCursor(options.cursor,fingerprint,ranked.length,cursorIntegrityKey),pageCandidates=ranked.slice(offset,offset+request.limit),omitted=[];request.includeSchema||omitted.push({name:"input_schema",reason:"compact_projection",restore_with:"Set includeSchema=true."}),offset+request.limit<ranked.length&&omitted.push({name:"tools",reason:"limit",restore_with:"Continue with next_cursor or increase limit."});const base={result_type:"pm_tool_discovery",contract_version:1,query:request.query,profile:request.profile,total:ranked.length,ranking_policy:{version:1,formula:"weighted_sum_then_name",weights:DISCOVERY_WEIGHTS},cache:{key:hashDiscoveryValue({fingerprint,cursorIntegrityKey:createHash("sha256").update(cursorIntegrityKey).digest("hex"),limit:request.limit,offset,budget:request.budget}),ttl_ms:3e4,scope:"private",invalidates_on:DISCOVERY_CACHE_INVALIDATIONS}},buildResultWithoutCost=(selected2,selectedCount=selected2.length)=>{const endOffset=offset+selectedCount,hasMore=endOffset<ranked.length,resultOmissions=[...omitted];return selectedCount<pageCandidates.length&&resultOmissions.push({name:"tools",reason:"token_budget",restore_with:"Continue with next_cursor or increase outputBudget."}),{...base,tools:[...selected2],returned:selectedCount,has_more:hasMore,...hasMore?{next_cursor:encodeDiscoveryCursor(fingerprint,endOffset,cursorIntegrityKey)}:{},omission_receipt:{has_omissions:resultOmissions.length>0,omitted:resultOmissions}}},buildResult=selected2=>{const resultWithoutCost=buildResultWithoutCost(selected2),estimatedTokens=estimateDiscoveryResultTokens(resultWithoutCost,request.budget);return{...resultWithoutCost,token_cost:{estimated_tokens:estimatedTokens,budget:request.budget,within_budget:request.budget==="unbounded"||estimatedTokens<=request.budget}}},selected=rowsWithinDiscoveryBudget(pageCandidates,request.budget,selectedCount=>buildResultWithoutCost([],selectedCount)),result=buildResult(selected);if(pageCandidates.length>0&&selected.length===0){const oneRowCost=buildResult([pageCandidates[0]]).token_cost.estimated_tokens;throw new PmCliError(`pm tool discovery outputBudget is too small to return a tool; increase it to at least ${oneRowCost}.`,64,{required:String(oneRowCost)})}if(request.budget!=="unbounded"&&result.token_cost.estimated_tokens>request.budget)throw new PmCliError(`pm tool discovery outputBudget is too small; at least ${result.token_cost.estimated_tokens} estimated tokens are required for this page.`,64,{required:String(result.token_cost.estimated_tokens)});return result}export{PM_MCP_ENTRY_TOOL_NAMES,PM_MCP_PROGRESSIVE_DISCOVERY_EXTENSION,PM_MCP_PROGRESSIVE_DISCOVERY_SERVER_CAPABILITY,discoverPmTools,parsePmToolDiscoveryOptions};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="98283845-5c48-5901-b54c-c8cc8138427b")}catch{}})();import{createHash,createHmac,randomBytes,timingSafeEqual}from"node:crypto";import{PM_COMMAND_CAPABILITY_CONTRACTS,PM_MCP_TOOL_COMMAND_CONTRACTS,resolvePmCommandCapabilityFamily,resolvePmCommandVisibilityTier}from"../agent-capability-contracts.js";import{PmCliError}from"../runtime-primitives.js";const PM_MCP_PROGRESSIVE_DISCOVERY_EXTENSION="dev.unbrained.pm/progressive-tool-discovery",PM_MCP_PROGRESSIVE_DISCOVERY_SERVER_CAPABILITY=Object.freeze({version:1,discoveryTool:"pm_discover",canonicalResult:"structuredContent.result",compatibilityText:"pointer"}),PM_MCP_ENTRY_TOOL_NAMES=Object.freeze(["pm_discover","pm_next","pm_context","pm_search","pm_get"]),DISCOVERY_WEIGHTS=Object.freeze({lexical:.4,semantic:.2,graph:.1,permission:.15,freshness:.05,usage:.1}),DISCOVERY_CACHE_INVALIDATIONS=Object.freeze(["profile_changed","tool_contract_changed","workspace_extension_changed","authorization_changed","ranking_signal_changed","cursor_integrity_key_rotated"]),TIER_RANK={core:0,standard:1,full:2,internal:3},SELECTABLE_TIERS=Object.freeze(["core","standard","full"]),MCP_TOOL_PROFILES=new Set(["core","standard","full","custom"]),CAPABILITY_FAMILIES=new Set(PM_COMMAND_CAPABILITY_CONTRACTS.map(({family})=>family)),PROCESS_CURSOR_INTEGRITY_KEY=randomBytes(32);function boundedDiscoveryString(value,field){if(typeof value!="string")throw new PmCliError(`pm tool discovery ${field} must be a string of at most 4096 Unicode characters.`,64);const iterator=value[Symbol.iterator]();let count=0;for(let next=iterator.next();!next.done;next=iterator.next())if(count+=1,count>4096)throw new PmCliError(`pm tool discovery ${field} must be a string of at most 4096 Unicode characters.`,64);return value}function discoveryLimit(value){if(!Number.isInteger(value)||Number(value)<1||Number(value)>100)throw new PmCliError("pm tool discovery limit must be from 1 through 100.",64);return Number(value)}function discoveryOutputBudget(value){if(value!=="unbounded"&&(!Number.isInteger(value)||Number(value)<128))throw new PmCliError("pm tool discovery outputBudget must be unbounded or an integer of at least 128.",64);return value==="unbounded"?value:Number(value)}function discoveryIncludeSchema(value){if(value!==void 0&&typeof value!="boolean")throw new PmCliError("pm tool discovery includeSchema must be a boolean.",64);return value===!0}function validateDiscoveryOptionsContainer(value){if(value===null||typeof value!="object"||Array.isArray(value))throw new PmCliError("pm tool discovery options must be an object.",64)}function validateDiscoveryCandidates(candidates){if(!Array.isArray(candidates))throw new PmCliError("pm tool discovery candidates must be an array.",64);for(const[index,candidate]of candidates.entries()){if(candidate===null||typeof candidate!="object"||Array.isArray(candidate))throw new PmCliError(`pm tool discovery candidate ${index} must be an object.`,64);if(typeof candidate.name!="string"||candidate.name.trim().length===0)throw new PmCliError(`pm tool discovery candidate ${index} name must be a non-empty string.`,64);if(typeof candidate.description!="string"||candidate.description.trim().length===0)throw new PmCliError(`pm tool discovery candidate ${index} description must be a non-empty string.`,64);if(candidate.inputSchema===null||typeof candidate.inputSchema!="object"||Array.isArray(candidate.inputSchema))throw new PmCliError(`pm tool discovery candidate ${index} inputSchema must be an object.`,64);if(candidate.authorized!==void 0&&typeof candidate.authorized!="boolean")throw new PmCliError(`pm tool discovery candidate ${index} authorized must be a boolean.`,64)}}function parsePmToolDiscoveryOptions(input){if(validateDiscoveryOptionsContainer(input),input.family!==void 0&&(typeof input.family!="string"||!CAPABILITY_FAMILIES.has(input.family)))throw new PmCliError("pm tool discovery family must be a declared capability family.",64);if(input.tier!==void 0&&(typeof input.tier!="string"||!SELECTABLE_TIERS.includes(input.tier)))throw new PmCliError("pm tool discovery tier must be core, standard, or full.",64);return{...input.query!==void 0?{query:boundedDiscoveryString(input.query,"query")}:{},...input.family!==void 0?{family:input.family}:{},...input.tier!==void 0?{tier:input.tier}:{},...input.limit!==void 0?{limit:discoveryLimit(input.limit)}:{},...input.cursor!==void 0?{cursor:boundedDiscoveryString(input.cursor,"cursor")}:{},...input.includeSchema!==void 0?{includeSchema:discoveryIncludeSchema(input.includeSchema)}:{},...input.outputBudget!==void 0?{outputBudget:discoveryOutputBudget(input.outputBudget)}:{}}}function normalizedUnitInterval(value){return value===void 0||!Number.isFinite(value)?0:Math.min(1,Math.max(0,value))}function normalizedSearchTokens(value){return[...new Set(value.toLowerCase().match(/[a-z0-9]+/gu)??[])].sort()}function lexicalRelevance(query,text){const queryTokens=normalizedSearchTokens(query);if(queryTokens.length===0)return 0;const targetTokens=new Set(normalizedSearchTokens(text)),matched=queryTokens.filter(token=>targetTokens.has(token)).length,exactBonus=text.toLowerCase().includes(query.toLowerCase())?.25:0;return Math.min(1,matched/queryTokens.length+exactBonus)}function semanticRelevance(query,text){const queryTokens=normalizedSearchTokens(query);if(queryTokens.length===0)return 0;const target=text.toLowerCase(),targetTokens=normalizedSearchTokens(text),related=queryTokens.filter(queryToken=>targetTokens.some(targetToken=>targetToken.startsWith(queryToken)||queryToken.startsWith(targetToken))).length,phraseBonus=target.includes(query.toLowerCase())?.2:0;return Math.min(1,related/queryTokens.length+phraseBonus)}function hashDiscoveryValue(value){return createHash("sha256").update(JSON.stringify(value)).digest("hex").slice(0,24)}function cursorSignature(fingerprint,offset,integrityKey){return createHmac("sha256",integrityKey).update(JSON.stringify({version:1,fingerprint,offset})).digest("base64url")}function encodeDiscoveryCursor(fingerprint,offset,integrityKey){const cursor={version:1,offset,signature:cursorSignature(fingerprint,offset,integrityKey)};return Buffer.from(JSON.stringify(cursor),"utf8").toString("base64url")}function decodeDiscoveryCursor(value,fingerprint,total,integrityKey){if(value===void 0)return 0;try{const decoded=JSON.parse(Buffer.from(value,"base64url").toString("utf8")),offset=decoded.offset;if(decoded.version!==1||typeof offset!="number"||!Number.isInteger(offset)||offset<0||offset>total||typeof decoded.signature!="string")throw new Error("cursor fields do not match the request");const expectedSignature=Buffer.from(cursorSignature(fingerprint,offset,integrityKey),"base64url"),suppliedSignature=Buffer.from(decoded.signature,"base64url");if(suppliedSignature.length!==expectedSignature.length||!timingSafeEqual(suppliedSignature,expectedSignature))throw new Error("cursor signature does not match the request");return offset}catch(error){throw new PmCliError("Invalid or stale pm tool discovery cursor; restart discovery without cursor.",64,{reason:String(error)})}}function appliedSignal(value,weight,source){return{value:normalizedUnitInterval(value),weight,available:source!=="unavailable",source}}function hostOrComputedSignal(hostValue,computedValue,weight){return appliedSignal(hostValue??computedValue,weight,hostValue===void 0?"computed":"host")}function buildRankedRow(candidate,query,includeSchema){const command=Object.hasOwn(PM_MCP_TOOL_COMMAND_CONTRACTS,candidate.name)?PM_MCP_TOOL_COMMAND_CONTRACTS[candidate.name]:"help",family=resolvePmCommandCapabilityFamily(command),searchableText=`${candidate.name} ${candidate.description} ${command} ${family}`,lexical=lexicalRelevance(query,searchableText),queryTokens=new Set(normalizedSearchTokens(query)),signals={lexical:appliedSignal(lexical,DISCOVERY_WEIGHTS.lexical,"computed"),semantic:hostOrComputedSignal(candidate.signals?.semantic,semanticRelevance(query,searchableText),DISCOVERY_WEIGHTS.semantic),graph:hostOrComputedSignal(candidate.signals?.graph,queryTokens.has(family)||queryTokens.has(command)?1:0,DISCOVERY_WEIGHTS.graph),permission:appliedSignal(1,DISCOVERY_WEIGHTS.permission,"authorization"),freshness:hostOrComputedSignal(candidate.signals?.freshness,1,DISCOVERY_WEIGHTS.freshness),usage:hostOrComputedSignal(candidate.signals?.usage,PM_MCP_ENTRY_TOOL_NAMES.includes(candidate.name)?1:0,DISCOVERY_WEIGHTS.usage)},score=Object.values(signals).reduce((total,signal)=>total+signal.value*signal.weight,0);return{name:candidate.name,description:candidate.description,command,tier:resolvePmCommandVisibilityTier(command),family,score:Number(score.toFixed(6)),signals,...includeSchema?{input_schema:structuredClone(candidate.inputSchema)}:{}}}function validateDiscoveryFilters(options){if(options.cursorIntegrityKey!==void 0&&(!(options.cursorIntegrityKey instanceof Uint8Array)||options.cursorIntegrityKey.byteLength<32))throw new PmCliError("pm tool discovery cursorIntegrityKey must contain at least 32 bytes.",64);if(options.tier!==void 0&&(typeof options.tier!="string"||!SELECTABLE_TIERS.includes(options.tier)))throw new PmCliError("pm tool discovery tier must be core, standard, or full.",64);if(options.family!==void 0&&(typeof options.family!="string"||!CAPABILITY_FAMILIES.has(options.family)))throw new PmCliError("pm tool discovery family must be a declared capability family.",64);if(options.profile!==void 0&&(typeof options.profile!="string"||!MCP_TOOL_PROFILES.has(options.profile)))throw new PmCliError("pm tool discovery profile must be core, standard, full, or custom.",64)}function resolveDiscoveryRequest(options){const query=boundedDiscoveryString(options.query===void 0?"":options.query,"query").trim().replace(/\s+/gu," ");boundedDiscoveryString(options.cursor===void 0?"":options.cursor,"cursor");const limit=discoveryLimit(options.limit===void 0?10:options.limit),budget=discoveryOutputBudget(options.outputBudget===void 0?1200:options.outputBudget);return validateDiscoveryFilters(options),{query,includeSchema:discoveryIncludeSchema(options.includeSchema),limit,budget,maximumTier:TIER_RANK[options.tier??"full"],profile:options.profile===void 0?"core":options.profile}}function estimateDiscoveryResultTokens(resultWithoutCost,budget,serializedToolRowsBytes){const toolRowsBytes=serializedToolRowsBytes??resultWithoutCost.tools.reduce((total,row,index)=>total+(index===0?0:1)+Buffer.byteLength(JSON.stringify(row),"utf8"),0),emptyToolsResult={...resultWithoutCost,tools:[]};let estimatedTokens=0;for(let iteration=0;iteration<4;iteration+=1){const envelopeBytes=Buffer.byteLength(JSON.stringify({...emptyToolsResult,token_cost:{estimated_tokens:estimatedTokens,budget,within_budget:!0}}),"utf8"),nextEstimate=Math.ceil((envelopeBytes+toolRowsBytes)/4);if(nextEstimate===estimatedTokens)break;estimatedTokens=nextEstimate}return estimatedTokens}function rankedDiscoveryRows(candidates,options,request){return candidates.filter(candidate=>candidate.authorized!==!1).map(candidate=>buildRankedRow(candidate,request.query,request.includeSchema)).filter(row=>row.tier!=="internal"&&TIER_RANK[row.tier]<=request.maximumTier&&(options.family===void 0||row.family===options.family)).sort((left,right)=>right.score-left.score||(left.name<right.name?-1:left.name>right.name?1:0))}function rowsWithinDiscoveryBudget(candidates,budget,buildResultWithoutCost){if(budget==="unbounded")return[...candidates];const selected=[];let serializedToolRowsBytes=0;for(const[index,row]of candidates.entries()){const candidateRowsBytes=serializedToolRowsBytes+(index===0?0:1)+Buffer.byteLength(JSON.stringify(row),"utf8");if(estimateDiscoveryResultTokens(buildResultWithoutCost(index+1),budget,candidateRowsBytes)>budget)break;selected.push(row),serializedToolRowsBytes=candidateRowsBytes}return selected}function discoverPmTools(candidates,options={}){validateDiscoveryCandidates(candidates),validateDiscoveryOptionsContainer(options);const request=resolveDiscoveryRequest(options),cursorIntegrityKey=options.cursorIntegrityKey??PROCESS_CURSOR_INTEGRITY_KEY,ranked=rankedDiscoveryRows(candidates,options,request),fingerprint=hashDiscoveryValue({query:request.query,family:options.family??null,tier:options.tier??"full",includeSchema:request.includeSchema,profile:request.profile,ranked}),offset=decodeDiscoveryCursor(options.cursor,fingerprint,ranked.length,cursorIntegrityKey),pageCandidates=ranked.slice(offset,offset+request.limit),omitted=[];request.includeSchema||omitted.push({name:"input_schema",reason:"compact_projection",restore_with:"Set includeSchema=true."}),offset+request.limit<ranked.length&&omitted.push({name:"tools",reason:"limit",restore_with:"Continue with next_cursor or increase limit."});const base={result_type:"pm_tool_discovery",contract_version:1,query:request.query,profile:request.profile,total:ranked.length,ranking_policy:{version:1,formula:"weighted_sum_then_name",weights:DISCOVERY_WEIGHTS},cache:{key:hashDiscoveryValue({fingerprint,cursorIntegrityKey:createHash("sha256").update(cursorIntegrityKey).digest("hex"),limit:request.limit,offset,budget:request.budget}),ttl_ms:3e4,scope:"private",invalidates_on:DISCOVERY_CACHE_INVALIDATIONS}},buildResultWithoutCost=(selected2,selectedCount=selected2.length)=>{const endOffset=offset+selectedCount,hasMore=endOffset<ranked.length,resultOmissions=[...omitted];return selectedCount<pageCandidates.length&&resultOmissions.push({name:"tools",reason:"token_budget",restore_with:"Continue with next_cursor or increase outputBudget."}),{...base,tools:[...selected2],returned:selectedCount,has_more:hasMore,...hasMore?{next_cursor:encodeDiscoveryCursor(fingerprint,endOffset,cursorIntegrityKey)}:{},omission_receipt:{has_omissions:resultOmissions.length>0,omitted:resultOmissions}}},buildResult=selected2=>{const resultWithoutCost=buildResultWithoutCost(selected2),estimatedTokens=estimateDiscoveryResultTokens(resultWithoutCost,request.budget);return{...resultWithoutCost,token_cost:{estimated_tokens:estimatedTokens,budget:request.budget,within_budget:request.budget==="unbounded"||estimatedTokens<=request.budget}}},selected=rowsWithinDiscoveryBudget(pageCandidates,request.budget,selectedCount=>buildResultWithoutCost([],selectedCount)),result=buildResult(selected);if(pageCandidates.length>0&&selected.length===0){const oneRowCost=buildResult([pageCandidates[0]]).token_cost.estimated_tokens;throw new PmCliError(`pm tool discovery outputBudget is too small to return a tool; increase it to at least ${oneRowCost}.`,64,{required:String(oneRowCost)})}if(request.budget!=="unbounded"&&result.token_cost.estimated_tokens>request.budget)throw new PmCliError(`pm tool discovery outputBudget is too small; at least ${result.token_cost.estimated_tokens} estimated tokens are required for this page.`,64,{required:String(result.token_cost.estimated_tokens)});return result}export{PM_MCP_ENTRY_TOOL_NAMES,PM_MCP_PROGRESSIVE_DISCOVERY_EXTENSION,PM_MCP_PROGRESSIVE_DISCOVERY_SERVER_CAPABILITY,discoverPmTools,parsePmToolDiscoveryOptions};
 //# sourceMappingURL=discovery.js.map

package/dist/sdk/output/list-envelope.d.ts

@@ -5,3 +5,11 @@
  * JSON hosts should retain the original result when full receipts are required.
  */
 export declare function projectPmBriefListEnvelope(value:unknown):unknown;
+/**
+ * Compact a standard search page without mutating its typed SDK result:
+ * drops `truncated` when it repeats `has_more`, a `filters.limit` echo of
+ * `applied_limit`, and the single default `projection_metadata` omission
+ * receipt in favour of `details: "--full"`. Custom, partial and inconsistent
+ * receipts pass through unchanged; JSON hosts should keep the original result.
+ */
+export declare function projectPmBriefSearchEnvelope(value:unknown):unknown;

package/dist/sdk/output/list-envelope.js

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="95103919-d686-5c3b-bd51-928f5b2314ef")}catch{}})();import{BRIEF_LIST_FIELDS}from"../query/projection-contracts.js";function isRecord(value){return value!==null&&typeof value=="object"&&!Array.isArray(value)}function hasStandardBriefProjection(value){if(!isRecord(value))return!1;const fields=value.fields;return value.mode==="brief"&&Object.keys(value).length===2&&Array.isArray(fields)&&(fields.length===BRIEF_LIST_FIELDS.length||fields.length===BRIEF_LIST_FIELDS.length+1&&fields.at(-1)==="priority")&&BRIEF_LIST_FIELDS.every((field,index)=>fields[index]===field)}function hasStandardPagination(value,count){return typeof value.has_more=="boolean"&&value.truncated===value.has_more&&value.count===count&&typeof value.total=="number"&&Number.isSafeInteger(value.total)&&(value.has_more?value.total>count&&typeof value.next_cursor=="string"&&value.next_cursor.length>0:value.total===count&&value.next_cursor==null)}function hasCompactibleSource(value){return isRecord(value)&&(value.status==="complete"||value.status==="unchecked")&&value.unreadable_item_count===0&&value.unreadable_directory_count===0}function hasDefaultOmissions(value){if(!isRecord(value)||!Array.isArray(value.omitted_field_groups))return!1;const groups=value.omitted_field_groups,group=groups[0];return value.has_omissions===!0&&value.omitted_field_group_count===1&&Object.keys(value).length===3&&groups.length===1&&isRecord(group)&&Object.keys(group).length===2&&group.name==="full_item_fields"&&group.restore_with==="--full"}function projectPmBriefListEnvelope(value){if(!isRecord(value)||!Array.isArray(value.items)||Object.hasOwn(value,"details")||!hasStandardBriefProjection(value.projection)||!hasCompactibleSource(value.completeness)||!hasStandardPagination(value,value.items.length)||!hasDefaultOmissions(value.omission_receipt))return value;const{total,has_more:hasMore,truncated:_truncated,next_cursor:nextCursor,completeness,projection:_projection,now:_now,omission_receipt:_omissions,sorting,...rest}=value,completed=completeness.status==="complete"&&!hasMore&&Object.keys(completeness).length===3,{unreadable_item_count:_items,unreadable_directory_count:_directories,...source}=completeness;return{...rest,...completed?{}:{total,has_more:hasMore,completeness:source},...hasMore?{next_cursor:nextCursor}:{},...isRecord(sorting)&&sorting.sort==="default"&&sorting.order==="asc"&&Object.keys(sorting).length===2?{}:{sorting},details:"--full"}}export{projectPmBriefListEnvelope};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="0841394b-c439-5002-8451-c538a17acf47")}catch{}})();import{BRIEF_LIST_FIELDS}from"../query/projection-contracts.js";function isRecord(value){return value!==null&&typeof value=="object"&&!Array.isArray(value)}function hasStandardBriefProjection(value){if(!isRecord(value))return!1;const fields=value.fields;return value.mode==="brief"&&Object.keys(value).length===2&&Array.isArray(fields)&&(fields.length===BRIEF_LIST_FIELDS.length||fields.length===BRIEF_LIST_FIELDS.length+1&&fields.at(-1)==="priority")&&BRIEF_LIST_FIELDS.every((field,index)=>fields[index]===field)}function hasStandardPagination(value,count){return typeof value.has_more=="boolean"&&value.truncated===value.has_more&&value.count===count&&typeof value.total=="number"&&Number.isSafeInteger(value.total)&&(value.has_more?value.total>count&&typeof value.next_cursor=="string"&&value.next_cursor.length>0:value.total===count&&value.next_cursor==null)}function hasCompactibleSource(value){return isRecord(value)&&(value.status==="complete"||value.status==="unchecked")&&value.unreadable_item_count===0&&value.unreadable_directory_count===0}function hasDefaultOmissions(value,groupName="full_item_fields"){if(!isRecord(value)||!Array.isArray(value.omitted_field_groups))return!1;const groups=value.omitted_field_groups,group=groups[0];return value.has_omissions===!0&&value.omitted_field_group_count===1&&Object.keys(value).length===3&&groups.length===1&&isRecord(group)&&Object.keys(group).length===2&&group.name===groupName&&group.restore_with==="--full"}function projectPmBriefListEnvelope(value){if(!isRecord(value)||!Array.isArray(value.items)||Object.hasOwn(value,"details")||!hasStandardBriefProjection(value.projection)||!hasCompactibleSource(value.completeness)||!hasStandardPagination(value,value.items.length)||!hasDefaultOmissions(value.omission_receipt))return value;const{total,has_more:hasMore,truncated:_truncated,next_cursor:nextCursor,completeness,projection:_projection,now:_now,omission_receipt:_omissions,sorting,filters,...rest}=value,completed=completeness.status==="complete"&&!hasMore&&Object.keys(completeness).length===3,{unreadable_item_count:_items,unreadable_directory_count:_directories,...source}=completeness;return{...rest,...completed?{}:{total,has_more:hasMore,completeness:source},...hasMore?{next_cursor:nextCursor}:{},...projectDefaultSorting(sorting),...compactEchoedFilters(filters,rest.applied_limit),details:"--full"}}function isDefaultSorting(value){return isRecord(value)&&value.sort==="default"&&value.order==="asc"&&Object.keys(value).every(key=>key==="sort"||key==="order"||key==="effective_keys")}function isSortKeyPair(value){return Array.isArray(value)&&value.length===2&&typeof value[0]=="string"&&(value[1]==="asc"||value[1]==="desc")}function projectDefaultSorting(value){if(!isDefaultSorting(value))return{sorting:value};const keys=value.effective_keys;return keys===void 0?{}:!Array.isArray(keys)||!keys.every(isSortKeyPair)?{sorting:value}:{sorting:{effective_keys:keys.map(([key,order])=>`${key} ${order}`).join(", ")}}}function compactEchoedFilters(filters,appliedLimit){if(!isRecord(filters))return filters===void 0?{}:{filters};const remaining=Object.fromEntries(Object.entries(filters).filter(([key,value])=>!(key==="limit"&&String(value)===String(appliedLimit))&&!(key==="runtime_filters"&&isRecord(value)&&Object.keys(value).length===0)));return Object.keys(remaining).length===0?{}:{filters:remaining}}function hasTerminalSearchPagination(value,count){return value.count===count&&!Object.hasOwn(value,"has_more")&&!Object.hasOwn(value,"truncated")&&value.next_cursor==null&&(value.total===void 0||value.total===count)}function projectPmBriefSearchEnvelope(value){if(!isRecord(value)||typeof value.query!="string"||!Array.isArray(value.items)||Object.hasOwn(value,"details")||Object.hasOwn(value,"projection")||!(hasStandardPagination(value,value.items.length)||hasTerminalSearchPagination(value,value.items.length))||!hasDefaultOmissions(value.omission_receipt,"projection_metadata"))return value;const{truncated:_truncated,omission_receipt:_omissions,filters,...rest}=value;return{...rest,...compactEchoedFilters(filters,rest.applied_limit),details:"--full"}}export{projectPmBriefListEnvelope,projectPmBriefSearchEnvelope};
 //# sourceMappingURL=list-envelope.js.map

package/dist/sdk/output.d.ts

@@ -6,7 +6,7 @@
  */
 export { SUPPRESS_HOST_OUTPUT_MARKER,isHostOutputSuppressed,suppressHostOutput,type SuppressedHostOutput,} from "../core/output/output-control.js";
 export { encodePmTableRows,decodePmTableRows,type PmTableCellEncoding,type PmEncodedTableRows,} from "./output/table-rows.js";
-export { projectPmBriefListEnvelope } from "./output/list-envelope.js";
+export { projectPmBriefListEnvelope,projectPmBriefSearchEnvelope,} from "./output/list-envelope.js";
 export { assertWellFormedOutputText,toWellFormedText } from "../core/shared/output-unicode.js";
 /**
  * Serialize object rows as newline-delimited JSON without adding a trailing

package/dist/sdk/output.js

@@ -1,3 +1,3 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="57414d85-ac87-59fb-8a42-b2be660bc2e6")}catch{}})();import{SUPPRESS_HOST_OUTPUT_MARKER,isHostOutputSuppressed,suppressHostOutput}from"../core/output/output-control.js";import{encodePmTableRows,decodePmTableRows}from"./output/table-rows.js";import{projectPmBriefListEnvelope}from"./output/list-envelope.js";import{assertWellFormedOutputText,toWellFormedText}from"../core/shared/output-unicode.js";function serializeNdjsonRows(rows){return rows.map((row,index)=>{if(typeof row!="object"||row===null||Array.isArray(row))throw new TypeError(`NDJSON row ${index} must be a non-null object.`);const serialized=JSON.stringify(row);if(serialized===void 0)throw new TypeError(`NDJSON row ${index} must serialize to a non-null object.`);const projected=JSON.parse(serialized);if(typeof projected!="object"||projected===null||Array.isArray(projected))throw new TypeError(`NDJSON row ${index} must serialize to a non-null object.`);return serialized}).join(`
-`)}function serializeNdjsonStream(rows,trailer){if(trailer.count!==rows.length)throw new TypeError(`NDJSON trailer count ${trailer.count} does not match ${rows.length} ${rows.length===1?"row":"rows"}.`);for(const[index,row]of rows.entries())if(typeof row=="object"&&row!==null&&!Array.isArray(row)&&Reflect.get(row,"record_type")==="pm.stream.trailer")throw new TypeError(`NDJSON row ${index} uses reserved record_type pm.stream.trailer`);return serializeNdjsonRows([...rows,{...trailer,record_type:"pm.stream.trailer"}])}export{SUPPRESS_HOST_OUTPUT_MARKER,assertWellFormedOutputText,decodePmTableRows,encodePmTableRows,isHostOutputSuppressed,projectPmBriefListEnvelope,serializeNdjsonRows,serializeNdjsonStream,suppressHostOutput,toWellFormedText};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="9febe44f-931d-5442-95e6-2793cb571972")}catch{}})();import{SUPPRESS_HOST_OUTPUT_MARKER,isHostOutputSuppressed,suppressHostOutput}from"../core/output/output-control.js";import{encodePmTableRows,decodePmTableRows}from"./output/table-rows.js";import{projectPmBriefListEnvelope,projectPmBriefSearchEnvelope}from"./output/list-envelope.js";import{assertWellFormedOutputText,toWellFormedText}from"../core/shared/output-unicode.js";function serializeNdjsonRows(rows){return rows.map((row,index)=>{if(typeof row!="object"||row===null||Array.isArray(row))throw new TypeError(`NDJSON row ${index} must be a non-null object.`);const serialized=JSON.stringify(row);if(serialized===void 0)throw new TypeError(`NDJSON row ${index} must serialize to a non-null object.`);const projected=JSON.parse(serialized);if(typeof projected!="object"||projected===null||Array.isArray(projected))throw new TypeError(`NDJSON row ${index} must serialize to a non-null object.`);return serialized}).join(`
+`)}function serializeNdjsonStream(rows,trailer){if(trailer.count!==rows.length)throw new TypeError(`NDJSON trailer count ${trailer.count} does not match ${rows.length} ${rows.length===1?"row":"rows"}.`);for(const[index,row]of rows.entries())if(typeof row=="object"&&row!==null&&!Array.isArray(row)&&Reflect.get(row,"record_type")==="pm.stream.trailer")throw new TypeError(`NDJSON row ${index} uses reserved record_type pm.stream.trailer`);return serializeNdjsonRows([...rows,{...trailer,record_type:"pm.stream.trailer"}])}export{SUPPRESS_HOST_OUTPUT_MARKER,assertWellFormedOutputText,decodePmTableRows,encodePmTableRows,isHostOutputSuppressed,projectPmBriefListEnvelope,projectPmBriefSearchEnvelope,serializeNdjsonRows,serializeNdjsonStream,suppressHostOutput,toWellFormedText};
 //# sourceMappingURL=output.js.map