pm-context 2026.7.25 → 2026.7.27

package/dist/index.js

@@ -1,6 +1,19 @@
-import { spawnSync } from "node:child_process";
 import { writeFileSync } from "node:fs";
-const defineExtension = ((extension) => extension);
+import { readSettings, resolveRuntimeStatusRegistry } from "@unbrained/pm-cli/sdk";
+import { list as pmList } from "@unbrained/pm-cli/sdk/core";
+import { buildItemContextRelevanceCandidates, defaultScoreContextCandidates, packContextCandidates, recordContextUsageServing, } from "@unbrained/pm-cli/sdk/query";
+import { DEFAULT_REPORT_LIMIT, renderUsageReport, reportContextUsage, resolveSince } from "./context-usage.js";
+import { readContextUsageAffinity } from "@unbrained/pm-cli/sdk/query";
+/**
+ * Runtime stand-in for the SDK's `defineExtension`.
+ *
+ * `defineExtension` is a documented zero-cost identity function. This package
+ * now resolves `@unbrained/pm-cli` at runtime (it is a peer dependency the pm
+ * host provides) for the `sdk/core` and `sdk/query` engines, but the authoring
+ * helper itself has no runtime behavior, so a local identity shim avoids a
+ * needless value import while still contract-checking the module against
+ * {@link ExtensionModule}.
+ */
 export const EXIT_CODE = {
     GENERIC_FAILURE: 1,
     USAGE: 2,
@@ -262,7 +275,8 @@ export function buildContextPack(allItems, options = {}) {
     const selected = ids.length > 0
         ? ids.map((id) => byId.get(id)).filter((item) => Boolean(item))
         : allItems.filter((item) => matchesFilters(item, options));
-    const limited = sortContextItems(selected).slice(0, options.limit ?? 25);
+    const ranker = options.ranker ?? sortContextItems;
+    const limited = ranker(selected).slice(0, options.limit ?? 25);
     const selectedIds = new Set(limited.map((item) => item.id));
     // Resolve the neighborhood depth. --without-neighborhood (neighborhood === false)
     // forces depth 0. Otherwise default to 1 hop, capped at MAX_NEIGHBORHOOD_DEPTH.
@@ -299,12 +313,18 @@ export function buildContextPack(allItems, options = {}) {
         neighborIds.delete(id);
     let neighbors = sortContextItems([...neighborIds].map((id) => byId.get(id)).filter((item) => Boolean(item)))
         .sort((a, b) => (neighborDepths.get(a.id) ?? Number.MAX_SAFE_INTEGER) - (neighborDepths.get(b.id) ?? Number.MAX_SAFE_INTEGER));
-    // --max-items caps the total item count (focus + neighbors). Focus items take
-    // priority; neighbors are trimmed to fit the remaining budget. If focus
-    // alone exceeds the cap, focus is also trimmed.
+    // --max-items caps the total item count (focus + neighbors). The default
+    // packer gives focus items priority and trims neighbors to fit the remaining
+    // budget; the command path supplies a `packContextCandidates`-backed packer
+    // that selects under a token budget with projection degradation instead.
     let focusItems = limited;
     if (typeof options.maxItems === "number" && options.maxItems > 0) {
-        if (focusItems.length >= options.maxItems) {
+        if (options.packer) {
+            const packed = options.packer(focusItems, neighbors, options.maxItems);
+            focusItems = packed.focus;
+            neighbors = packed.neighbors;
+        }
+        else if (focusItems.length >= options.maxItems) {
             focusItems = focusItems.slice(0, options.maxItems);
             neighbors = [];
         }
@@ -633,25 +653,300 @@ export function renderAgentHandoff(pack, options = {}) {
     }
     return output;
 }
-export function readPmItems(pmRoot) {
-    const result = spawnSync("pm", ["--path", pmRoot, "list-all", "--json", "--include-body"], {
-        encoding: "utf-8",
-        maxBuffer: 64 * 1024 * 1024,
+/**
+ * Read every pm item (full metadata + body) in-process through the SDK.
+ *
+ * Replaces the previous `spawnSync("pm", ["list-all", "--json", "--include-body"])`
+ * shell-out with the typed {@link list} action from `@unbrained/pm-cli/sdk/core`.
+ * `list-all` is the SDK alias for `list` with `excludeTerminal: false`; passing
+ * `full: true` + `includeBody: true` reproduces the full-metadata-with-body
+ * projection the shell-out parsed, including the CLI's default truncation
+ * semantics, so the downstream pack shape remains compatible.
+ */
+export async function readPmItems(pmRoot) {
+    let result;
+    try {
+        result = await pmList({ full: true, includeBody: true, excludeTerminal: false }, { pmRoot });
+    }
+    catch (err) {
+        throw new CommandError(`Could not read pm items via SDK list: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return result.items.filter((item) => typeof item.id === "string");
+}
+/** Per-item token estimate for one character of text (rough 4 chars/token). */
+const TOKENS_PER_CHAR = 0.25;
+/** Default token budget allocated per `--max-items` slot when token-budgeted packing runs. */
+const TOKENS_PER_ITEM_SLOT = 220;
+/**
+ * Coerce a {@link PmItem} into the {@link ItemMetadata} shape the SDK relevance
+ * engine requires, filling any absent required scalar with a neutral default.
+ * Items returned by {@link readPmItems} already carry every required field, so
+ * this is idempotent for real packs; it only papers over the optional fields of
+ * the loose `PmItem` projection so hand-built test fixtures still rank.
+ */
+function toItemMetadata(item, now) {
+    const priority = typeof item.priority === "number" && item.priority >= 0 && item.priority <= 4 ? item.priority : 3;
+    // `readPmItems` returns the SDK list engine's full projection, which already
+    // satisfies `ItemMetadata`; it flows through the loose `PmItem` interface only
+    // so `buildContextPack` can keep accepting hand-built fixtures. This cast
+    // restores the precise SDK type for the relevance engine — the required
+    // scalars are filled above, and the optional collection fields (dependencies,
+    // docs, files, blocked_by) come straight from the real item. PmItem types
+    // those as `unknown` (wider than ItemMetadata), so the assertion bridges that
+    // widening rather than hiding a real mismatch.
+    return {
+        ...item,
+        id: item.id,
+        title: typeof item.title === "string" ? item.title : "",
+        description: typeof item.description === "string" ? item.description : "",
+        type: typeof item.type === "string" ? item.type : "Task",
+        status: typeof item.status === "string" ? item.status : "unknown",
+        priority: priority,
+        tags: Array.isArray(item.tags) ? item.tags.map((tag) => String(tag)) : [],
+        created_at: normalizeText(item.created_at) || normalizeText(item.updated_at) || now,
+        updated_at: normalizeText(item.updated_at) || normalizeText(item.created_at) || now,
+    };
+}
+/**
+ * Rank items with pm's deterministic weighted relevance model.
+ *
+ * Wraps {@link buildItemContextRelevanceCandidates} +
+ * {@link defaultScoreContextCandidates} so the command path uses the same
+ * relevance signals (`priority_pressure`, `recency`, `claim_focus`, …) as
+ * `pm context` / `pm next` instead of the hand-rolled priority-then-recency
+ * sort. Returns the items in ranked order and exposes the full report via
+ * {@link scoreContextItems} for `--explain`.
+ */
+export function rankContextItems(items, options) {
+    const report = scoreContextItems(items, options);
+    const byId = new Map(items.map((item) => [item.id, item]));
+    return report.ranked
+        .map((ranked) => byId.get(ranked.id))
+        .filter((item) => Boolean(item));
+}
+/**
+ * Score items with the SDK relevance model and return the full report.
+ *
+ * The report's `ranked[].contributions` map each item's score back to the
+ * individual signals that produced it — the data behind `pm context-pack
+ * --explain`.
+ */
+export function scoreContextItems(items, options) {
+    const now = options.now;
+    const byId = new Map(items.map((item) => [item.id, item]));
+    const candidates = buildItemContextRelevanceCandidates(items.map((item) => toItemMetadata(item, now)), {
+        statusRegistry: options.statusRegistry,
+        now,
+        author: options.author,
+        usageAffinity: options.usageAffinity,
     });
-    if (result.error) {
-        throw new CommandError(`Could not run pm list-all --json --include-body: ${result.error.message}`);
+    // `defaultScoreContextCandidates` is the deterministic, extension-free core of
+    // `scoreContextCandidates`. The command path runs in-process and does not need
+    // the governed `context_relevance` service override, so the synchronous default
+    // keeps pack generation deterministic and side-effect free.
+    return defaultScoreContextCandidates(candidates.map((candidate) => ({ id: candidate.id, item: byIdOrFail(byId, candidate.id), signals: candidate.signals })));
+}
+/** Look up an item by id or throw a descriptive error (keeps callers honest). */
+function byIdOrFail(byId, id) {
+    const item = byId.get(id);
+    if (!item)
+        throw new CommandError(`relevance candidate ${id} not found among items`);
+    return item;
+}
+/**
+ * Build a {@link ContextPackOptions.ranker} closure backed by the SDK relevance
+ * model. The closure ranks whatever focus subset {@link buildContextPack} hands
+ * it after id/status/type/tag filtering, preserving the SDK's weighted order.
+ */
+export function createSdkRanker(allItems, options) {
+    return (items) => {
+        if (items.length <= 1)
+            return items;
+        return rankContextItems(items, options);
+    };
+}
+/** Rough token estimate for one projection level of a context candidate. */
+function estimateTokens(text) {
+    return Math.max(1, Math.ceil(text.length * TOKENS_PER_CHAR));
+}
+/**
+ * Estimate the identity / summary / full token costs for one item, matching the
+ * monotone projection ladder {@link packContextCandidates} upgrades through.
+ */
+function estimateProjectionCosts(item) {
+    const identity = estimateTokens(`${item.id} ${normalizeText(item.title)}`);
+    const meta = `${itemType(item)} ${itemStatus(item)} ${typeof item.priority === "number" ? item.priority : ""} ${(normalizeTags(item.tags)).join(" ")}`;
+    const summary = identity + estimateTokens(meta);
+    const body = normalizeText(item.body) || normalizeText(item.description);
+    const full = summary + (body ? estimateTokens(body) : 0);
+    return { identity, summary, full };
+}
+/**
+ * Build a {@link ContextPackOptions.packer} closure backed by
+ * {@link packContextCandidates}. Each `--max-items` slot maps to a token budget;
+ * focus items are required anchors, neighbors compete by relevance rank for the
+ * remaining budget. The packer first selects under that token budget with pm's
+ * projection-degradation optimizer, then enforces the command's explicit item
+ * ceiling while preserving the SDK-selected focus-first order.
+ */
+export function createSdkPacker(rankedFocus, rankedNeighbors) {
+    const focusRank = new Map(rankedFocus.map((item, index) => [item.id, index + 1]));
+    const neighborRank = new Map(rankedNeighbors.map((item, index) => [item.id, rankedFocus.length + index + 1]));
+    return (focus, neighbors, maxItems) => {
+        if (!(maxItems > 0))
+            return { focus, neighbors };
+        const tokenBudget = maxItems * TOKENS_PER_ITEM_SLOT;
+        const candidates = [
+            ...focus.map((item) => ({
+                id: item.id,
+                item,
+                rank: focusRank.get(item.id) ?? 1,
+                score: 1 / (focusRank.get(item.id) ?? 1),
+                token_costs: estimateProjectionCosts(item),
+                required: true,
+            })),
+            ...neighbors.map((item) => ({
+                id: item.id,
+                item,
+                rank: neighborRank.get(item.id) ?? focus.length + 1,
+                score: 1 / (neighborRank.get(item.id) ?? focus.length + 1),
+                token_costs: estimateProjectionCosts(item),
+            })),
+        ];
+        const packed = packContextCandidates(candidates, { tokenBudget, profile: "context" });
+        const included = new Set(packed.included.map((candidate) => candidate.id));
+        const packedFocus = focus.filter((item) => included.has(item.id)).slice(0, maxItems);
+        const remainingSlots = Math.max(0, maxItems - packedFocus.length);
+        return {
+            focus: packedFocus,
+            neighbors: neighbors.filter((item) => included.has(item.id)).slice(0, remainingSlots),
+        };
+    };
+}
+/**
+ * Build the `--explain` report from the SDK relevance model for the emitted
+ * pack. Ranks and normalized scores are relative to this supplied population,
+ * not the complete workspace corpus.
+ */
+export function buildContextExplain(items, options) {
+    const report = scoreContextItems(items, options);
+    return {
+        generatedAt: options.now,
+        model: report.model,
+        ranking_scope: "emitted_pack",
+        available_signals: report.available_signals,
+        entries: report.ranked.map((ranked) => ({
+            id: ranked.id,
+            rank: ranked.rank,
+            score: ranked.score,
+            contributions: ranked.contributions,
+        })),
+    };
+}
+/**
+ * Render a {@link ContextExplainReport} as an agent-readable Markdown brief.
+ *
+ * Each focus item is listed with its relevance rank, normalized score, and the
+ * per-signal contributions that produced it (sorted most-contributing first), so
+ * an agent can judge whether the pack is trustworthy before acting on it.
+ */
+export function renderContextExplain(report, options = {}) {
+    const lines = [
+        "# pm context explain",
+        "",
+        `Generated: ${report.generatedAt}`,
+        `Model: ${report.model}`,
+        "Ranking scope: emitted pack (not workspace-wide)",
+        `Signals: ${report.available_signals.join(", ")}`,
+        "",
+        "## Relevance",
+        "",
+    ];
+    if (report.entries.length === 0) {
+        lines.push("_No focus items to explain._", "");
     }
-    if (result.status !== 0) {
-        const stderr = typeof result.stderr === "string" ? result.stderr.trim() : "";
-        throw new CommandError(stderr || "`pm list-all --json --include-body` failed");
+    else {
+        for (const entry of report.entries) {
+            const contributions = Object.entries(entry.contributions)
+                .sort((a, b) => b[1] - a[1])
+                .map(([signal, value]) => `${signal}=${value.toFixed(3)}`)
+                .join(", ");
+            lines.push(`- **${entry.id}** rank ${entry.rank} score ${entry.score.toFixed(3)} — ${contributions}`);
+        }
+        lines.push("");
     }
+    let output = `${lines.join("\n")}\n`;
+    if (options.compress) {
+        output = `${output.split("\n").filter((line) => line.trim() !== "").join("\n")}\n`;
+    }
+    return output;
+}
+/**
+ * Resolve the SDK relevance rank options for one command invocation.
+ *
+ * Builds the workspace lifecycle status registry from pm settings (falling
+ * back to the built-in registry when the tracker has no settings file), pins a
+ * stable clock, and — when an author is resolvable — pulls decayed
+ * served-then-used affinity from the SDK context-usage store so the relevance
+ * model's `usage_affinity` signal reflects real agent feedback.
+ */
+async function resolveSdkRankOptions(ctx) {
+    const now = new Date().toISOString();
+    let statusRegistry;
     try {
-        const parsed = JSON.parse(result.stdout);
-        const items = Array.isArray(parsed) ? parsed : parsed.items ?? parsed.results ?? [];
-        return items.filter((item) => Boolean(item) && typeof item === "object" && typeof item.id === "string");
+        // readSettings returns built-in defaults even for an uninitialized tracker,
+        // so this yields a valid registry for any real workspace root.
+        const settings = await readSettings(ctx.pm_root);
+        statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
     }
     catch (err) {
-        throw new CommandError(`Could not parse pm item JSON: ${err instanceof Error ? err.message : String(err)}`);
+        throw new CommandError(`Could not resolve workspace status registry for relevance ranking: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const author = stringOption(ctx.options ?? {}, "author") ?? ctx.global?.author;
+    let usageAffinity;
+    if (author) {
+        try {
+            const affinity = await readContextUsageAffinity({ pmRoot: ctx.pm_root, author });
+            usageAffinity = affinity.affinity;
+        }
+        catch {
+            // No ledger yet, or unreadable; ranking proceeds without usage affinity.
+            usageAffinity = undefined;
+        }
+    }
+    return { statusRegistry, now, author, usageAffinity };
+}
+/**
+ * Record a context-serving event to pm's own context-usage ledger.
+ *
+ * This closes the feedback loop: every emitted focus and neighborhood item
+ * becomes an included `serve` row in the same `runtime/context-usage.jsonl`
+ * pm's `usage_affinity` signal reads, so a later
+ * `pm context-usage --author <agent>` can report whether the served context was
+ * actually touched. Skipped silently when no author is resolvable, since the
+ * ledger is per-author.
+ */
+async function recordPackServing(ctx, focus, neighbors) {
+    const author = stringOption(ctx.options ?? {}, "author") ?? ctx.global?.author;
+    if (!author)
+        return;
+    const rows = [
+        ...focus.map((item, index) => ({ id: item.id, rank: index + 1, included: true })),
+        ...neighbors.map((item, index) => ({ id: item.id, rank: focus.length + index + 1, included: true })),
+    ];
+    if (rows.length === 0)
+        return;
+    try {
+        await recordContextUsageServing({
+            pmRoot: ctx.pm_root,
+            author,
+            surface: "context",
+            profile: "context",
+            rows,
+        });
+    }
+    catch {
+        // Recording is best-effort: a ledger write failure must not break a pack.
     }
 }
 function setupCommands(api) {
@@ -671,6 +966,7 @@ function setupCommands(api) {
             "pm context-pack --id pm-1234 --compress --format json",
             "pm context-pack --id pm-1234 --format agent --include-deps --section focus --section blockers",
             "pm context-pack --id pm-1234 --max-items 10",
+            "pm context-pack --status in_progress --explain",
         ],
         flags: [
             { long: "--id", value_name: "id", description: "Focus item id (repeatable or comma-separated)", type: "string" },
@@ -692,6 +988,7 @@ function setupCommands(api) {
             { long: "--include-deps", description: "Include per-item dependency info in the context pack", type: "boolean" },
             { long: "--max-items", value_name: "n", description: "Maximum total items (focus + neighbors) in the pack", type: "string" },
             { long: "--section", value_name: "section", description: "Include sections (repeatable). Markdown: summary, focus, neighborhood, neighbors, links, deps. Agent/compact: focus, blockers, next-actions, recent, links, deps, refresh", type: "string" },
+            { long: "--explain", description: "Explain emitted items with ranks/scores relative to the packed subset instead of emitting a pack", type: "boolean" },
         ],
         async run(ctx) {
             const options = ctx.options;
@@ -710,8 +1007,19 @@ function setupCommands(api) {
             const compress = boolOption(options, "compress");
             const includeDeps = boolOption(options, "include-deps", "includeDeps");
             const maxItems = intOptionMin0(options, ["max-items", "maxItems"], 0) || undefined;
+            const explain = boolOption(options, "explain");
             const sections = validateSections(format, [...asArray(options.section), ...asArray(options.sections)]);
-            const pack = buildContextPack(readPmItems(ctx.pm_root), {
+            const items = await readPmItems(ctx.pm_root);
+            const rankOptions = await resolveSdkRankOptions(ctx);
+            const ranker = createSdkRanker(items, rankOptions);
+            // Pre-rank the full corpus so the token-budgeted packer has relevance ranks
+            // for both focus and neighbor candidates before buildContextPack trims.
+            let packer;
+            if (maxItems) {
+                const rankedAll = rankContextItems(items, rankOptions);
+                packer = createSdkPacker(rankedAll, rankedAll);
+            }
+            const pack = buildContextPack(items, {
                 ids: selection.ids,
                 status: selection.status,
                 type: selection.type,
@@ -723,7 +1031,22 @@ function setupCommands(api) {
                 neighborhoodDepth,
                 includeDeps,
                 maxItems,
+                ranker,
+                packer,
             });
+            if (explain) {
+                const explainReport = buildContextExplain([...pack.items, ...pack.neighbors], rankOptions);
+                const output = format === "json"
+                    ? `${JSON.stringify(explainReport, null, compress ? 0 : 2)}\n`
+                    : renderContextExplain(explainReport, { compress });
+                const outputPath = stringOption(options, "output");
+                if (outputPath) {
+                    writeFileSync(outputPath, output, "utf-8");
+                    return { ok: true, format: format === "json" ? "json" : "markdown", explained: explainReport.entries.length };
+                }
+                return renderedCommandResult(output);
+            }
+            await recordPackServing(ctx, pack.items, pack.neighbors);
             const suggestedCommand = buildSuggestedAgentCommand({
                 commandName: "context-pack",
                 selection,
@@ -804,7 +1127,15 @@ function setupCommands(api) {
             const includeDeps = boolOption(options, "include-deps", "includeDeps");
             const maxItems = intOptionMin0(options, ["max-items", "maxItems"], 0) || undefined;
             const sections = validateSections(format, [...asArray(options.section), ...asArray(options.sections)]);
-            const pack = buildContextPack(readPmItems(ctx.pm_root), {
+            const items = await readPmItems(ctx.pm_root);
+            const rankOptions = await resolveSdkRankOptions(ctx);
+            const ranker = createSdkRanker(items, rankOptions);
+            let packer;
+            if (maxItems) {
+                const rankedAll = rankContextItems(items, rankOptions);
+                packer = createSdkPacker(rankedAll, rankedAll);
+            }
+            const pack = buildContextPack(items, {
                 ids: selection.ids,
                 status: selection.status,
                 type: selection.type,
@@ -815,7 +1146,10 @@ function setupCommands(api) {
                 neighborhoodDepth,
                 includeDeps,
                 maxItems,
+                ranker,
+                packer,
             });
+            await recordPackServing(ctx, pack.items, pack.neighbors);
             const suggestedCommand = buildSuggestedAgentCommand({
                 commandName: "context-handoff",
                 selection,
@@ -850,10 +1184,88 @@ function setupCommands(api) {
             return renderedCommandResult(output);
         },
     });
+    api.registerCommand({
+        name: "context-usage",
+        description: "Report which items pm context/next served and which of those were actually touched.",
+        intent: "measure whether served context is being used",
+        examples: [
+            "pm context-usage",
+            "pm context-usage --format json",
+            "pm context-usage --surface next --since 7d",
+            "pm context-usage --by agent-a --limit 50",
+        ],
+        flags: [
+            { long: "--by", value_name: "author", description: "Restrict to one recording author", type: "string" },
+            { long: "--surface", value_name: "surface", description: "Restrict serve events to one surface: context or next", type: "string" },
+            { long: "--since", value_name: "when", description: "Drop events at or before this point (ISO timestamp, or a day offset such as 7d)", type: "string" },
+            { long: "--limit", value_name: "n", description: `Maximum per-item rows (default: ${DEFAULT_REPORT_LIMIT})`, type: "string" },
+            { long: "--format", value_name: "format", description: "Output format: markdown or json (default: markdown)", type: "string" },
+        ],
+        async run(ctx) {
+            const options = ctx.options ?? {};
+            const requestedFormat = stringOption(options, "format")?.toLowerCase();
+            if (requestedFormat && requestedFormat !== "markdown" && requestedFormat !== "json") {
+                throw new CommandError("--format must be markdown or json", EXIT_CODE.USAGE);
+            }
+            const surface = stringOption(options, "surface")?.toLowerCase();
+            if (surface && surface !== "context" && surface !== "next") {
+                throw new CommandError("--surface must be context or next", EXIT_CODE.USAGE);
+            }
+            const rawSince = stringOption(options, "since");
+            const since = rawSince === undefined ? undefined : resolveSince(rawSince);
+            if (rawSince !== undefined && since === null) {
+                throw new CommandError(`--since '${rawSince}' is not an ISO timestamp or a day offset such as 7d`, EXIT_CODE.USAGE);
+            }
+            // This is a *filter* over recorded ledger events ("whose usage to report"),
+            // which is a different concept from pm's host-owned global `--author`
+            // ("override mutation author for this invocation"). Reusing the global
+            // would silently narrow every report to the invoking agent, so this keeps
+            // a distinct `--by`.
+            const author = stringOption(options, "by");
+            const report = reportContextUsage(ctx.pm_root, {
+                author,
+                surface,
+                since: since ?? undefined,
+                limit: intOption(options, "limit", DEFAULT_REPORT_LIMIT),
+            });
+            // When an author is selected, fold in pm's own decayed served-then-touched
+            // affinity from the SDK context-usage store. This is the same `usage_affinity`
+            // signal the relevance model consumes, surfaced directly so an agent can see
+            // which items its prior touches reinforced — without this module re-implementing
+            // pm's decay model. The event-based waste/misses/conversion report stays because
+            // the SDK does not expose the raw ledger event stream (see SDK_PROBLEMS).
+            let affinity;
+            if (author) {
+                try {
+                    affinity = await readContextUsageAffinity({ pmRoot: ctx.pm_root, author });
+                }
+                catch {
+                    affinity = undefined;
+                }
+            }
+            const reportWithAffinity = affinity ? { ...report, affinity } : report;
+            // pm's global --json owns that flag name, so a command-level alias would be
+            // silently shadowed and never populate ctx.options. Read the global instead,
+            // so `pm context-usage --json` returns the raw report as an agent expects.
+            const wantsJson = requestedFormat === "json" || ctx.global?.json === true;
+            return wantsJson ? reportWithAffinity : renderedCommandResult(renderUsageReport(reportWithAffinity));
+        },
+    });
 }
+/**
+ * Local stand-in for the SDK's `defineExtension` identity helper.
+ *
+ * This package resolves `@unbrained/pm-cli` at runtime for the `sdk/core` and
+ * `sdk/query` engines (it is a peer dependency the pm host provides), but
+ * `defineExtension` itself is a pure identity with no runtime behavior, so a
+ * local shim avoids a needless value import while still contract-checking the
+ * extension object against {@link ExtensionModule} exactly as the imported
+ * helper would.
+ */
+const defineExtension = (module) => module;
 export default defineExtension({
     name: "pm-context",
-    version: "2026.7.25",
+    version: "2026.7.27",
     description: "Generate deterministic pm context packs for agent handoffs, reviews, and status briefs",
     activate(api) {
         setupCommands(api);