feat(sdk): extensible agent identity and model provenance

Merged
UN
3mo ago
+1734-443

Summary

  • add structured harness, model, model-source, and local session provenance across SDK, CLI history, MCP initialization, and telemetry
  • add collision-safe built-in/package/workspace harness signal registries with bounded literal detection and precedence-preserving author resolution
  • remove hard-wired plugin authorship, reduce mutation-help identity overhead, and document normal automatic identity versus intentional principal overrides
  • preserve telemetry privacy with presence-only minimal capture, installation-keyed hashes at richer levels, and no session export

PM lineage

Verification

  • repository release gates: type tests, docs/skills, static quality, 100% docstrings, package boundaries, token budgets, SDK surface/import costs, CLI transport floor
  • 6,376 tests across 370 files
  • coverage: 100% statements / branches / functions / lines
  • packed npx smoke and 88-command package-first dogfood
  • isolated packed consumer: exact installed binary, public SDK settings write, custom harness CLI mutation, history provenance assertion, get, and health
  • Claude plugin smoke: 31-file structure and full flow
  • pnpm audit --audit-level=low: no known vulnerabilities
  • tracked-file secret scan: clean

Compatibility and privacy

Existing author and legacy history remain compatible. New history fields are optional. Explicit authors remain assertions, configured authors remain configured, and detected harness/model observations are recorded independently. Session identifiers remain local history only and are never sent in telemetry.

Summary by cubic

Adds extensible agent identity provenance (harness, model, source, session) with automatic detection across SDK, CLI, MCP, history, and telemetry. Removes hard-wired authors from MCP/help/docs, adds a declarative harness registry, and hardens detection and safety.

  • New Features

    • History/telemetry: record agent_harness, agent_model, and agent_model_source; session stays local-only. Telemetry uses presence-only fields and installation-keyed hashes.
    • Detection/registry: workspace agent_identity.harness_signals; registerHarnessSignalDescriptors(...), detectAgentIdentity, runWithHarnessDetectionSignals/runWithWorkspaceHarnessSignalDescriptors. CLI loads workspace descriptors at parse time. MCP reads and keeps client name/version from initialize for bounded detection.
    • CLI/MCP/docs: help/examples drop redundant author flags; tool docs mark author as an override only; .mcp.json and plugin guides remove PM_AUTHOR and rely on automatic identity.
    • Safety: process-local sessions; bounded descriptor validation; cached normalized built-ins; argv-marker match by executable basename; tolerant env prototypes; de-duped argv inputs; registration cleanup; isolated telemetry tests.

  • Migration

    • No breaking changes; existing author precedence and legacy history remain compatible; new fields are optional.
    • Remove any PM_AUTHOR from local .mcp.json or host configs; rely on automatic identity. @unbrained/pm-cli fallback behavior is unchanged.
    • Avoid --author in normal agent flows; use only for intentional external principals or legacy compatibility.
    • Optionally add agent_identity.harness_signals in settings to register in-house harnesses.