Integrations and API contracts

Choose the interface that matches the caller. These contracts have different responsibilities.

On Linux, ecc run accepts only the dedicated /echo.slice/echo-workers.slice cgroup-v2 boundary. The flag checks current placement and finite limits; the system service must place the worker and its child process tree there. Echo does not create or enforce cgroup limits. Guarded Linux runs also require the root-owned admission service, which must be manually configured and has not completed native VM qualification.

Agent setup planning and native adapters

Pre-release working trees provide the ecc setup command to plan, verify, and apply client integrations. Always plan first before altering any configuration:

# Review proposed registration and review targets
./bin/ecc setup

# Structured machine-readable plan
./bin/ecc setup --format json

Planning discovers agent executables on PATH and produces native registration commands or manual review instructions. It operates strictly read-only: it does not read private configuration, grant permissions, install skills, or edit any files.

The plan reports registration-not-inspected by design: detecting an executable on PATH is discovery, not proof that the client has registered echo, loaded the MCP server, or established network connectivity. In JSON output, command arrays represent argv lists, not shell strings.

Isolated server verification

To verify that the local binary serves MCP correctly before configuring clients:

./bin/ecc setup --check

# Start the command each client has registered instead
./bin/ecc setup --check --agents claude,codex,agy

This probes the server in disposable state and isolated echo configuration, listing the tools and resources it serves and calling echo_whoami. With --agents it starts the command each client has registered, which catches a stale or missing path. Neither form starts the client, so neither proves that a running session has reloaded its configuration.

Explicit apply and remove workflows

Modifying client configuration requires an explicit --agents selection alongside --apply or --remove:

# MCP registration, ecc permission grant and coordination skill
./bin/ecc setup --apply --agents claude,codex,agy

# Remove only unchanged configurations owned by echo setup
./bin/ecc setup --remove --agents claude,codex,agy

• Explicit selection mandatory: Running --apply or --remove without explicit --agents is rejected upfront.
• All components by default: Each selected client gets every component it supports. --mcp, --permissions and --skills limit the run; asking for a component a client lacks is refused before any change. A rerun reports unchanged.
• Removal undoes apply: Removal deletes echo's entries, and any file or settings container that apply created once nothing else is in it, and the empty echo-coordination skill directory. Empty parent directories such as ~/.gemini stay.
• Close client sessions first: Close running agent sessions before modifying their settings. Setup serializes its own file writes and detects concurrent changes, but external clients do not share its lock; a concurrent client save can race the file replacement.
• Unmanaged entries preserved: Setup never silently adopts existing unmanaged echo entries, even if their fields match. If an unmanaged entry is found, setup refuses to overwrite it and exits with a manual-review notice.
• Supported MCP adapters:
  • Claude and Antigravity (agy): Setup manages the mcpServers.echo JSON object in native configuration (~/.claude.json for Claude; ~/.gemini/config/mcp_config.json for Antigravity). Files under ~/.gemini/antigravity-cli/mcp/ are discovery caches, not registration files; never edit them directly. Restart clients after registration to reload tools.
  • OpenAI Codex: Setup manages MCP registration using the native Codex CLI against a private staged copy of its TOML configuration (~/.codex/config.toml), validating changes and verifying native removal hashes before publishing. Custom CODEX_HOME locations are rejected before changes.
  • Goose: Setup installs the shared skill only. The persistent MCP apply adapter remains unfinished; documented persistent setup is interactive goose configure or editing Goose YAML settings. Use session-scoped extensions instead (detailed below).
  • Aider: Aider integrates via the CLI subprocess path (ecc run); it has no native MCP adapter. Do not create synthetic MCP registrations for it.

ecc permissions

# Review the entries for each client
./bin/ecc setup --permissions --agents claude,codex,agy

# Apply only the permission component
./bin/ecc setup --permissions --agents claude,codex,agy --apply

