HOL Registry Broker Codex Plugin

	Codex plugin for HOL Registry Broker. This repository adds a Codex-facing MCP server and skill that let Codex ask the broker whether to delegate, inspect candidates, summon a selected agent, and recover the broker session later. For the broader public Registry Broker skill and CLI, use hashgraph-online/registry-broker-skills and @hol-org/registry.

Canonical HOL plugin profile: hol.org/registry/plugins/hol%2Fregistry-broker-codex-plugin

Overview

This repository exposes four user-facing broker tools inside Codex:

• registryBroker.delegate: Ask the broker whether the task should be delegated, reviewed as a shortlist, or handled locally.
• registryBroker.findAgents: Inspect the shortlist of candidates recommended by the broker.
• registryBroker.summonAgent: Send a subtask to a broker-selected agent or a known UAID, or preview the exact dispatch with dryRun.
• registryBroker.sessionHistory: Recover the broker conversation for a previous session with a concise latest-state summary.

The broker returns one of three recommendation states:

• delegate-now
• review-shortlist
• handle-locally

Codex can use that recommendation to decide whether to delegate immediately, show candidates first, or keep the work local.

When to use this plugin

Use this plugin when a Codex task can benefit from a broker-selected outside specialist, for example:

• bug fixing and verification
• implementation review
• research and competitive analysis
• business planning or GTM work
• landing page, onboarding, or UX exploration
• launch messaging and lifecycle copy

If you only need the public Registry Broker skill or CLI outside Codex, use:

• hashgraph-online/registry-broker-skills
• @hol-org/registry

Install

Requirements:

• Node >=20
• pnpm >=10

From the repository root:

pnpm install
pnpm run build

The packaged MCP server entrypoint is:

{
  "mcpServers": {
    "registryBroker": {
      "command": "node",
      "args": ["./dist/cli.cjs", "up", "--transport", "stdio"]
    }
  }
}

The public HOL Registry Broker API base URL is https://hol.org/registry/api/v1.

Configure

Supported public configuration:

• REGISTRY_BROKER_API_KEY Optional. Enables authenticated broker chat flows when your broker deployment requires an API key.
• MCP_SERVER_NAME Optional. Overrides the MCP server display name.
• REGISTRY_BROKER_PLUGIN_LOG_LEVEL Optional. Defaults to info.

Use in Codex

Start with a task-shaped prompt. Codex can call registryBroker.delegate first, then decide whether to shortlist or summon.

For higher-stakes delegation, you can also pass a structured brief:

• deliverable
• constraints
• mustInclude
• acceptanceCriteria

Example prompts:

• Delegate this bug investigation and return a fix plan.
• Find broker candidates for this TypeScript verification task.
• Dry-run the broker handoff for this patch review before sending it.
• Write a business plan and GTM outline for this product.
• Design a landing page and onboarding direction for this feature.
• Research the market and compare the strongest alternatives.

Typical flow:

1. Codex calls registryBroker.delegate.
2. The broker returns delegate-now, review-shortlist, or handle-locally.
3. Codex either calls registryBroker.summonAgent, shows registryBroker.findAgents, or keeps working locally.
4. If a delegation happened, Codex can recover the broker conversation with registryBroker.sessionHistory.

The plugin now returns explicit next-action payloads so Codex can move directly from delegation planning to shortlist review, dispatch preview, live summon, and session recovery.

Verify

Repository checks:

pnpm run lint
pnpm run typecheck
pnpm test
pnpm run build

GitHub Actions also runs the HOL Codex Plugin Scanner action on every push and pull request, uploads SARIF into GitHub code scanning, and enforces a minimum scanner score plus severity gate for this plugin.

Broker-backed smoke test:

If your broker requires an API key, set REGISTRY_BROKER_API_KEY in your shell before running the command.

REGISTRY_BROKER_E2E_DISCOVERY_QUERY="<search phrase that should return your target candidate>" \
REGISTRY_BROKER_E2E_DISCOVERY_EXPECT_UAID="<uaid:aid:discoverable-agent>" \
REGISTRY_BROKER_E2E_UAID="<uaid:aid:target-agent>" \
REGISTRY_BROKER_E2E_MESSAGE="<your probe message>" \
REGISTRY_BROKER_E2E_EXPECT="<expected response substring>" \
pnpm run e2e:broker

Optional query-driven summon verification:

REGISTRY_BROKER_E2E_QUERY_SUMMON_QUERY="<query that should resolve to a chatable agent>" \
REGISTRY_BROKER_E2E_QUERY_SUMMON_EXPECT_UAID="<uaid:aid:query-selected-agent>" \
REGISTRY_BROKER_E2E_QUERY_SUMMON_EXPECT="<expected delegated response substring>" \
pnpm run e2e:broker

The smoke harness supports:

• local broker verification when you provide a known-working target
• HOL-hosted recommendation-consumption verification against https://hol.org/registry/api/v1
• dry-run summon verification with structured delegation briefs
• session-history summaries for follow-up work

Repository layout

• src/mcp.ts: MCP tool definitions and orchestration
• src/brief.ts: structured delegation brief rendering
• src/delegation.ts: planner selection, fallback search, and summon helpers
• src/planner.ts: planner selection and shortlist formatting helpers
• src/broker.ts: broker client adapter
• src/config.ts: runtime configuration
• src/tool-contracts.ts: shared MCP schemas
• src/tool-results.ts: next-action and session-history summaries
• scripts/e2e-local-broker.ts: broker-backed smoke test
• skills/registry-broker-orchestrator/SKILL.md: Codex usage guidance

Contributing

Please read our Contributing Guide and Code of Conduct before contributing.

For bugs and feature requests, use the issue tracker.

Security

For security issues, see SECURITY.md.

Maintainers

See MAINTAINERS.md.

License

Apache-2.0