feat(sdk): add reproducible agent environments and lossless criteria merges

Merged
UN
2mo ago
+2726-24

Summary

This PR adds a broad public-SDK foundation for reproducible agent environments while fixing silent acceptance-criteria loss in concurrent tracker merges.

  • publishes declared observation contracts with pre-call ceilings, emitted-byte calibration, corpus-dependence declarations, deterministic tier degradation, and truthful refusal receipts;
  • publishes total, deterministic verdict contracts over recorded state with composable predicates, exact evidence pointers, privacy-safe value digests, and an explicit no-reward boundary;
  • publishes isolated episode specifications and sessions that compose workspace recipes, observable/withheld projections, ordinary PmClient actions, hard limits, scoring, and trajectory evidence;
  • adds a dependency-free executable example that runs reset → observe → ordinary SDK action → verdict → close from the packed public SDK;
  • makes semicolon-backed acceptance criteria use add/remove-aware element union during three-way merge, preserving independent multi-branch additions without changing the storage format;
  • restores exact repository coverage for the MCP uninitialized-workspace guards;
  • records governed PM closeout and generates the changelog with pm-changelog 2026.9.2.

PM lineage

Completed in this delivery:

Substantial SDK/CLI progress, deliberately left open and unclaimed for their documented residuals:

New GitHub reports discovered during the live inventory were deduplicated across all statuses, linked to shipped predecessor lineages, and left open/unclaimed:

Verification

  • pnpm typecheck
  • pnpm quality:static
  • node scripts/run-tests.mjs coverage
    • 603 files / 8,341 tests
    • statements 61,714/61,714
    • branches 46,669/46,669
    • functions 12,840/12,840
    • lines 59,387/59,387
  • focused linked PM tests for all seven worked items
  • focused source coverage for the new environment SDK: 100/100/100/100
  • packed fresh-consumer install and executable SDK environment run in a temporary directory
  • packed npx and bunx smoke: passed across 13 packages
  • package-first dogfood: 88 commands passed
  • pnpm audit --audit-level high: no known vulnerabilities
  • tracked secret scan: no credential-like secrets detected
  • full graph composition, tracker context, defect evidence, and append-only record-integrity assurances passed on the final tracker state

The local release pipeline reached only the hosted-analysis boundary after commit because the SHA had not yet been pushed. This PR supplies the remote head required for that final hosted proof.

Summary by Sourcery

Add reproducible public-SDK agent environments and make acceptance-criteria merges lossless across concurrent branches.

New Features:

  • Publish SDK contracts for calibrated, budgeted observations, deterministic verdicts, and isolated agent-environment episodes.
  • Add a dependency-free executable example demonstrating a complete public-SDK environment lifecycle.

Bug Fixes:

  • Preserve independent acceptance-criteria additions and removals during three-way merges without changing their legacy storage format.
  • Restore coverage for MCP operations against uninitialized workspaces.

Enhancements:

  • Expose reproducible evidence, privacy-safe verdict digests, withheld-field isolation, hard episode limits, and an explicit no-reward evaluation boundary.

Documentation:

  • Document the public SDK agent-environment contracts and executable example.

Tests:

  • Add comprehensive contract, episode, merge, and executable-example coverage for the new behavior.

Chores:

  • Record PM closeout lineage and newly discovered follow-up issues.

Summary by cubic

Adds public SDK contracts for reproducible agent environments and fixes concurrent acceptance-criteria additions being silently discarded during three-way merges.

New Features

  • Publishes observation, verdict, and episode contracts through @unbrained/pm-cli/sdk for reproducible, budgeted agent environments.
  • Adds a dependency-free executable example covering reset → observe → ordinary SDK action → verdict → close.

Bug Fixes

  • Acceptance criteria now merge with add/remove-aware element union, preserving independent multi-branch additions without changing the storage format.
  • Restores exact coverage for MCP operations targeting uninitialized workspaces.
  • Episode isolation is enforced: grading reads count against the observation budget, nested observable/withheld path overlap is rejected, and cyclic or non-JSON verdict operands fail at the contract boundary.
  • Episode closure is atomic: the terminal transition is reserved before grading, concurrent callers share one close result, and the session is restored only when grading fails.