Convergence audit: merge parallel WordPress agents-api extractions

[lezama]

Goal

Two parallel extraction efforts have been building toward an OSS-able WordPress-shaped agents substrate from different starting points:

• This repo (Automattic/agents-api), extracted from Extra-Chill/data-machine.
• A second extraction inside a large WordPress install, extracting from a lib/ai/agents/ runtime into a local mu-plugins/agents-api/ package.

The goal is a single OSS plugin that both major adopters (and any future consumer) build on top of, with zero forks. This issue is the convergence map: what overlaps, what diverges, and the PR sequence to land canonical.

Inventory comparison

Already in canonical (this repo) but not in the second extraction

The substrate has shipped a much wider contract surface in PRs #65–#73:

• src/Approvals/ — pending action / approval primitives
• src/Auth/ — access grants, token store, capability ceiling, authorization policy
• src/Consent/ — consent policy contracts
• src/Context/ — composable context, memory layer/registry, authority cascade, conflict resolution
• src/Identity/ — agent identity scope, materialized identity, store
• src/Memory/ — full memory store contracts (with workspace + provenance)
• src/Packages/ — agent package + artifact registry
• src/Runtime/ — AgentConversationLoop, completion policy, transcript persister, compaction, iteration budget, execution principal, message envelope
• src/Tools/ — tool execution core, source registry, action policy, runtime tool declaration
• src/Transcripts/ — ConversationTranscriptStoreInterface
• src/Workspace/ — AgentWorkspaceScope

In the second extraction but not in canonical

1. Heavy WP_Agent runtime base class that integrates LLM loop + provider + session + memory + hooks + context tree + token streaming + async + compaction in one class. Canonical's pattern is the opposite: thin value object (Registry/class-wp-agent.php) + AgentConversationLoop composition.

2. Five typed lifecycle event objects — WP_Agent_Stream_Delta, WP_Agent_Progress, WP_Agent_Queued, WP_Agent_Input_Required, WP_Agent_Final_Result. These are the working precedent for the typed-events option in Clarify event sink contract: on_event callable vs documented filter #75 (already commented there with detail).

3. Concrete memory stores — guideline-backed and markdown-backed implementations of the memory store interface. Data Machine has parallel implementations of the same shape (DiskAgentMemoryStore, GuidelineAgentMemoryStore). See companion proposal: "agents-api-default-stores companion plugin" — separate issue to follow.

4. Concrete CPT-backed session store — implements the conversation transcript contract. Same default-stores question applies.

5. Provider abstraction — WP_Agent_Provider interface, WP_Agent_Provider_Factory, WP_Ai_Client_Provider. Canonical's README explicitly excludes provider code (delegates to wp-ai-client). The second extraction's provider classes stay outside the substrate as the host's adapter — this is the right boundary, no convergence needed here.

Same idea, different name

Convergence means picking one name and migrating the other:

Second extraction	Canonical	Notes
WP_Agent_Conversation_Store (interface)	ConversationTranscriptStoreInterface	Same shape, different namespace
WP_Agent_Memory_Store (interface)	AgentMemoryStoreInterface	Same shape, canonical's adds workspace fields
WP_Agents_Registry	WP_Agents_Registry	Both exist; merge to canonical
WP_Agent (value object aspects)	WP_Agent (value object)	Both exist; canonical's is already the thin shape
WP_Agent_Message, WP_Agent_Tool_Call, WP_Agent_Tool_Result	AgentMessageEnvelope, Tools/ToolCall, Tools/ToolExecutionResult	Comparable; canonical wins on namespacing

Convergence PR sequence

In order, smallest to largest:

1. Lift typed lifecycle events into canonical (src/Runtime/Events/). Parallel implementation can switch to use AgentsAPI\\AI\\Runtime\\Events\\… once landed. Resolves Clarify event sink contract: on_event callable vs documented filter #75. Small.

