@unbrained/pm-cli 2026.8.6 → 2026.8.7

package/dist/sdk/read-output-contracts.js

@@ -5,10 +5,12 @@
  * surface without coupling package authors to command-specific option names.
  */
 
-!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]="27431a6b-6f2e-5020-b4f1-b94cfa8a1c26")}catch(e){}}();
+!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]="0bccb953-bd78-5eee-a78d-8af3e250fa55")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
-import { compactReadOutputToBudget, updateReadOutputReceiptEstimate } from "./read-output-budget.js";
+import { compactReadOutputToBudget, updateReadOutputReceiptEstimate, } from "./read-output-budget.js";
+import { boundReadOutputRows, countReadOutputRows, mapReadOutputRows, readOutputRowPaths, } from "./read-output-rows.js";
+import { applyReadOutputSessionReferences, attachReadOutputSessionReceipt, parseReadOutputSession, readOutputSessionRemainingTokens, } from "./read-output-session.js";
 /** Stable output dimensions shared by every read surface. */
 export const PM_READ_OUTPUT_DIMENSIONS = [
     "include",
@@ -52,6 +54,10 @@ const CANONICAL_OPTIONS = {
 };
 /** Canonical CLI flags that opt a read invocation into universal output shaping. */
 export const PM_READ_OUTPUT_OPTION_FLAGS = Object.freeze(PM_READ_OUTPUT_DIMENSIONS.map((dimension) => CANONICAL_OPTIONS[dimension]));
+/** Canonical control that composes the four per-call dimensions across reads. */
+export const PM_READ_OUTPUT_COMPOSITION_OPTION_FLAGS = Object.freeze([
+    "--output-session",
+]);
 const LEGACY_FLAGS_BY_COMMAND = {
     list: {
         include: ["--brief", "--compact", "--fields", "--full"],
@@ -166,7 +172,11 @@ function buildSurfaceContract(command) {
             }))),
         }),
     ])));
-    return Object.freeze({ command, dimensions, precedence: READ_OUTPUT_PRECEDENCE });
+    return Object.freeze({
+        command,
+        dimensions,
+        precedence: READ_OUTPUT_PRECEDENCE,
+    });
 }
 /** Universal output contract for every built-in read surface. */
 export const PM_READ_OUTPUT_SURFACE_CONTRACTS = Object.freeze(PM_READ_OUTPUT_SURFACES.map(buildSurfaceContract));
