SDK extension inventories, scoped activation, and stable agent context

Merged
UN
3mo ago
+2259-298

Summary

This broad SDK/CLI context-management tranche makes extension contributions statically discoverable and durable, honors declared activation scopes across every capability, stabilizes metadata caches across extension modes, adds token-bounded extension health to pm context, and turns failed declared extension commands into accurate actionable recovery. It also refreshes newly vulnerable transitive dependencies and the current compatible tsx patch.

  • Persist a typed schema-versioned contribution inventory from real install-time activation, with static manifest discovery and public SDK authoring contracts.
  • Make explicit activation.commands authoritative while preserving conservative compatibility for legacy packages and eager global contributions.
  • Retain up to four fingerprint-keyed metadata/body/collection cache variants so normal and --no-extensions reads stop evicting one another.
  • Add bounded extension_health context with --no-extension-health; empty installs add zero bytes and the large-workspace baseline remains exactly 1,231 estimated tokens.
  • Correlate unknown commands with declared contributions and activation failures before generic typo guidance, with aligned JSON/human recovery.
  • Require patched brace-expansion and PostCSS floors; refresh the lockfile and tsx 4.23.5.

PM lineage

Verification

  • 428 test files / 6,791 tests pass.
  • Coverage is exactly 100% statements, branches, functions, and lines.
  • ESLint has zero warnings; jscpd finds zero clones; docstring/export/member coverage gates are 100%.
  • Static SDK surface, package boundary/parity, token budget, context calibration, CLI transport, and entrypoint cost gates pass.
  • Secrets scan passes and pnpm audit reports no known vulnerabilities. GitHub Dependabot, code-scanning, and secret-scanning APIs reported zero open alerts before publication.
  • Packed npm/npx and Bun/bunx consumers were initialized in unrelated temporary roots; create/context JSON flows passed. A scaffolded third-party extension persisted contributions, invoked its lazily activated command, and appeared in context health.
  • The packaged npx smoke and 88-command package-first dogfood suite pass.
  • Real 2,000+ item alternating reads restore cached variants: list 0.432s/0.346s, get 0.440s/0.348s, context 1.771s/1.355s, and next 0.751s/0.694s for extension/no-extension modes.
  • pm validate reports zero history drift. The graph has 10,781 edges with no active isolated or degree-one items; remaining graph findings are legacy informational history.
  • pm-changelog@2026.8.3 is current and generated CHANGELOG.md is unchanged because these items remain in progress until merge/release proof.

Compatibility notes

npm-package-arg 14 is intentionally not adopted because its Node engine excludes the supported Node 22.18 floor. TypeScript 7 is intentionally deferred because the current typescript-eslint peer range is below 6.1. These are incompatible majors rather than unattended safe updates.

Summary by Sourcery

Stabilize extension-related runtime behavior by introducing a static contribution inventory, tightening activation scoping, preserving multiple metadata cache variants per context, and exposing installed extension health in pm context, alongside improved CLI recovery for failed extension commands and refreshed dependency floors.

New Features:

  • Persist a schema-versioned extension contribution inventory at install time and expose it through SDK authoring and managed extension state.
  • Add a token-bounded installed extension health summary to pm context, with CLI flags and tool contracts to opt out.
  • Support static extension-manifest contributions for discovery without importing extension modules and surface them in install results and docs.
  • Enhance CLI unknown-command handling to correlate failures with declared extension commands and return actionable recovery guidance in text and JSON.

Enhancements:

  • Bound item metadata caches to up to four context fingerprints so extension and no-extension modes retain separate cache variants and degrade gracefully when enumeration fails.
  • Refine extension activation decisions to honor explicit activation.commands for all capabilities while still activating global contribution surfaces when required.
  • Refactor extension discovery and loader logic to normalize manifests, managed state, and contribution inventories into shared contracts and helper modules.
  • Extend context markdown and release readiness checks to include extension health projections and section coverage.
  • Adjust governance-audit extension manifest and activation behavior to align with new activation and contribution rules.

Build:

  • Raise brace-expansion and postcss dependency floors, add a minimum-age exclusion for tsx 4.23.5, and bump the tsx dev dependency version in package.json.

Documentation:

  • Update extension authoring documentation and manifest schema to describe the contribution inventory contract, authoritative activation.commands semantics, and install-time persistence.
  • Refresh fixtures and public SDK surface documentation to reflect new context flags, parameters, and extension health fields.

Tests:

  • Add unit and integration coverage for contribution inventory normalization and persistence, context extension health behavior, bounded cache identity handling, and extension command activation recovery flows.
  • Update existing extension startup, CLI error, recovery, and release-readiness tests to validate new activation decisions, diagnostics, and context sections.

Summary by cubic

Persist extension contributions and enforce command-scoped activation to load only what’s needed. Adds extension health to pm context, hardens and stabilizes cache variants across modes, improves failed command recovery, and updates vulnerable deps.

  • New Features

    • Persisted versioned contribution inventory and public SDK helpers (createExtensionContributionInventory, normalizeExtensionContributionInventory).
    • Scoped activation honors declared activation.commands across all capabilities; uses static contributions for matching.
    • Metadata cache keeps up to four fingerprinted variants and safely prunes them; context variants are memoized so extension/--no-extensions modes don’t evict each other.
    • pm context includes token-bounded extension_health; opt out with --no-extension-health (SDK: noExtensionHealth).
    • Recovery for unresolved extension commands leads with declared-command correlation and repair suggestions; publishes extension_command_activation_failed and JSON extension_command_failure.
    • Manifest schema adds contributions; publishes CLI/SDK contracts for --no-extension-health and the new error code.

  • Dependencies

    • Patched transitive vulnerabilities: brace-expansion ≥ 5.0.9, postcss ≥ 8.5.23; bumped tsx to ^4.23.5.
    • Intentionally defer incompatible majors (npm-package-arg@14, TypeScript 7).