2. Land conversation lock/unlock on ConversationTranscriptStoreInterface (Add conversation lock/unlock to ConversationTranscriptStoreInterface #74). Both extractions need this for long-running loops; canonical defines the contract once. Small.

3. Land cross-site A2A caller context (Add cross-site agent-to-agent caller context primitive #76). Substrate defines WP_Agent_Caller_Context + the header convention. Medium.

4. Default-stores companion plugin — extract the two pairs of parallel memory store impls (guideline-backed, markdown/disk-backed) plus the CPT session store into agents-api-default-stores. Removes duplication; gives outside adopters working stores from day one. Medium, separate issue.

5. Refactor the second extraction's WP_Agent to thin value object + AgentConversationLoop composition. All current behavior of the heavy base class is reachable through the loop's adapter slots: provider via the runner adapter, memory via the store adapters, transcript via the persister adapter, lifecycle via the typed events from step 1, compaction via the existing AgentConversationCompaction class, async/queued via the Queued typed event. Large. The architectural lift.

6. Replace local interface declarations with canonical imports in the second extraction. Drop WP_Agent_Conversation_Store, WP_Agent_Memory_Store, WP_Agent_Provider (provider stays as a host-side adapter, just stops being declared as a substrate interface). Small mechanical PR after step 5.

7. Vendor canonical in the second extraction via git subtree at the original agents-api/ path. The mu-plugin package becomes the host-side adapter only. Small.

Verification — non-regression on every concrete agent

The second extraction has many concrete WP_Agent subclasses already running in production (block editing, site building, P2 chat, reader chat, support, orchestrator, internal tooling, workflow agents, and more). Each one is a risk surface for the refactor in step 5.

The convergence cannot land without a verification story. Proposed gates:

• Contract tests against every concrete agent. A test harness that instantiates each subclass, runs a fixed prompt + tool sequence against a recorded provider, and asserts the produced messages, tool calls, and final result match a recorded baseline. Lives in the consumer (the second extraction), runs in CI on every convergence PR. Recordings produced from the current heavy WP_Agent before any refactor.

• Sandboxed shadow runs. For the higher-traffic agents (chat-facing ones), route a fraction of real production traffic through both the legacy and refactored paths, diff the produced transcripts, alert on divergence. Ramp-up gated.

• Per-feature smoke abilities. Each agentic feature (block edit, site build, P2 chat, reader chat, support search, etc.) gets a one-shot smoke test that runs the user-visible feature end-to-end. Runs in pre-merge CI plus a daily watcher.

• Compatibility shim during migration. The legacy heavy WP_Agent stays available under its current name and lazy-delegates to the new thin value object + loop composition for one release cycle. Concrete agents migrate one at a time.

• Telemetry watch on production rollout. Tool-call success rate, transcript length, completion-status distribution, time-to-first-token monitored before/after each rollout slice. Auto-rollback gate on regression.

The contract test harness is the gating dependency for step 5 — it should land before the refactor starts, not after.

Out of scope

• Provider-specific code stays outside canonical (delegated to wp-ai-client).
• Concrete admin UI, REST routes, and product workflows stay in the consumer (boundary already in canonical's README).
• Episode detection, context-tree variable substitution, and other above-the-substrate memory engineering primitives stay in the consumer for now. They're candidates for follow-up substrate primitives later, after the convergence settles.

AI assistance

• AI assistance: Yes
• Tool(s): Claude Code (Opus 4.7)
• Used for: Side-by-side inventory of the two parallel extractions, drafting the convergence sequence, and identifying the regression-test gating dependency.

[chubes4]

Status after #65-#73 and the new #74-#78 issues

I re-checked main plus the current issue set. The original convergence shape in this issue still looks right: canonical should stay the thin substrate, and the second extraction should converge by replacing local substrate interfaces/classes with canonical imports rather than by moving product/provider/runtime-policy code into this repo.

Now covered in canonical

The #65-#73 batch closes most of the scope-model substrate gap from #55:

Area	Owning issue / PR	Current status
Guideline capability mapping for scoped private memory/shared guidance	#62 / #65	Landed in src/Guidelines/ and documented in README.
Consent policy for memory/transcripts/sharing/escalation	#60 / #66	Landed in src/Consent/.
Workspace scope across memory and transcript contracts	#56 / #67	Landed as AgentWorkspaceScope; transcript sessions are workspace-stamped.
Memory/context registry and composable context sections	#63 / #68	Landed in src/Context/.
Memory provenance, confidence, validators, and authority metadata	#61 / #69	Landed in src/Memory/ and documented.
Retrieved-context authority cascade and conflict resolution	#64 / #70	Landed in src/Context/.
Durable approvals and pending-action audit contracts	#59 / #71	Landed in src/Approvals/.
Generic tool visibility/action policy contracts	#57 / #72	Landed in src/Tools/ and documented.
Agent auth grants/tokens/capability ceilings	#58 / #73	Landed in src/Auth/.

Net: the broad canonical substrate now covers identity/auth, workspace scope, memory metadata/provenance, context composition/authority, consent, approvals, tool policy, transcript contracts, loop contracts, compaction, and iteration budgets.

New work now owns the remaining canonical gaps

Gap from this convergence audit	Owning issue	Notes
Transcript single-writer safety for async/long-running/shared sessions	#74	Still open. This should be canonical because update_session() replaces the whole message array and races are host-generic. I agree with splitting the lock surface from the base transcript interface if we want stores to make locking support type-checkable instead of silently no-op.
Loop lifecycle observer/event contract	#75	Still open. The typed event precedent from the second extraction is the strongest new information. This should decide whether on_event remains (string, array) or moves to typed objects; avoid adding both typed objects and a global action unless there is a concrete observer composition need.
Cross-site/A2A caller context	#76	Still open. Canonical has token/client/workspace auth after #73, but not caller-chain identity/depth/root request context. This should stay value-object + header/parser/trust-boundary guidance; host trust enforcement remains out of scope.
Concrete memory/session stores shared by both consumers	#78	Still open. This should be a companion plugin/repo, not this substrate, unless the project decides to violate the current README boundary and ship concrete persistence here.
Heavy second-extraction WP_Agent base-class refactor	This issue (#77), downstream consumer PRs	Not a canonical-code gap. It is the large migration once #74/#75/#76/#78 settle enough for the downstream adapter to target stable imports.
Contract/shadow/smoke verification for existing concrete agents	This issue (#77), downstream consumer CI	Still the gating dependency before replacing the heavy base class in production consumers. This repo can provide fixtures/contracts, but consumer-specific baselines belong downstream.

Issue hygiene worth doing next

A few older umbrella/sub-issues now look stale or superseded by the #65-#73 batch:

• Scope model: promote workspace-scoped memory, permissions, transcripts, and approvals #55 is still open, but most of its concrete scope-model work is now closed through Make workspace scope first-class across memory and transcripts #56-Define authority cascade and conflict resolution for retrieved context #64 and PRs Harden guideline capability mapping #65-Add agent authorization contracts #73. It can probably become a tracking-only umbrella that points at Add conversation lock/unlock to ConversationTranscriptStoreInterface #74-Spin out agents-api-default-stores companion plugin (guideline + markdown + CPT session) #78, or be closed if Convergence audit: merge parallel WordPress agents-api extractions #77 is the convergence umbrella now.
• Add generic agent token binding #13 and Add generic agent access grants #14 are still open, but token binding/access grants appear covered by Promote agent authorization, access grants, tokens, and capability ceilings #58/Add agent authorization contracts #73. If no narrower work remains, close them as superseded/implemented.
• Add markdown-section compaction adapter #17 is still open, but PR Add markdown section compaction adapter #21 merged the markdown-section compaction adapter. If there is no follow-up beyond that adapter, close it as implemented.
• Add Guidelines substrate polyfill for wp_guideline #9 may need a fresh pass against the current Guidelines/ polyfill and Spin out agents-api-default-stores companion plugin (guideline + markdown + CPT session) #78's default-stores capability-type question. It is still relevant only if it tracks the upstream Gutenberg/core guideline substrate relationship rather than local store implementation.

Recommended next PR order

1. Add conversation lock/unlock to ConversationTranscriptStoreInterface #74: lock primitive, preferably as an explicit lock-capable sibling interface plus loop integration only when available.
2. Clarify event sink contract: on_event callable vs documented filter #75: typed lifecycle event objects, keeping the existing callable adapter path if possible.
3. Add cross-site agent-to-agent caller context primitive #76: caller context value object/header parser and execution-principal carry-through.
4. Spin out agents-api-default-stores companion plugin (guideline + markdown + CPT session) #78: create the default-stores companion and delete duplicate concrete stores from both consumers.
5. Downstream verification harness against the second extraction's concrete agents.
6. Downstream heavy WP_Agent refactor to thin value object + AgentConversationLoop composition.
7. Downstream mechanical import replacement/vendor canonical step.

Rationale for no repo PR from this pass

I do not see a small canonical doc/code patch that improves the repo more than this issue update. The README already states the substrate boundary and documents the main #65-#73 surfaces. The remaining work is either open design (#74/#75/#76), a sibling repo decision (#78), or downstream migration/verification work (#77). A PR here would risk turning a planning/convergence issue into premature surface area.

AI assistance

• AI assistance: Yes
• Tool(s): OpenCode (GPT-5.5)
• Used for: Inspecting Automattic/agents-api main, reading issues Add conversation lock/unlock to ConversationTranscriptStoreInterface #74-Spin out agents-api-default-stores companion plugin (guideline + markdown + CPT session) #78 and recent PRs Harden guideline capability mapping #65-Add agent authorization contracts #73, mapping covered vs remaining convergence gaps, and drafting this status update for human review.

[lezama]

Aligned on all of this — and I'll take the downstream verification harness as my next concrete deliverable on the second extraction's side, since you've called it out as the gating dep for the WP_Agent refactor.

Splitting ownership the way you've laid out

• Canonical PRs in your lane: Add conversation lock/unlock to ConversationTranscriptStoreInterface #74 (lock, sibling-interface), Clarify event sink contract: on_event callable vs documented filter #75 (typed events, just pick one path), Add cross-site agent-to-agent caller context primitive #76 (caller-context value object + header parser).
• Companion repo decision: Spin out agents-api-default-stores companion plugin (guideline + markdown + CPT session) #78 — you're best positioned to say whether agents-api-default-stores lives as a sibling repo under Automattic, what the dependency-pinning relationship looks like, and who owns the initial scaffold.
• Downstream consumer work in my lane: contract-test harness against the second extraction's concrete WP_Agent subclasses, then the heavy → thin refactor once Add conversation lock/unlock to ConversationTranscriptStoreInterface #74/Clarify event sink contract: on_event callable vs documented filter #75/Add cross-site agent-to-agent caller context primitive #76 settle, then the mechanical import-swap / vendor-canonical step.

Issue hygiene

Agreed on the stale ones. I don't want to step on your tracker, but if it helps: I'm happy to close the ones that are clearly superseded (#13, #14, #17 against PR #21) on your say-so, leaving the umbrella questions on #55 and #9 for you. Just say the word.

On verification

I'll start by recording baselines from the existing heavy WP_Agent against each concrete subclass (block editing, P2 chat, reader chat, support, orchestrator, internal tooling, workflow agents, etc.) before any refactor touches the base class. The recordings + replay harness become the contract gate. I'll also wire per-agent smoke abilities into the consumer's CI so each downstream PR runs them. Telemetry watch on production rollout is a separate piece I'll coordinate with the host's ops side.

I'll open a downstream tracking issue (in the consumer's repo, not here) so you can see progress without it cluttering canonical's tracker. Will link it back to this convergence audit.

[lezama]

Restating the end goal explicitly

The destination is: the second extraction effort disappears entirely as substrate code. Only host-side adapters remain. There are no parallel implementations, no divergences, no race between the two repos. Every concrete agent in any host's runtime extends canonical's thin WP_Agent value object and composes WP_Agent_Conversation_Loop (post-#89's naming) — no heavy base class anywhere.

Mapping open issues to that destination

Gating	Issue	What it removes
Naming uniformity	#89	Lets hosts use canonical without a renaming churn after vendoring
Lock primitive	#74	Lets canonical's transcript contract cover what the second extraction already does
Typed lifecycle events	#75	Lets canonical own the events the second extraction emits today
A2A caller context	#76	Lets canonical own a primitive that hosts will need
Default-stores companion	#78	Lets parallel Guideline_Memory_Store impls live in one shared place
Workspace scope on memory + transcript	#67 (landed)	Already there
Auth contracts	#73 (landed)	Already there

After all of these land in canonical: any host's local extraction has zero unique substrate code. Every contract it needs is in canonical.

Gaps in the current plan (not covered by any open issue)

1. Vendor mechanism. Decide once: git subtree pull, composer require, or manual periodic sync. The convergence audit step Add conversation compaction as an Agents API runtime capability #7 says "vendor canonical via git subtree" — but that decision deserves its own discussion (versioning, who pushes, how downstream pins). Probably a sibling issue.

2. Migration cookbook. A short doc in canonical's README (or a new MIGRATION.md) showing the path: "if you have an extracted runtime, here's how to converge — replace local interfaces with canonical imports, refactor your WP_Agent to thin value object + WP_Agent_Conversation_Loop composition, move concrete stores to default-stores, vendor canonical." Future adopters will need this same playbook.

3. A working consumer example beyond the demo. The Site_Assistant_Agent example shows how a fresh greenfield agent looks. But the convergence story needs a more substantive example showing how an EXTRACTED runtime converges. A reference "adapter plugin" repo demonstrating the host-side adapter pattern (without host-specific code) would help every future adopter.

4. Contract test harness lifting. Downstream adopters doing the runtime-to-substrate migration will all want a regression net: a recording provider, a contract runner that can swap the provider in (via reflection where no filter exists), and a way to compare baselines from before vs. after a refactor. The pattern is general; worth lifting the harness primitives into canonical's tests/ dir as a reusable utility, separate from any specific agent scenarios.

5. Decommissioning plan. After a host vendors canonical, the local extraction's source files get deleted. That's a separate cleanup PR on the host side — worth tracking explicitly so it doesn't linger as dead-code-with-class-aliases forever.

Suggested next moves on the substrate side

1. Pre-v1 naming convergence: adopt uniform WP_ prefix and drop _Interface suffix #89 (naming) lands first — without naming uniformity, every other rename PR has to revisit names.
2. Add conversation lock/unlock to ConversationTranscriptStoreInterface #74 / Clarify event sink contract: on_event callable vs documented filter #75 / Add cross-site agent-to-agent caller context primitive #76 in any order — each is small.
3. Spin out agents-api-default-stores companion plugin (guideline + markdown + CPT session) #78 (default-stores) alongside or after the above — needs the auth/memory naming settled first.
4. Migration cookbook MR to canonical README, drafted from convergence experience.

Host-side migration steps (heavy → thin refactor, vendor canonical, decommission) live downstream and depend on these landing.

[lezama]

What shipped from the open-issue batch

Quick update on the four issues filed alongside this convergence audit — three are closed, one still open:

Issue	Status	Landed via
#74 — Conversation lock primitive	✅ Closed 2026-05-04	#82 — WP_Agent_Conversation_Lock + WP_Agent_Null_Conversation_Lock, token-based shape exactly as discussed
#75 — Event sink contract	✅ Closed 2026-05-04	#80 — Dual approach: on_event callable + agents_api_loop_event action, both fire, observer exceptions swallowed
#76 — A2A caller context	✅ Closed 2026-05-04	#81 — WP_Agent_Caller_Context value object with X-Agents-Api-Caller-* / X-Agents-Api-Chain-* header constants, SELF_HOST = 'self', DEFAULT_MAX_CHAIN_DEPTH = 16
#89 — Pre-v1 naming convergence	🟡 Open	#90 + #92 — All src/**/*.php now uniformly class-wp-agent-*.php, no _Interface suffix anywhere. Issue probably needs explicit close

All four contracts match the proposals discussed verbatim — really clean execution. With these landed, downstream extractions can now target stable canonical imports instead of carrying parallel implementations.

Filing one sibling issue to capture the next gap from gap #1 above (vendor mechanism). Then the convergence audit's substrate-side work is essentially complete; the remaining items are downstream migration steps that don't need canonical PRs.