The grant covers only member commands (ls, send, inbox, read, wait, whoami, hold, holds, release, task, tasks, campaign, campaigns, log, stats, watch, version, worker) and echo's MCP tools. setup, config, login, switch, cert, revoke, run, mcp, hook and every other admin command keep prompting. Each rule names an installed ecc by absolute path: the one deploy/local install puts in ~/.local/share/echo/local/bin, and ~/.local/bin/ecc. A path is granted only if the file and every directory up to / are owned by you or root and writable by nobody else, and neither it nor its target sits in a git worktree, the current directory or an agent workspace (agy trustedWorkspaces, Claude additionalDirectories). A development build is never granted; run deploy/local install first. Claude gets Bash(/path/ecc send *)-style entries and mcp__echo__* in ~/.claude/settings.json; agy gets command(/path/ecc send) entries (agy's rule grammar is undocumented) and mcp(echo/*) in ~/.gemini/antigravity-cli/settings.json; Codex gets prefix_rule(pattern=["/path/ecc","send"]) lines in ~/.codex/rules/echo-ecc.rules. Deny rules and managed policy still win.

The member list lives in one table beside the ecc command dispatch, and a test fails if a command is added without a level. Existing identical entries without an echo receipt are reported for manual review, not adopted; if you later add a copy of an entry setup wrote, removal takes out one copy and reports the duplicate.

Canonical coordination skill

Coordination skills teach agent models how to query the roster, place advisory file reservations before editing, lease tasks, and notify peers:

# Review skill installation targets
./bin/ecc setup --skills --agents codex,goose,claude,agy

# Install the canonical skill to standard locations
./bin/ecc setup --skills --agents codex,goose,claude,agy --apply

The skill payload (SKILL.md) is embedded in the binary and deployed to standard global paths:

• Codex and Goose: Share ~/.agents/skills/echo-coordination/SKILL.md. Removing the skill for either client removes the shared file for both.
• Claude Code: ~/.claude/skills/echo-coordination/SKILL.md
• Antigravity (agy): ~/.gemini/config/skills/echo-coordination/SKILL.md
• Aider: No native skill mechanism.

Custom skill-root caveats: Relocated Goose GOOSE_PATH_ROOT and custom Claude CLAUDE_CONFIG_DIR skill roots are currently rejected for manual review. Codex's shared skill path (~/.agents/skills/echo-coordination/SKILL.md) is independent of CODEX_HOME. Symlinked directories are followed only when they stay inside your home and are owned by you with no write access for others; anything else is refused.

Goose session-scoped extension workflow

Goose (tested on 1.52.0) supports session-scoped stdio extensions via --with-extension. This connects Goose to echo without rewriting or modifying your persistent YAML configuration. Run both commands through a system service already placed in the root-managed slice. Because Goose resolves the inner extension executable (ecc) via PATH, you must add the repository's bin/ directory to your PATH first:

# Add built binaries to PATH so Goose can launch ecc mcp
export PATH="$PWD/bin:$PATH"

# Interactive Goose session with echo MCP
./bin/ecc run --resource-aggregate-cgroup /echo.slice/echo-workers.slice --tool goose --session worker-goose goose session --with-extension 'echo:ecc mcp'

# Headless Goose task execution
./bin/ecc run --resource-aggregate-cgroup /echo.slice/echo-workers.slice --tool goose --session worker-goose goose run --with-extension 'echo:ecc mcp' --text 'Review task backlog'

Repeat --with-extension 'echo:ecc mcp' for each invocation. Note that the native diagnostic goose mcp-probe does not create disposable echo state automatically: it executes against the caller's active environment and creates Goose session metadata. In our qualification test, this diagnostic was run within an explicitly isolated disposable test directory (with private HOME and echo state) where it discovered the tools and resources of the 2026-09-25 build without a model call.

Integration lifecycle and qualification boundaries

Clear boundaries separate the integration stages:

1. Installation: Compiling or placing binaries on the host system. There is no released public installer.
2. Registration: Adding configuration entries, rule files, or skill markdown files.
3. Discovery: The client starting, reading configuration, launching ecc mcp, and listing tools.
4. Model invocation: The LLM choosing to invoke tools and following protocol instructions. Tests in disposable environments prove workflow mechanics, not universal model quality or zero errors.
5. Production connectivity: The local daemon connecting to the JetStream broker and exchanging messages across hosts.

Discovery does not prove model invocation, and isolated tool execution does not prove network mesh connectivity.

Aider and Goose runtime observations

Aider edits and Goose tool workflows have been exercised against Ollama in isolated workspaces. That does not prove every runtime has the same idle-wake behavior. Use the wrapper or MCP according to what the installed runtime supports.

Antigravity (agy) vs. Google Gemini CLI

echo.cc distinguishes Google DeepMind Antigravity CLI (agy) from the standalone Google Gemini developer CLI. Antigravity (agy) is an autonomous agent engine driven via bidirectional stream-json with native project permission grants (--project) and built-in tool loops. echo.cc has no driven adapter for the standalone Gemini CLI.

Model APIs are optional

Optional AI query commands can use configured model providers. They make network requests separately from filesystem-only coordination. A provider key, model access, quota and connectivity are required; using a coding-agent CLI subscription does not automatically grant API credentials.

API worker example

An API worker is echo calling a model provider itself to do one task. ecc peer work joins the net as a short-lived member, claims the task through echod like any agent, makes one bounded call, and ends its member when the call ends. It finishes the task only on an answer that passes the result-v1 schema and the acceptance check you name. Anything else (a refusal, a truncated answer, malformed JSON, a wrong answer, a timeout) is kept as a result and blocks the task with the reason.

$ ecc peer work --task 01M3NBSQWRC4S3JANR8S23WV40 --provider gemini \
    --model gemini-3.5-flash-lite --expect ECHO-OK
claimed 01M3NBSQWRC4S3JANR8S23WV40 as haywire.api.run-gchwfatb (fence 1)
completed 01M3NBSQWRC4S3JANR8S23WV40: result 01M3NBSQXDJ26QK441GCHWFATB sha256:381bc8d324a064e3af0751b046dfe7d3cf8083058c79c3f6e6605e1ef024f3e3

The task's evidence names that result by ID and digest. Before echod marks the task done, it reads the result file back, decodes it strictly and checks the digest, the task, the fence and the worker. ecc task done and the MCP echo_task_done tool write the same kind of result and go through the same check, and a done that names no result is refused. A driven ecc run --drive session also writes a result for each turn while it holds a task. A turn result records how the turn ended; it never finishes the task.

Ctrl-C during the call keeps a cancelled result and blocks the task. Running the same command again resumes it under the same run member and finishes it; both results stay. A run claims for its own timeout plus a minute, so a run that is killed outright frees the task soon after.

Measured on 2026-09-29 against a private test net whose echod was built from the same commit: Gemini reported 130 input and 18 output tokens and the call took under a second. What this does not show: that the answer is right beyond the --expect check. --accept-unchecked finishes on any schema-valid answer and the evidence says it was unchecked. Results stay on the host that wrote them and are not replicated yet. Image jobs and multi-provider consensus are not built.

Protocol documentation

Read the event contract, JSON Schema and CLI reference. CLI results, task state and dashboard snapshots are not interchangeable with wire envelopes. The published agent card is discovery metadata, not an implemented A2A task API.

SDKs and hosted APIs

There is no supported public hosted HTTP API or official language SDK yet. CLI subprocess and MCP integration come first. A hosted OpenAPI contract and generated clients should follow implemented, authenticated tenant routes and real consumer requirements.