|
| 1 | +--- |
| 2 | +phase: implementation |
| 3 | +title: Implementation Guide |
| 4 | +description: Technical implementation notes, patterns, and code guidelines |
| 5 | +--- |
| 6 | + |
| 7 | +# Implementation Guide |
| 8 | + |
| 9 | +## Development Setup |
| 10 | + |
| 11 | +- Work in `.worktrees/feature-herdr-runtime-integration` on branch `feature-herdr-runtime-integration`. |
| 12 | +- Use the existing npm workspace commands and focused Vitest targets for `packages/cli` and `packages/agent-manager`. |
| 13 | +- Herdr command contracts must be confirmed before real integration code is finalized. Until then, inject a Herdr command runner so tests can use fake JSON responses. |
| 14 | + |
| 15 | +## Code Structure |
| 16 | + |
| 17 | +- `packages/cli/src/util/config.ts`: shared runtime provider validation. |
| 18 | +- `packages/cli/src/lib/GlobalConfig.ts`: runtime config owner and global provider lookup. |
| 19 | +- `packages/cli/src/lib/Config.ts`: global runtime provider delegation for caller compatibility. |
| 20 | +- `packages/cli/src/services/agent/agent.service.ts`: managed agent orchestration that consumes runtime contracts from `agent-manager`. |
| 21 | +- `packages/cli/src/commands/agent.ts`: command-level config reading, UI rendering, and runtime factory usage. |
| 22 | +- `packages/agent-manager/src/utils/AgentRegistry.ts`: runtime metadata persistence. |
| 23 | +- `packages/agent-manager/src/database/migrations/005_agent_runtime.sql`: additive registry migration. |
| 24 | +- `packages/agent-manager/src/terminal/TmuxManager.ts`: low-level tmux operations. |
| 25 | +- `packages/agent-manager/src/runtime/AgentRuntime.ts`: runtime interfaces, Herdr runtime factory, and Herdr registry-entry predicate. |
| 26 | +- `packages/agent-manager/src/runtime/HerdrAgentRuntime.ts`: injected Herdr CLI client used by the CLI and reusable by later console/channel code. |
| 27 | + |
| 28 | +## Implementation Notes |
| 29 | + |
| 30 | +### Core Features |
| 31 | + |
| 32 | +- Runtime config: |
| 33 | + - Parse only `agentRuntime.provider` from global `~/.ai-devkit/.ai-devkit.json`. |
| 34 | + - Ignore project-level `agentRuntime` in project install config. |
| 35 | + - Default to `tmux` for missing config, missing `agentRuntime`, or missing provider. |
| 36 | + - Reject unknown providers with valid values. |
| 37 | +- Registry migration: |
| 38 | + - Add `runtime` and `runtime_ref`. |
| 39 | + - Keep the physical `tmux_session` column only for legacy row backfill and old-reader compatibility. |
| 40 | + - Parse `runtime_ref` as opaque JSON for known providers. |
| 41 | + - Preserve old rows as tmux. |
| 42 | +- Runtime dispatch: |
| 43 | + - Start uses configured runtime. |
| 44 | + - Send/focus/kill use stored runtime on the target row. |
| 45 | + - Managed start/stop/focus/send orchestration lives in `agent-manager`; CLI passes the selected runtime provider and renders results. |
| 46 | + - Runtime contracts, factories, and runtime-entry predicates are exported from `agent-manager`; CLI does not define Herdr runtime interfaces or construct the Herdr adapter class directly. |
| 47 | + - Herdr references are captured from Herdr responses only. |
| 48 | +- Herdr availability: |
| 49 | + - For `provider = herdr`, require Herdr binary availability and backend/API reachability. |
| 50 | + - Treat `HERDR_ENV` and `HERDR_PANE_ID` as optional context signals. |
| 51 | +- Cleanup pass: |
| 52 | + - Removed an unused Herdr availability error reason. |
| 53 | + - Simplified Herdr runtime ref parsing to normalize each field once. |
| 54 | + - Trimmed duplicate runtime-provider tests from `ConfigManager`; `GlobalConfigManager` and config util tests own those behavior cases. |
| 55 | +- Refactor pass: |
| 56 | + - Moved runtime start/stop/focus/send orchestration from CLI agent service into `agent-manager`. |
| 57 | + - Moved corresponding start/stop/focus/send tests into agent-manager runtime tests. |
| 58 | + - Kept CLI responsible for option parsing, config lookup, UI messages, and send/wait output formatting. |
| 59 | + |
| 60 | +### Implemented Behavior |
| 61 | + |
| 62 | +- Global config accepts only `tmux` and `herdr`; missing config, missing `agentRuntime`, and missing provider resolve to `tmux`. |
| 63 | +- Project `.ai-devkit.json` does not configure runtime selection. |
| 64 | +- Existing registry rows without runtime columns are migrated/read as tmux-backed records. |
| 65 | +- Registry entries expose `runtime` and opaque JSON `runtimeRef`; tmux rows use `{ session: "<tmux-session>" }`. |
| 66 | +- Old SQLite rows with only `tmux_session` synthesize `{ session: tmux_session }` when read. |
| 67 | +- `agent start` reads global runtime config once for interactive mode and starts through tmux or Herdr accordingly. |
| 68 | +- `agent send`, `agent send --wait`, `agent open`, and `agent kill` use stored Herdr refs when the target registry row is Herdr-backed. |
| 69 | +- Runtime-aware start, stop, focus, and prompt delivery are centralized in `packages/agent-manager/src/runtime/ManagedAgentRuntime.ts`; `agent send --wait` reads AI DevKit session transcripts for both tmux and Herdr-backed agents. |
| 70 | +- `agent send --wait` waits through a short transcript-flush grace period before reporting that an agent returned to waiting without assistant output. |
| 71 | +- Durable mode is unchanged and remains separate from interactive runtime selection. |
| 72 | + |
| 73 | +### Patterns & Best Practices |
| 74 | + |
| 75 | +- Use `execFile` or injected argument-array command runners, not shell string execution. |
| 76 | +- Validate Herdr JSON response shape before storing refs. |
| 77 | +- Keep errors domain-specific enough for CLI messages and tests. |
| 78 | +- Do not leak Herdr's full session model into AI DevKit detail/list data structures. |
| 79 | +- Active call sites should consume `runtimeRef`; do not add new `tmuxSession` reads. |
| 80 | + |
| 81 | +## Integration Points |
| 82 | + |
| 83 | +- Herdr CLI/API: |
| 84 | + - availability: `herdr --version` or equivalent plus `herdr api snapshot` or equivalent. |
| 85 | + - start: command returns session, pane ID, agent name, and optional PID. |
| 86 | + - send: command targets a returned pane/session ref. |
| 87 | + - read/wait: command returns output/result where available; otherwise AI DevKit transcript polling remains the result source. |
| 88 | + - focus/open: command targets returned pane/session ref. |
| 89 | + - stop: command delegates lifecycle cleanup to Herdr where supported. |
| 90 | +- Agent adapters: |
| 91 | + - Continue parsing agent-specific session files and summaries. |
| 92 | + - Do not become Herdr-aware unless Herdr needs adapter-specific launch metadata. |
| 93 | + |
| 94 | +## Error Handling |
| 95 | + |
| 96 | +- Unknown runtime provider: fail before side effects. |
| 97 | +- Herdr binary missing: fail before start/send with clear installation/PATH guidance. |
| 98 | +- Herdr backend unreachable: fail before start/send with backend/API guidance. |
| 99 | +- Missing required Herdr IDs in response: fail and do not register the agent. |
| 100 | +- PID unavailable: handle explicitly; do not guess. |
| 101 | +- Stale runtime ref: fail target operation and suggest focusing/listing/restarting the agent. |
| 102 | +- Malformed registry runtime ref: treat as target-specific data corruption, not a global list crash. |
| 103 | + |
| 104 | +## Performance Considerations |
| 105 | + |
| 106 | +- CLI process startup overhead is acceptable for MVP. |
| 107 | +- Avoid repeated runtime config reads inside loops or per-target group sends. |
| 108 | +- Keep the runtime boundary transport-agnostic so Herdr socket/event support can replace CLI calls later. |
| 109 | + |
| 110 | +## Security Notes |
| 111 | + |
| 112 | +- Do not pass prompts through shell interpolation. |
| 113 | +- Do not store secrets in runtime refs or debug logs. |
| 114 | +- Treat Herdr response JSON as untrusted. |
| 115 | +- Preserve existing AI DevKit ownership over channel permissions, assignments, and validation evidence. |
| 116 | + |
| 117 | +## Validation Evidence |
| 118 | + |
| 119 | +- `packages/cli`: `npx vitest run src/__tests__/util/config.test.ts src/__tests__/lib/Config.test.ts src/__tests__/lib/GlobalConfig.test.ts src/__tests__/services/agent/agent.service.test.ts src/__tests__/commands/agent.test.ts` |
| 120 | +- `packages/cli`: `npx tsc --noEmit` |
| 121 | +- `packages/agent-manager`: `npx vitest run src/__tests__/utils/AgentRegistry.test.ts src/__tests__/runtime/AgentRuntime.test.ts src/__tests__/runtime/HerdrAgentRuntime.test.ts` |
| 122 | +- `packages/agent-manager`: `npm run typecheck` |
| 123 | +- `packages/agent-manager`: `npm run build` |
| 124 | +- repository: `npx ai-devkit@latest lint --feature herdr-runtime-integration` |
| 125 | +- repository: `git diff --check` |
| 126 | +- Refactor validation: |
| 127 | + - `packages/agent-manager`: `npx vitest run src/__tests__/runtime/ManagedAgentRuntime.test.ts src/__tests__/runtime/AgentRuntime.test.ts src/__tests__/runtime/HerdrAgentRuntime.test.ts` |
| 128 | + - `packages/agent-manager`: `npm run typecheck` |
| 129 | + - `packages/agent-manager`: `npm run lint` |
| 130 | + - `packages/agent-manager`: `npm run build` |
| 131 | + - `packages/cli`: `npx vitest run src/__tests__/services/agent/agent.service.test.ts src/__tests__/commands/agent.test.ts src/__tests__/services/plugin/plugin-loader.service.test.ts` |
| 132 | + - `packages/cli`: `npx tsc --noEmit` |
| 133 | + - `packages/cli`: `npm run lint` |
| 134 | + - repository: `npx ai-devkit@latest lint --feature herdr-runtime-integration` |
| 135 | + - repository: `git diff --check` |
0 commit comments