[Meta] Hexagonal: AgentDispatchPort migration #513

New issue

Open

opened 2026-04-28 09:24:03 +00:00 by claude-desktop · 0 comments

claude-desktop commented

2026-04-28 09:24:03 +00:00

Collaborator

Tracking

Lift the agentic stack (agent-runner + container lifecycle + MCP wiring) behind a single domain port — AgentDispatchPort — mirroring the maturity already reached by ForgePort (Phase 2).

After this milestone, flow-runner / foreman / webhook handlers never see SDK messages, container IDs, or MCP server specs — only dispatch(type, request) → { taskId, worker }.

Why now

Forge layer fully hexagonalised. Agentic layer is the remaining gap. Audit findings (2026-04-28):

ClaudeAgentPort exists but agent-runner.ts:715–780 still calls SDK direct
SDKMessage import leak at agent-runner.ts:24, PR-extract regex at :679
Host-mode vs container-mode branch at agent-runner.ts:543–548
mcp-config.ts dual-mounts forgejo-mcp + forge-mcp without a port
Session key <type>:<repo>:<issue> does not bind forge → cross-forge collision risk
foreman.ts builds SDK options directly

Scope

#	Issue	Order
#514	AgentDispatchPort domain interface (types-only)	1
#515	ContainerLifecyclePort + DockerContainerLifecycle adapter	2
#516	McpRegistryPort + DefaultMcpRegistry adapter	2
#517	Finish ClaudeAgentPort migration — kill SDK leaks	3
#518	DefaultAgentDispatch orchestrator	4
#519	Migrate flows / foreman / webhook callsites	5
#520	Bind forge into session key	independent
#521	Per-call token override in dispatch	independent

Out of scope

ComfyUI-style graph editor changes (M21)
Forge layer changes — already complete
New agent types or instances

References

docs/agents-architecture.md
docs/foreman.md
docs/containers.md
Audit summary 2026-04-28 (this conversation)

## Tracking Lift the agentic stack (agent-runner + container lifecycle + MCP wiring) behind a single domain port — `AgentDispatchPort` — mirroring the maturity already reached by `ForgePort` (Phase 2). After this milestone, flow-runner / foreman / webhook handlers never see SDK messages, container IDs, or MCP server specs — only `dispatch(type, request) → { taskId, worker }`. ## Why now Forge layer fully hexagonalised. Agentic layer is the remaining gap. Audit findings (2026-04-28): - `ClaudeAgentPort` exists but `agent-runner.ts:715–780` still calls SDK direct - `SDKMessage` import leak at `agent-runner.ts:24`, PR-extract regex at `:679` - Host-mode vs container-mode branch at `agent-runner.ts:543–548` - `mcp-config.ts` dual-mounts forgejo-mcp + forge-mcp without a port - Session key `<type>:<repo>:<issue>` does not bind forge → cross-forge collision risk - `foreman.ts` builds SDK options directly ## Scope | # | Issue | Order | |---|-------|-------| | #514 | AgentDispatchPort domain interface (types-only) | 1 | | #515 | ContainerLifecyclePort + DockerContainerLifecycle adapter | 2 | | #516 | McpRegistryPort + DefaultMcpRegistry adapter | 2 | | #517 | Finish ClaudeAgentPort migration — kill SDK leaks | 3 | | #518 | DefaultAgentDispatch orchestrator | 4 | | #519 | Migrate flows / foreman / webhook callsites | 5 | | #520 | Bind forge into session key | independent | | #521 | Per-call token override in dispatch | independent | ## Out of scope - ComfyUI-style graph editor changes (M21) - Forge layer changes — already complete - New agent types or instances ## References - `docs/agents-architecture.md` - `docs/foreman.md` - `docs/containers.md` - Audit summary 2026-04-28 (this conversation)

claude-desktop added the

area:meta

type:meta

labels

2026-04-28 09:25:32 +00:00

claude-desktop added this to the M25 — Agentic dispatch port milestone

2026-04-28 09:26:59 +00:00