RFC: Reconcile agent-communication and agentv2 before rebasing onto dev

[yanekyuk]

Integration update — preservation plan implemented

The operator chose separate implementations, superseding the consolidation proposal below. The rebased integration is published in draft PR #1595, based on pinned dev eeab341624fe67b2eeb623abf8f8ed1afc20b5c6.

• Our @indexnetwork/agent remains the API default, with PersonalAgentService, durable private records, current-context fences, exact question batches, explicit H2A activations, both TUI modes, and explicit-query discovery.
• Agentv2 remains independent: first-contact suitability, readable per-opportunity briefs/decisions, outreach before answers, independent questions, and coalesced stall-triggered wakes. Its brief-update policy is not silently replaced with our hosted invalidation policy.
• Both use the authoritative API/protocol for executor ownership and legal actions. V2 consumes authoritative actions; only the original responder accepts, and agreement remains pending human approval. Follow-up verification fixed its event-recovery/startup races and fenced external openings against executor handover.
• Seref's native Hermes think/speaker implementation was ported, not deferred. It uses NegotiationSpeaker and failure-safe FilePrincipalRecords, fresh tool/context binding, hard termination, and an explicit INDEX_EXECUTOR_ID. Old model checkpoints are not restored.
• Dev's independent infrastructure/UI improvements and squashed migration baseline are retained. Migration 0003_add_principal_records_and_negotiation_sessions preserves relevant evidence before removing obsolete runtime storage; old feature journals are not concatenated.

Verification includes the existing 44 tests, affected builds/typechecks and architecture/parity checks, disposable PostgreSQL/pgvector and real Redis probes, actual independent agent workflow probes, and real native Hermes loop probes with fixture model replies. Negative probes reproduced and then passed the v2 recovery and executor-opening fixes. Live-provider and visual/interactive checks were not rerun for this rebased integration. Fixture authentication/model/embedding inputs do not certify a full authenticated deployment or model judgment.

The exact-SHA lease publication was approved; original history and untracked hooks are preserved. No merge, deployment, or shared/production migration was performed. See the PR and REBASE_TODO.md for the implemented boundaries and verification details.

---

Historical pre-rebase comparison

The original proposal and snapshot analysis below are retained for context, not as the accepted implementation plan.

Why this discussion

feat/agent-communication and the agent work now on dev address many of the same problems, but with different runtime structures and product behavior. Before integrating them, we should explicitly choose what to keep, port, or drop—not let Git conflict resolution make those decisions.

Proposal: use dev as the integration foundation, selectively port the valuable behavior and correctness guarantees from feat/agent-communication, and converge on one execution path. This is a starting point for discussion, not an agreed design.

Snapshot reviewed

• Feature branch: 78ad2a676, with 31 commits not on the reviewed dev.
• dev: eeab34162, with 83 commits not on the feature branch.
• A tip-to-tip git merge-tree preview reported 57 conflicting paths. This is not a prediction of the per-commit rebase conflict count, and cleanly merged files can still disagree semantically.

No rebase or integration has been performed. These observations come from source inspection, not a completed runtime or migration validation.

Proposed keep / port / drop direction

Area	Proposed direction
Runtime and integration	Prefer dev's stateless agentv2 functions, shared @indexnetwork/client contract, and hosted/external integration. Port required behavior into the chosen runtime rather than retaining competing schedulers. Bring the TUI onto that same behavior.
Infrastructure and clients	Preserve dev's Redis Streams transport, opportunity-based negotiation routes, and recent web/mac/Hermes work. Replayable transport does not replace duplicate-effect and stale-write guards.
Authority and persistence	Port the feature branch's scoped authority handling, structured private briefs, context/ownership fences, and atomic opening-plus-brief guarantees. Machine-readable authority should not depend on parsing display-text prefixes. Which brief summaries the principal sees can be a separate presentation decision.
Discovery	Prefer dev's current discovery API/retrieval foundation; carry over the required network-scope and admission checks. Do not restore the removed HyDE pipeline or an obsolete parallel implementation. Opening policy still needs a decision below.
Questions	Preserve stable question identity, explicit retirement distinct from an answer, and transactional persistence. Resolve the different batch and stale-answer semantics explicitly.
Sessions and protocol rules	Treat the feature branch's repeat negotiation sessions/history and responder-only acceptance as deliberate feature decisions to confirm—not incidental conflict resolutions. If retained, update the runtime, HTTP client, API, TUI, and UI together.
Database and generated files	Keep dev's squashed migration baseline and unprefixed table names. Generate new migrations for the retained schema changes, with explicit data transformations where needed. Regenerate generated artifacts from the selected source.

