feat(agents): namespace shorthand + manifest auto-load (#876)#877
Merged
Conversation
Harbor-style colon prefixes over the existing flat names (design #876; prior art: harbor's `--agent acp:<id>[@Version]`). The naming law: the native/ACP path owns bare names; every other path prefixes "<path>-". The shorthand is a deterministic candidate mapping onto those names — no new AgentConfig fields, no ambiguity machinery: acp:mimo -> mimo (bare) acp:pi -> pi-acp (suffix form) acp:claude -> claude-agent-acp (via the existing alias) omnigent:pi -> omnigent-pi (prefix form) ai-sdk:codex -> ai-sdk-codex (prefix form; candidates go through AGENT_ALIASES so renamed-with-alias packages keep resolving) Exact registered names and aliases always win (checked first), so "acpx:" runtime keys are unaffected; unknown namespaces fall through to the normal unknown-agent error. Phase 2 (#876) keys the registry-backed agent auto-fetch on these same namespaces. tests/agents/test_namespace_shorthand.py locks the mapping (9 tests); full tests/agents/ suite green.
Yiminnn
temporarily deployed
to
pypi-internal-preview
July 1, 2026 22:28 — with 
GitHub Actions
Inactive
GitHub Actions
Inactive
) When --agent <name> does not resolve locally, fetch the pinned agents source (default benchflow-ai/agents@main, cloned+cached via the same benchmark_repos machinery task sources use) and register every manifest.toml agent that collides with nothing local, then retry resolution (exact + alias + namespace shorthand). Why this is safe automatically, unlike installing agent packages: a manifest is PURE DATA — its install_cmd/launch_cmd strings execute inside the task sandbox, exactly the trust level of a task fetched with --source-repo (and of harbor's acp:<id> registry auto-fetch, which likewise fetches data and executes it sandboxed). No remote code ever runs in the host process. Host-side python adapters (omnigent's session-factory) stay explicit installs by design. Semantics: gap-fill only (local names/aliases always win; colliding aliases stripped, not fatal), one-shot per process, per-manifest guards (a broken manifest or unreachable source logs a warning and degrades to the normal unknown-agent error, which now also names the source consulted). BENCHFLOW_AGENTS_SOURCE=off disables; =owner/repo[@ref] re-pins; a local dir works for dev/tests. Live e2e: a fresh process resolving 'auggie' auto-registered 28 manifest agents from benchflow-ai/agents@main (cline, goose, qwen-code, stakpak, kilo, github-copilot-cli, ...) with zero installs. tests/agents/test_remote_manifest_autoload.py (6, network-free via local-dir source); full tests/agents/ suite green.
Yiminnn
changed the title
Yiminnn
temporarily deployed
to
pypi-internal-preview
July 1, 2026 22:52 — with
GitHub Actions
Inactive
GitHub Actions
Inactive
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements #876 (final design; harbor prior art): the namespace shorthand (Phase 1) and the manifest auto-load (Phase 2a — corrected design, see the issue update).
1. Namespace-shorthand specs —
<ns>:<id>Deterministic candidate mapping onto the existing flat names (naming law: native/ACP owns bare names; other paths use their
<path>-prefix):acp:mimo/acp:pi/acp:claudemimo/pi-acp/claude-agent-acpomnigent:piomnigent-piai-sdk:codexai-sdk-codex(alias-aware)No new
AgentConfigfields; exact names/aliases always win;acpx:keys unaffected.2. Miss-driven manifest auto-load — agents load like tasks
Unknown
--agent⇒ fetch the pinned agents source (defaultbenchflow-ai/agents@main, same clone+cache as--source-repo) ⇒ register every declarativemanifest.tomlagent that collides with nothing local ⇒ retry (exact + alias + shorthand).Why this is safe automatically (the key correction in #876): a manifest is pure data — its install/launch strings execute in the sandbox, the same trust level as task sources and as harbor's
acp:<id>registry fetch. No remote code runs on the host. Host-side python adapters (omnigent) stay explicit installs by design.BENCHFLOW_AGENTS_SOURCE=offdisables;=owner/repo[@ref]re-pins; local dir for dev/tests.Live e2e
A fresh process resolving
auggiefetched the repo once and auto-registered 28 manifest agents (cline, goose, qwen-code, stakpak, kilo, github-copilot-cli, …) — zero installs, zero env vars:Tests
15 new (9 shorthand + 6 auto-load, network-free via local-dir source); full
tests/agents/suite green (70 passed).Companion: benchflow-ai/agents#44 (naming law +
ai-sdk-pirename).