@@ -195,6 +205,8 @@ const CANONICAL_OPTION_KEYS = [
     "output_budget",
     "outputFormat",
     "output_format",
+    "outputSession",
+    "output_session",
 ];
 const HYBRID_READ_MUTATION_KEYS = {
     comments: ["add", "body", "stdin", "file", "edit", "delete"],
@@ -226,6 +238,14 @@ const READ_OUTPUT_VALUE_VALIDATORS = [
         valid: (value) => value === "toon" || value === "json",
         message: "--output-format must be toon or json.",
     },
+    {
+        keys: ["outputSession", "output_session"],
+        valid: (value) => {
+            parseReadOutputSession(value);
+            return true;
+        },
+        message: "--output-session must be a valid session-state object.",
+    },
 ];
 /** Reject malformed or mutation-scoped universal output controls before command execution. */
 export function validateReadOutputOptions(command, options) {
@@ -403,29 +423,24 @@ const ENVELOPE_KEYS = new Set([
     "total",
     "truncated",
 ]);
-function rowKeys(result) {
-    const contract = result.row_contract;
-    if (isRecord(contract) && Array.isArray(contract.row_keys)) {
-        return contract.row_keys.filter((entry) => typeof entry === "string");
-    }
-    return Object.entries(result)
-        .filter(([, value]) => Array.isArray(value))
-        .map(([key]) => key);
-}
 function projectRecordFields(value, selectors) {
     const selected = new Set(selectors.map((selector) => selector.split(".")[0]));
     return Object.fromEntries(Object.entries(value).filter(([key]) => selected.has(key)));
 }
 function applyIncludeProjection(result, selectors) {
-    const rows = rowKeys(result);
-    const selectedRoot = selectors.some((selector) => Object.hasOwn(result, selector.split(".")[0]));
-    if (rows.length > 0 && !selectedRoot) {
-        return Object.fromEntries(Object.entries(result).map(([key, value]) => [
-            key,
-            rows.includes(key) && Array.isArray(value)
-                ? value.map((entry) => isRecord(entry) ? projectRecordFields(entry, selectors) : entry)
-                : value,
-        ]));
+    const rows = readOutputRowPaths(result);
+    const qualifiedRowSelectors = selectors.flatMap((selector) => rows.flatMap((rowPath) => selector.startsWith(`${rowPath}.`)
+        ? [selector.slice(rowPath.length + 1)]
+        : []));
+    const selectedRoot = selectors.some((selector) => Object.hasOwn(result, selector.split(".")[0]) &&
+        !rows.some((rowPath) => selector.startsWith(`${rowPath}.`)));
+    if (rows.length > 0 && (!selectedRoot || qualifiedRowSelectors.length > 0)) {
+        const projected = { ...result };
+        return mapReadOutputRows(projected, (entry) => isRecord(entry)
+            ? projectRecordFields(entry, qualifiedRowSelectors.length > 0
+                ? qualifiedRowSelectors
+                : selectors)
+            : entry);
     }
     return Object.fromEntries(Object.entries(result).filter(([key]) => selectors.some((selector) => selector.split(".")[0] === key) ||
         ENVELOPE_KEYS.has(key)));
@@ -433,22 +448,13 @@ function applyIncludeProjection(result, selectors) {
 function applyAmountBound(result, amount) {
     if (amount === "unbounded")
         return result;
-    let truncated = false;
-    const rowKeyList = rowKeys(result);
-    const rows = new Set(rowKeyList);
-    const bounded = Object.fromEntries(Object.entries(result).map(([key, value]) => {
-        if (!rows.has(key) || !Array.isArray(value) || value.length <= amount) {
-            return [key, value];
-        }
-        truncated = true;
-        return [key, value.slice(0, amount)];
-    }));
+    const { result: bounded, truncated } = boundReadOutputRows(result, amount);
     if (!truncated)
         return bounded;
     bounded.has_more = true;
     bounded.truncated = true;
     if (typeof bounded.count === "number") {
-        bounded.count = rowKeyList.reduce((total, key) => total + (Array.isArray(bounded[key]) ? bounded[key].length : 0), 0);
+        bounded.count = countReadOutputRows(bounded);
     }
     bounded.applied_bound = {
         kind: "output_limit",
@@ -460,23 +466,91 @@ function applyAmountBound(result, amount) {
 function requestedDimensions(resolved) {
     return PM_READ_OUTPUT_DIMENSIONS.filter((dimension) => resolved[dimension] !== undefined);
 }
+/** Stabilize the per-call and cross-call receipts in one complete envelope. */
+function attachReadOutputSessionContracts(result, state, receipt) {
+    let withSession = attachReadOutputSessionReceipt(result, state);
+    for (let iteration = 0; iteration < 8; iteration += 1) {
+        const previousReadEstimate = receipt.estimated_tokens;
+        const previousSessionEstimate = withSession.read_session.spent_this_call_tokens;
+        updateReadOutputReceiptEstimate(withSession, receipt);
+        withSession = attachReadOutputSessionReceipt(withSession, state);
+        const sessionEstimate = withSession.read_session.spent_this_call_tokens;
+        if (receipt.estimated_tokens === previousReadEstimate &&
+            sessionEstimate === previousSessionEstimate) {
+            return withSession;
+        }
+    }
+    return withSession;
+}
+/** Apply field, amount, and repeat projections to every declared row path. */
+function projectReadOutputRows(result, resolved, session) {
+    let projected = { ...result };
+    if (resolved.include?.source === "canonical") {
+        projected = applyIncludeProjection(projected, resolved.include.value);
+    }
+    if (resolved.amount?.source === "canonical") {
+        projected = applyAmountBound(projected, resolved.amount.value);
+    }
+    return session === undefined
+        ? projected
+        : applyReadOutputSessionReferences(projected, session);
+}
+/** Resolve the smallest binding per-call or remaining cross-call ceiling. */
+function resolveBindingReadOutputBudget(resolved, session) {
+    const budgets = [
+        ...(resolved.cost?.source === "canonical" ? [resolved.cost.value] : []),
+        ...(session === undefined
+            ? []
+            : [readOutputSessionRemainingTokens(session)]),
+    ];
+    return budgets.length === 0 ? undefined : Math.min(...budgets);
+}
+/** Build the smallest truthful omission envelope or reject an exhausted session. */
+function omitReadOutputForBudget(resolved, requested, session, budget) {
+    const minimalReceipt = {
+        contract_version: 1,
+        command: resolved.command,
+        requested_dimensions: requested,
+        precedence: resolved.precedence,
+        legacy_aliases_used: [],
+        migration_hints: [],
+        estimated_tokens: 0,
+        within_budget: false,
+        strings_compacted: false,
+        rows_compacted: false,
+        result_omitted: true,
+    };
+    const omitted = {
+        output_budget_exceeded: {
+            omitted_result: true,
+            reason: "requested_budget_infeasible",
+            restore_with: "Increase --output-budget or narrow the read.",
+        },
+        read_output: minimalReceipt,
+    };
+    const boundedOmission = session === undefined
+        ? omitted
+        : attachReadOutputSessionContracts(omitted, session, minimalReceipt);
+    if (session === undefined) {
+        updateReadOutputReceiptEstimate(boundedOmission, minimalReceipt);
+    }
+    if (session !== undefined && minimalReceipt.estimated_tokens > budget) {
+        throw new PmCliError("The remaining output-session budget cannot fit its mandatory receipts; start a new session with a larger token_budget.", EXIT_CODE.USAGE);
+    }
+    return boundedOmission;
+}
 /** Apply universal field, row, and token bounds and attach an exact receipt. */
 export function applyReadOutputDimensions(command, options, result) {
     const resolved = resolveReadOutputDimensions(command, options);
     if (!resolved)
         return result;
+    const session = parseReadOutputSession(options.outputSession ?? options.output_session);
     const requested = requestedDimensions(resolved);
     const canonicalRequested = requested.filter((dimension) => resolved[dimension]?.source === "canonical");
-    if (canonicalRequested.length === 0) {
+    if (canonicalRequested.length === 0 && session === undefined) {
         return result;
     }
-    let projected = { ...result };
-    if (resolved.include?.source === "canonical") {
-        projected = applyIncludeProjection(projected, resolved.include.value);
-    }
-    if (resolved.amount?.source === "canonical") {
-        projected = applyAmountBound(projected, resolved.amount.value);
-    }
+    let projected = projectReadOutputRows(result, resolved, session);
     const receipt = {
         contract_version: 1,
         command: resolved.command,
@@ -491,35 +565,20 @@ export function applyReadOutputDimensions(command, options, result) {
         result_omitted: false,
     };
     projected.read_output = receipt;
+    projected =
+        session === undefined
+            ? projected
+            : attachReadOutputSessionContracts(projected, session, receipt);
     updateReadOutputReceiptEstimate(projected, receipt);
-    const budget = resolved.cost?.source === "canonical" ? resolved.cost.value : undefined;
+    const budget = resolveBindingReadOutputBudget(resolved, session);
     if (budget !== undefined && receipt.estimated_tokens > budget) {
         projected = compactReadOutputToBudget(projected, receipt, budget);
+        if (session !== undefined) {
+            projected = attachReadOutputSessionContracts(projected, session, receipt);
+        }
     }
     if (budget !== undefined && receipt.estimated_tokens > budget) {
-        const minimalReceipt = {
-            contract_version: 1,
-            command: resolved.command,
-            requested_dimensions: requested,
-            precedence: resolved.precedence,
-            legacy_aliases_used: [],
-            migration_hints: [],
-            estimated_tokens: 0,
-            within_budget: false,
-            strings_compacted: false,
-            rows_compacted: false,
-            result_omitted: true,
-        };
-        const omitted = {
-            output_budget_exceeded: {
-                omitted_result: true,
-                reason: "requested_budget_infeasible",
-                restore_with: "Increase --output-budget or narrow the read.",
-            },
-            read_output: minimalReceipt,
-        };
-        updateReadOutputReceiptEstimate(omitted, minimalReceipt);
-        return omitted;
+        return omitReadOutputForBudget(resolved, requested, session, budget);
     }
     return projected;
 }
@@ -538,4 +597,4 @@ export function resolveReadOutputEncoding(command, options) {
         : undefined;
 }
 //# sourceMappingURL=read-output-contracts.js.map
-//# debugId=27431a6b-6f2e-5020-b4f1-b94cfa8a1c26
+//# debugId=0bccb953-bd78-5eee-a78d-8af3e250fa55

package/dist/sdk/read-output-rows.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @module sdk/read-output-rows
+ *
+ * Resolves and transforms the row collections declared by universal read
+ * envelopes, including dot-delimited nested paths used by graph projections.
+ */
+/** One declared array or object-map row collection in a read envelope. */
+export interface PmReadOutputRowCollection {
+    /** Dot-delimited path published by the envelope row contract. */
+    path: string;
+    /** Array rows or a keyed row map stored at {@link path}. */
+    value: unknown[] | Record<string, unknown>;
+}
+/** Resolve declared row paths, falling back to top-level array properties. */
+export declare function readOutputRowPaths(result: Record<string, unknown>): string[];
+/** Resolve every declared row path that currently contains iterable rows. */
+export declare function readOutputRowCollections(result: Record<string, unknown>): PmReadOutputRowCollection[];
+/** Count array entries and object-map values across declared row collections. */
+export declare function countReadOutputRows(result: Record<string, unknown>): number;
+/**
+ * Transform every declared row while preserving collection keys and cloning
+ * only the owner objects along paths that changed.
+ */
+export declare function mapReadOutputRows(result: Record<string, unknown>, transform: (row: unknown, path: string, index: number) => unknown): Record<string, unknown>;
+/** Bound every declared row collection independently and report truncation. */
+export declare function boundReadOutputRows(result: Record<string, unknown>, amount: number): {
+    result: Record<string, unknown>;
+    truncated: boolean;
+};

package/dist/sdk/read-output-rows.js

@@ -0,0 +1,100 @@
+/**
+ * @module sdk/read-output-rows
+ *
+ * Resolves and transforms the row collections declared by universal read
+ * envelopes, including dot-delimited nested paths used by graph projections.
+ */
+
+!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]="ae6fbd4a-6c4e-5639-93ac-f107a336e95b")}catch(e){}}();
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** Read one dot-delimited path without treating missing segments as rows. */
+function valueAtPath(result, rowPath) {
+    let value = result;
+    for (const segment of rowPath.split(".")) {
+        if (!isRecord(value))
+            return undefined;
+        value = value[segment];
+    }
+    return value;
+}
+/** Clone the owners along one row path and replace only its terminal value. */
+function replaceValueAtPath(result, rowPath, replacement) {
+    const segments = rowPath.split(".");
+    const root = { ...result };
+    let source = result;
+    let target = root;
+    for (const segment of segments.slice(0, -1)) {
+        const sourceChild = source[segment];
+        const targetChild = { ...sourceChild };
+        target[segment] = targetChild;
+        source = sourceChild;
+        target = targetChild;
+    }
+    target[segments.at(-1)] = replacement;
+    return root;
+}
+/** Resolve declared row paths, falling back to top-level array properties. */
+export function readOutputRowPaths(result) {
+    const contract = result.row_contract;
+    if (isRecord(contract) && Array.isArray(contract.row_keys)) {
+        return contract.row_keys.filter((entry) => typeof entry === "string" && entry.trim().length > 0);
+    }
+    return Object.entries(result)
+        .filter(([, value]) => Array.isArray(value))
+        .map(([key]) => key);
+}
+/** Resolve every declared row path that currently contains iterable rows. */
+export function readOutputRowCollections(result) {
+    return readOutputRowPaths(result).flatMap((rowPath) => {
+        const value = valueAtPath(result, rowPath);
+        return Array.isArray(value) || isRecord(value)
+            ? [{ path: rowPath, value }]
+            : [];
+    });
+}
+/** Count array entries and object-map values across declared row collections. */
+export function countReadOutputRows(result) {
+    return readOutputRowCollections(result).reduce((total, collection) => total +
+        (Array.isArray(collection.value)
+            ? collection.value.length
+            : Object.keys(collection.value).length), 0);
+}
+/**
+ * Transform every declared row while preserving collection keys and cloning
+ * only the owner objects along paths that changed.
+ */
+export function mapReadOutputRows(result, transform) {
+    let projected = result;
+    for (const collection of readOutputRowCollections(projected)) {
+        const replacement = Array.isArray(collection.value)
+            ? collection.value.map((row, index) => transform(row, collection.path, index))
+            : Object.fromEntries(Object.entries(collection.value).map(([key, row], index) => [
+                key,
+                transform(row, collection.path, index),
+            ]));
+        projected = replaceValueAtPath(projected, collection.path, replacement);
+    }
+    return projected;
+}
+/** Bound every declared row collection independently and report truncation. */
+export function boundReadOutputRows(result, amount) {
+    let projected = result;
+    let truncated = false;
+    for (const collection of readOutputRowCollections(projected)) {
+        const entries = Array.isArray(collection.value)
+            ? collection.value
+            : Object.entries(collection.value);
+        if (entries.length <= amount)
+            continue;
+        truncated = true;
+        const replacement = Array.isArray(collection.value)
+            ? entries.slice(0, amount)
+            : Object.fromEntries(entries.slice(0, amount));
+        projected = replaceValueAtPath(projected, collection.path, replacement);
+    }
+    return { result: projected, truncated };
+}
+//# sourceMappingURL=read-output-rows.js.map
+//# debugId=ae6fbd4a-6c4e-5639-93ac-f107a336e95b

package/dist/sdk/read-output-session.d.ts

@@ -0,0 +1,69 @@
+/** Versioned state supplied to a sequence of related read invocations. */
+export interface PmReadOutputSessionState {
+    /** Session-state schema version. */
+    version: 1;
+    /** Caller-selected request-group identity. */
+    id: string;
+    /** Binding token ceiling shared by every invocation in the group. */
+    token_budget: number;
+    /** Tokens already spent by earlier invocations. */
+    spent_tokens: number;
+    /** Item facts already serialized in full during this session. */
+    seen_item_ids: string[];
+}
+/** Lightweight row emitted instead of repeating a previously served item. */
+export interface PmReadOutputSessionReference {
+    /** Stable item identity retained for joins and follow-up reads. */
+    id: string;
+    /** Resolvable reference to the session fact already in caller context. */
+    context_ref: string;
+}
+/** Receipt proving cross-call suppression and budget accounting. */
+export interface PmReadOutputSessionReceipt {
+    /** Session-receipt schema version. */
+    contract_version: 1;
+    /** Caller-selected request-group identity. */
+    id: string;
+    /** Accounting scope, including this receipt and the read-output receipt. */
+    measurement_scope: "complete_read_envelope";
+    /** Canonical estimator shared with per-call output budgets. */
+    estimator: "ceil(utf8_bytes / 4)";
+    /** Group ceiling supplied in the session state. */
+    token_budget: number;
+    /** Spend carried into this invocation. */
+    spent_before_tokens: number;
+    /** Exact fixed-point estimate emitted by this invocation. */
+    spent_this_call_tokens: number;
+    /** Portion of this invocation charged before the ceiling was exhausted. */
+    charged_this_call_tokens: number;
+    /** Accumulated spend after this invocation. */
+    spent_total_tokens: number;
+    /** Unspent group capacity after this invocation. */
+    remaining_tokens: number;
+    /** Whether no further useful read envelope fits the group ceiling. */
+    exhausted: boolean;
+    /** Number of full item facts known before this invocation. */
+    seen_before_count: number;
+    /** Number of newly delivered item facts retained in this envelope. */
+    new_item_count: number;
+    /** Number of repeated item rows replaced by references. */
+    suppressed_repeat_count: number;
+    /** Stable reference syntax used by suppressed rows. */
+    reference_format: "session:<session-id>:<item-id>";
+    /** Command that restores a referenced item when prior context is unavailable. */
+    restore_reference_with: "pm get <item-id> --brief";
+    /** Caller-carried state for the next read in the same request group. */
+    next_state: PmReadOutputSessionState;
+}
+/** Smallest session ceiling that can carry a useful result and both receipts. */
+export declare const PM_READ_OUTPUT_SESSION_MIN_TOKENS = 256;
+/** Maximum caller-carried served-item identities accepted in one session state. */
+export declare const PM_READ_OUTPUT_SESSION_MAX_SEEN_ITEM_IDS = 10000;
+/** Parse and strictly validate a JSON string or typed session-state object. */
+export declare function parseReadOutputSession(value: unknown): PmReadOutputSessionState | undefined;
+/** Replace previously served item rows with compact, resolvable references. */
+export declare function applyReadOutputSessionReferences(result: Record<string, unknown>, state: PmReadOutputSessionState): Record<string, unknown>;
+/** Attach a fixed-point session receipt and return the exact charged tokens. */
+export declare function attachReadOutputSessionReceipt(result: Record<string, unknown>, state: PmReadOutputSessionState): Record<string, unknown>;
+/** Return the unspent group budget available to the current invocation. */
+export declare function readOutputSessionRemainingTokens(state: PmReadOutputSessionState): number;