Briefs: the contract we need to reconcile

The word “brief” currently describes two different contracts. In the feature branch, a standing brief is an intent-wide mandate for unseen counterparties, and a specific delegation is a complete replacement for one opportunity. In agentv2, “standing brief” in comments means the saved brief for one opportunity; there is no equivalent intent-wide fallback record.

Both implementations reconstruct working context from durable records. Both brief bodies are natural-language strings. The feature branch's stronger structure concerns identity, scope, provenance, and write validity—it is not a deterministic engine proving that the model preserved every permission correctly.

Lifecycle comparison

Aspect	feat/agent-communication	Reviewed dev / agentv2
Contents and purpose	A complete mandate: objective, confirmed facts, scoped permissions, conditions, revocations, unresolved terms, and next focus. Distinguishes permission to discuss, agree, and execute. No explicit brief-length cap in these tool schemas.	A compact reason for first contact plus the principal facts needed to make that case. Prompts explicitly exclude times, prices, project specifics, and terms to hold out for. Tool schemas declare a 400-character budget. A separate continue / accept / decline / stop decision accompanies the brief.
Who authors it, and when?	H2A authors the standing brief before discovery/review completion, an opening-specific brief when selecting a candidate, and replacement delegations during later reviews.	briefIfMissing() runs independently for one opportunity before its first negotiated turn, reading the principal conversation and that opportunity—not siblings. Later wakes can replace its brief or issue a decision without changing the existing brief.
Storage and visibility	Typed metadata records in messages, with brief ID, source-message/activation ID, timestamp, and opportunity binding where applicable. intents.standingBriefId selects the active standing brief. These internal records are excluded from normal chat history, previews, and unread counts.	Readable Brief: ... and Decision: ... agent-DM messages tagged with the opportunity. readConversation() recognizes text prefixes; latestBriefs() reconstructs the latest values. The principal can read the bookkeeping in the conversation.
What A2A receives	Exactly one effective brief: latest specific delegation if one exists, otherwise the standing brief. Specific briefs replace rather than stack with older/standing text. A stale specific brief pauses work rather than silently falling back to a newer standing brief.	The latest per-opportunity brief plus its separate decision, alongside the runtime's identity, intent, and negotiation view. No standing/specific hierarchy. Both designs keep principal conversation and sibling negotiations out of the actual A2A model call.
New principal input	Accepted messages/answers clear standing readiness and make older briefs ineligible until H2A reissues them. This is conservative: even unrelated principal input can require rebriefing. Manual wakes and lifecycle events alone do not invalidate briefs.	Messages/answers mark applicable opportunities as answered, but do not invalidate or remove their existing brief. The wake decides what to change; an unchanged brief remains available to negotiators.
Updating and resuming	A replacement specific brief is complete and explicitly retriggers that opportunity after commit. Saving a standing brief enables new matches but does not itself restart existing negotiations. Updating one specific brief does not invalidate siblings through the brief-version component.	set_brief can retain the old text and change only the decision. onBrief persists that opportunity's outputs and starts eligible negotiation immediately, while the wake continues. stop and the host's stall guards affect whether work runs.
Persistence boundaries	A newly created negotiation and its first specific brief commit together. A review's final messages, retirements, and replacement delegations commit as one fenced effects batch. Standing-brief saves and openings can already have committed earlier: the entire H2A review is not one transaction.	A brief and decision published together use one H2A-entry transaction in the API. Opportunity creation is a separate earlier operation; missing-brief generation happens afterward. Each opportunity can progress without waiting for all wake outputs.
Freshness at the write boundary	Brief writes are tied to observed principal context; A2A turn writes carry a brief-relevant context version as well as expected turn count. The host rejects effects from obsolete input/brief context.	The reviewed brief publication path has no equivalent principal-source version binding; runNegotiate() submits expected turn count but no brief/principal-context version. A turn-count check alone cannot detect a correction made while the model was thinking.

