feat(agents): AgentDispatchPort domain interface

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

charles/claude-hooks#514

claude-desktop commented

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

Collaborator

User story

As a flow-graph or webhook author, I want a single domain port to dispatch agent work, so that I can request an agent without knowing about Docker, the Claude SDK, or MCP server wiring.

Acceptance criteria

Port shape

New file apps/server/src/domain/ports/agent-dispatch-port.ts exports AgentDispatchPort interface
Methods (minimum):
- dispatch(req: AgentDispatchRequest): Promise<AgentDispatchHandle>
- steer(taskId: string, message: string): Promise<void>
- kill(taskId: string, reason?: string): Promise<void>
- status(taskId: string): Promise<AgentDispatchStatus | null>
AgentDispatchRequest carries: agentType, repo (forge+owner+name), issueOrPr, prompt, forgeToken?, resumeSessionKey?, metadata
AgentDispatchHandle carries: taskId, worker, containerId?, sessionKey
No SDK types (SDKMessage, Options) in the port file
No Docker types (DockerExecArgs, container names) in the port file

Tests

Type-only tests: import the port, build a fake adapter, assert call shapes compile
No runtime tests yet — concrete impl is in a later issue

Out of scope

Concrete implementation (DefaultAgentDispatch) — separate issue
Adapter wiring for ContainerLifecyclePort / McpRegistryPort — separate issues
Migrating callsites — separate issue

References

Tracking: [Meta] Hexagonal: AgentDispatchPort migration
domain/ports/forge-port.ts is the analogue precedent
domain/agent/claude-port.ts shape we are wrapping

## User story As a flow-graph or webhook author, I want a single domain port to dispatch agent work, so that I can request an agent without knowing about Docker, the Claude SDK, or MCP server wiring. ## Acceptance criteria ### Port shape - [ ] New file `apps/server/src/domain/ports/agent-dispatch-port.ts` exports `AgentDispatchPort` interface - [ ] Methods (minimum): - [ ] `dispatch(req: AgentDispatchRequest): Promise<AgentDispatchHandle>` - [ ] `steer(taskId: string, message: string): Promise<void>` - [ ] `kill(taskId: string, reason?: string): Promise<void>` - [ ] `status(taskId: string): Promise<AgentDispatchStatus | null>` - [ ] `AgentDispatchRequest` carries: `agentType`, `repo` (forge+owner+name), `issueOrPr`, `prompt`, `forgeToken?`, `resumeSessionKey?`, `metadata` - [ ] `AgentDispatchHandle` carries: `taskId`, `worker`, `containerId?`, `sessionKey` - [ ] No SDK types (`SDKMessage`, `Options`) in the port file - [ ] No Docker types (`DockerExecArgs`, container names) in the port file ### Tests - [ ] Type-only tests: import the port, build a fake adapter, assert call shapes compile - [ ] No runtime tests yet — concrete impl is in a later issue ## Out of scope - Concrete implementation (`DefaultAgentDispatch`) — separate issue - Adapter wiring for ContainerLifecyclePort / McpRegistryPort — separate issues - Migrating callsites — separate issue ## References - Tracking: `[Meta] Hexagonal: AgentDispatchPort migration` - `domain/ports/forge-port.ts` is the analogue precedent - `domain/agent/claude-port.ts` shape we are wrapping

claude-desktop added the

labels

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

claude-desktop referenced this issue

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

[Meta] Hexagonal: AgentDispatchPort migration #513

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

2026-04-28 09:27:00 +00:00

code-lead was assigned by claude-desktop

2026-04-28 10:00:21 +00:00

code-lead was unassigned by claude-desktop

2026-04-28 10:01:34 +00:00