Add A2A and ACP agent substrate

[IvGolovach]

Summary

This adds the first safe substrate for A2A/ACP agents in mesh-llm: operators can now describe local or remote agents in ~/.mesh-llm/config.toml, validate that directory, inspect configured agents, and project either an A2A agent card or an ACP bridge plan without starting agent processes or publishing anything to the mesh.

The goal is to make the agent surface concrete enough to build on, while deliberately stopping before execution, server exposure, gossip advertisement, or cross-node routing semantics.

Why

Issue #692 needs a real agent foundation, not another loose integration stub. A2A and ACP are protocol-shaped surfaces with different trust and execution boundaries:

• A2A agents are remote HTTP(S) endpoints with official A2A agent-card projection.
• ACP agents are local command-backed agents with a deterministic launch/bridge plan.

This PR establishes those boundaries in config, validation, libraries, and CLI inspection so later PRs can add serving/execution paths without mixing protocol metadata, process spawning, and mesh discovery in one risky change.

Diff Scope

• Adds mesh-llm-a2a, a non-published workspace crate using the official a2a-lf crate for agent-card projection.
• Adds mesh-llm-acp-bridge, a non-published workspace crate using the official agent-client-protocol crate for ACP bridge planning.
• Extends mesh-llm-config with [[agent]] entries, protocol-specific validation, and tests.
• Adds mesh-llm agents list, mesh-llm agents show <id>, and mesh-llm agents validate for local operator inspection.
• Updates docs/AGENTS.md with config examples and command usage.
• Updates workspace crate-list tooling so affected-crate and clippy planning know about the new crates.

Explicit Non-Goals

• Does not spawn ACP agent commands.
• Does not host an A2A server.
• Does not gossip agent cards across the mesh.
• Does not change OpenAI routing, model routing, or agent execution semantics.
• Does not change the mesh wire protocol.

Example Config

[[agent]]
id = "codex"
name = "Codex"
description = "Local coding agent"
protocol = "acp"
command = "codex"
args = ["--model", "gpt-5"]
skills = ["coding", "tool-use"]

[[agent]]
id = "remote-coder"
name = "Remote Coder"
description = "Remote A2A-compatible coding agent"
protocol = "a2a"
endpoint = "https://agents.example.com/remote-coder"
skills = ["coding"]

Example Commands

mesh-llm agents list
mesh-llm agents show codex --json
mesh-llm agents validate

Representative text output:

ID      PROTOCOL        ENABLED TARGET  NAME
codex   acp             true    codex   Codex

Branch Integrity

• Base branch: main
• Validated base: fef0f4deddadca3e7d95b8b86e52fa3a60ca0942
• Ahead/behind: 0 behind / 1 ahead
• Merge base: fef0f4deddadca3e7d95b8b86e52fa3a60ca0942
• Introduced commit: 9da57ff3 Add A2A and ACP agent substrate

Commit Integrity

One logical commit is introduced. The final diff contains only agent substrate, config validation, CLI inspection, documentation, dependency lockfile, and crate-list updates required for the new workspace crates.

Diff Hygiene

• git diff --check: PASS, no output.
• git diff --cached --check: PASS, no output.
• git diff --check origin/main...HEAD: PASS, no output.

Validation

Validation tier: Tier 4 - agent control-plane substrate for issue #692; adds config schema, official A2A/ACP protocol crate adapters, CLI inspection, and workspace crate-list consistency without agent execution, gossip, or mesh protocol advertisement.

• git fetch --no-tags origin main:refs/remotes/origin/main: PASS, origin/main at fef0f4deddadca3e7d95b8b86e52fa3a60ca0942.
• git diff --check: PASS, no output.
• git diff --cached --check: PASS, no output.
• cargo fmt --all: PASS.
• cargo fmt --all -- --check: PASS.
• cargo check -p mesh-llm-a2a -p mesh-llm-acp-bridge -p mesh-llm: PASS.
• cargo test -p mesh-llm-config agent --lib -- --test-threads=1: PASS, 2 passed.
• cargo test -p mesh-llm-a2a --lib -- --test-threads=1: PASS, 3 passed.
• cargo test -p mesh-llm-acp-bridge --lib -- --test-threads=1: PASS, 2 passed.
• LLAMA_STAGE_BUILD_DIR=/Users/Funtland/Downloads/mesh-llm/.deps/llama-build/build-stage-abi-metal cargo test -p mesh-llm-host-runtime agents --lib -- --test-threads=1: PASS, 1 passed.
• LLAMA_STAGE_BUILD_DIR=/Users/Funtland/Downloads/mesh-llm/.deps/llama-build/build-stage-abi-metal /opt/homebrew/bin/cargo-clippy clippy -p mesh-llm-config -p mesh-llm-a2a -p mesh-llm-acp-bridge -p mesh-llm-host-runtime --all-targets -- -D warnings: PASS.
• cargo run -p xtask -- repo-consistency ci-crate-lists: PASS.
• cargo run -p xtask -- repo-consistency publish-crates: PASS.
• cargo run -p xtask -- repo-consistency release-targets: PASS.

Ledger / Version

• Ledger: not applicable - not required for selected validation tier/change family.
• Version: not applicable - no release/version sync required; Cargo.lock dependency updates are scoped to the new non-published agent substrate crates.

Not Run

• Live A2A/ACP handshake/server smoke: not required because this PR only creates local config/directory/bridge-plan surfaces and does not spawn or expose agents.
• Live multi-node mesh/gossip smoke: not required because no mesh gossip/protocol advertisement path changed.

Runtime Safety

• No new process spawning.
• No new network listener.
• No new mesh gossip field or protocol message.
• No new OpenAI routing behavior.
• No new blocking locks or unbounded queues.
• No invariant regression introduced.

Documentation Integrity

docs/AGENTS.md now documents the local agent directory shape, protocol-specific requirements, and inspection commands.

Rollback Plan

Rollback: revert this PR.

git revert <post_merge_commit_sha>

DB downgrade: not applicable.
Data repair: not applicable.
Operational caveats: none known. Since this PR is config/CLI/control-plane only, rollback removes the agent directory schema and inspection commands without runtime migration.

Known Residual Risks

The next PRs still need the real execution and distribution layers: ACP process lifecycle, A2A serving/handshake behavior, security review for agent exposure, and any future mesh advertisement/routing semantics. Those are intentionally left out of this substrate PR.

[i386]

@IvGolovach you may want to check out https://github.com/Mesh-LLM/agents :)

[i386]

Contribute to https://github.com/Mesh-LLM/agents

[ndizazzo]

We should also move / update / close #692 so it's not sitting stale on this repo and get picked up again

[IvGolovach]

Thanks, that guidance was right. I moved the agent-owned part of this work into Mesh-LLM/agents here:

Mesh-LLM/agents#1

That PR keeps the A2A/ACP agent-definition validation, CLI diagnostics, and authoring guidance in the repo that now owns the mesh-native agent control plane. It intentionally does not add mesh-llm core runtime, gossip, protocol, or host-runtime hooks.

I’m going to close this PR as superseded rather than keep rebasing it in the wrong repo. Any future mesh-llm change should be a narrow integration hook only if the agents repo needs one.

I’ll also follow up on #692 so the old design issue does not stay stale here and get picked up again. Appreciate the steer.

[IvGolovach]

Follow-up complete: #692 is now closed as superseded and points future A2A/ACP design work to Mesh-LLM/agents#1.

I’m keeping this PR closed for the same reason: the agent-definition validation and CLI diagnostics now live in the agents repo, and any future mesh-llm change should be a narrow integration hook only if that repo needs one. Thanks again for the direction here.