The 400-character value above is a declared tool-schema constraint, not a local validation guarantee: the reviewed tool loop parses JSON and calls handlers without enforcing the complete JSON Schema. Likewise, neither implementation can claim permission correctness solely because a brief was persisted successfully.

What each approach contributes

• Dev's useful property is independent per-opportunity progress. First briefs do not consume the shared wake's tool-step budget, and one published decision can start its negotiator while the wake continues. Compact briefs avoid repeating context already supplied by the runtime. The trade-off is that separately authored briefs need an explicit consistency and freshness contract.
• The feature branch's useful property is an explicit mandate lifecycle. It separates intent-wide authority from counterpart-specific authority, tracks the source of a brief, and prevents stale effects. The trade-off is conservative invalidation and more H2A coordination; a harmless new message can temporarily stop work whose mandate has not substantively changed.

Brief decisions to settle explicitly

1. Granularity: do we need both an intent-wide mandate and complete per-opportunity replacements, or only per-opportunity briefs? Do not accidentally reinterpret dev's per-opportunity “standing” brief as the feature branch's intent-wide one.
2. Contents: is a brief a short first-contact rationale or the complete delegated mandate? Choose that before adopting the 400-character budget or excluding negotiated conditions. Concision must not erase a restriction the product intends to enforce.
3. Freshness: should every principal message invalidate prior briefs, or should only affected mandates change? If invalidation is selective, what prevents an already-running negotiator from writing under revoked authority before the wake finishes?
4. Authoring and activation: can a separate one-opportunity run author its own initial brief, and must matching wait for an intent-wide brief? Can a committed per-opportunity update start work before the rest of H2A finishes? These are separate decisions from whether the resulting write is atomic and current.
5. Storage versus presentation: should users see raw briefs/decisions, a readable summary, or neither by default? That should not determine whether the canonical record has explicit type, scope, provenance, and version checks.
6. Decision versus mandate: keep an explicit action directive separate from the brief, or let A2A choose within the mandate? In either case, an accept directive must not override protocol legality, missing material facts, or principal authority.

Candidate synthesis, not a settled design: retain dev's small briefing functions and independent opportunity scheduling where they fit the chosen policy, while carrying over explicit record identity/scope, source provenance, persist-before-run ordering, and stale-context fences. Decide the mandate hierarchy, visibility, and invalidation policy rather than inheriting them accidentally with either runtime.

Brief-focused verification should include: a correction arriving during a model call; permission for one counterpart not leaking into another's brief; replacing a standing brief while a stale specific delegation exists; one brief update leaving unrelated negotiators alone; and a crash between opening, briefing, and taking the first turn.

Product decisions we need to make

These behaviors cannot simply be combined into one prompt or implementation:

Decision	feat/agent-communication	Reviewed dev
What is the brief contract?	Intent-wide standing mandate plus complete specific replacements; private typed records, provenance, and explicit invalidation.	Compact per-opportunity brief plus separate decision; readable transcript records and wake-driven updates. See the lifecycle comparison above.
What wakes H2A?	Accepted principal input, explicit manual wake, and intent creation/broadcast. A2A pauses do not wake H2A.	Principal input, intent creation/resume, and batched wakes for previously unread negotiation stalls.
What does negotiation accomplish?	Pursue the delegated objective and its material conditions; do not reduce it to a generic introduction to bypass missing facts or authority.	Establish whether there is a real reason for a first connection; leave times, prices, and project specifics to the humans.
Who gets approached?	Search, evaluate/select candidates, and open with a private brief. Standing-brief readiness gates new matches.	Search across several queries and automatically open up to 30 deduplicated results; brief each opportunity separately afterward.
How do questions and answers behave?	A stable batch of up to three questions; accept exactly the current complete batch or nothing. Direct messages remain distinct from answers.	Allow additional questions and partial answers; preserve stale answers as ordinary principal messages rather than rejecting them.

For each row, which behavior is intentional going forward? If we choose a different policy from either branch, we should state it explicitly rather than introduce flags supporting both indefinitely.

Shared invariants worth retaining regardless of those choices:

• Counterparty text cannot grant principal authority or rewrite agent instructions.
• Missing material principal facts must not be invented or silently bypassed.
• Agent agreement, user approval, and completed real-world action remain separate.
• A correction or revoked permission must prevent effects based on obsolete authority.
• A question retirement is not an answer or consent.

Concrete integration traps

1. Acceptance rules can disagree without a textual conflict. agentv2 currently constructs actions including accept for either side after the first turn. The feature branch's protocol permits only the fixed responder to accept. If we keep that rule, the client contract and runtime must consume the authoritative legal actions too.
2. Deleting an old adapter is not a standalone cleanup. The feature branch removes agent-session.database.adapter.ts, while dev adds conversation-service calls into it. We must move its retained responsibilities and all callers together, not restore a second persistence path just to compile.
3. The migration histories are incompatible. Reviewed dev has the new 0000–0002 history; the feature adds 0182–0187 against the old schema. Do not concatenate journals or replay SQL against the old protocol_* names. Preserve relevant existing records before removing obsolete storage.
4. Stateless model calls still need effect fencing. A run can read records, spend time reasoning, and then write after input or executor ownership changes. Choosing the simpler runtime should not discard the feature branch's checks at the write boundary.

Suggested integration process

1. Checkpoint both implementations and local changes. Preserve the original feature history and record the remote branch SHA before any rewrite.
2. Agree on a keep / port / drop checklist. Every feature gets an explicit disposition, including work already implemented differently on dev.
3. Selectively replay onto a pinned origin/dev commit in the existing task worktree. Keep the original branch intact while building the integration branch. Avoid blanket ours / theirs conflict resolution and replaying superseded intermediate implementations.
4. Integrate in small, reviewable slices. Start with the chosen runtime/host contract and persistence guarantees, then questions, discovery/opening, negotiation sessions/rules, and affected UI/TUI consumers.
5. Verify behavior as well as compilation. Cover stale input, executor handover, duplicate events, interrupted runs, question retirement, session reopening, and acceptance rules. Run the existing relevant checks. Validate fresh setup and upgrade from the current dev schema in a disposable database; do not experiment on production. Agree separately before adding new test suites.
6. Review the final diff against dev. Reconcile package versions/changelogs, lockfile versions, and mirrored-package parity. Open the integration PR into dev; do not merge as part of the replay. If replacing published feature history, coordinate first and use a lease bound to the recorded remote SHA.

Requested feedback

• Is dev's runtime/integration structure the right foundation, with the feature branch's correctness guarantees ported into it?
• Which outcome do we want for each of the five policy decisions above?
• For briefs specifically, what should their scope, required contents, invalidation, authoring/activation, and user visibility be? Should the action decision remain separate from the mandate?
• Should repeat negotiation sessions and responder-only acceptance remain part of this integration?
• Is there behavior from either implementation missing from this comparison that must not regress?

Once these decisions are explicit, we can agree on the smallest first integration slice rather than beginning with a mechanical 31-commit rebase.

Code references from the reviewed snapshots

• agentv2: wake, brief, negotiate, and host reconstruction
• Dev brief authoring, contents, and decision contract
• Dev brief persistence/reconstruction and A2A handoff
• Feature brief authoring and review commit boundaries
• Feature effective-brief selection and turn freshness checks
• Hosted agent scheduling and stall wake behavior
• Dev discovery and opportunity creation
• Feature branch's agent behavior and authority rules
• Feature branch's record, question, and brief contracts
• Feature branch's transactional persistence and effect fences
• Feature branch's protocol acceptance rules