6.9 KiB
6.9 KiB
Host Utility Agentctl — Boot Probes, Capability API, Sessionless Utility Prompts
Date: 2026-04-08 Status: implemented PR: TBD Decision: ADR-0002
Problem
Utility agent calls (enhance-prompt, commit-message, etc.) required an active task session because lifecycle.Manager.ExecuteInferencePrompt looked up the session's agentctl via GetOrEnsureExecution and spawned a one-shot ACP subprocess inside it. Three features could not fit that mold:
- Boot-time probes. List models/modes/auth for each installed agent so the settings UI can render them and detect misconfiguration early.
- Settings refresh. User clicks "refresh" to re-check auth/models after installing or re-authing a CLI.
- Sessionless enhance-prompt. Enhance button in the new-task modal — no task or workspace exists yet.
Built-in utility prompts are self-contained (context is injected as template vars), so running them in a neutral tmp dir is semantically fine.
Design
Architecture
Backend boot
↓
waitForAgentctlControlHealthy
↓
HostUtilityManager.Start(ctx) [goroutine]
├─ mktemp kandev-host-utility-<pid>-*/
├─ filter registry → ACP-native inference agents
└─ errgroup (parallel):
for each agent type:
├─ IsInstalled? (skip → not_installed)
├─ ControlClient.CreateInstance(workdir=tmp/<type>)
├─ waitForClientHealthy
└─ Probe() → cache
Per-call path (both probe and sessionless prompt):
caller → HostUtilityManager.getInstance(type) [singleflight per agent type]
→ per-type warm Client (one-shot ACP subprocess)
→ agentctl utility.{Probe|Execute}
→ initialize → session/new → [set_mode?] → [prompt?] → kill
Packages and files
New
internal/agent/hostutility/—Manager,cache, public API (GetAll,Get,Refresh,ExecutePrompt), types (AgentCapabilities,Model,Mode,AuthMethod,PromptResult,Statusenum).internal/agent/capabilities/handlers/— HTTP routes (mounted under/api/v1/agent-capabilitiesrather than under/api/v1/agents/:id/...to avoid a Gin wildcard-name collision with the existing settings routes):GET /api/v1/agent-capabilitiesGET /api/v1/agent-capabilities/:typePOST /api/v1/agent-capabilities/:type/probePOST /api/v1/agent-capabilities/:type/prompt(raw one-off)
Extended
internal/agentctl/server/utility/types.go—ProbeRequest/ProbeResponse,Modefield onPromptRequest,ProbeAuthMethod/ProbeModel/ProbeMode/ProbePromptCapabilities.internal/agentctl/server/utility/acp_executor.go—Probe()method,executeACPSessionhonorsmodeviaconn.SetSessionMode. Parsing split intobuildInitProbeFields+applySessionProbeFieldshelpers.internal/agentctl/server/utility/handler.go—POST /api/v1/inference/proberoute.internal/agentctl/client/utility.go— factoreddoLongRunningJSONhelper shared byInferencePromptand newProbe.internal/utility/template/engine.go—ResolveWithOptions+ResolveOptions{MissingAsEmpty bool}.internal/utility/service/service.go—PreparePromptRequesttakes asessionless boolflag.internal/utility/controller/controller.go— threads the flag through.internal/utility/handlers/handlers.go—session_idoptional; sessionless branch callsHostUtilityExecutor.ExecutePrompt; newHostUtilityExecutorinterface.cmd/kandev/main.go— constructsHostUtilityManagerafterwaitForAgentctlControlHealthy, starts it in a goroutine, registersStop()cleanup viaaddCleanupwith a 10s timeout. Threaded throughbuildHTTPServer→routeParams.cmd/kandev/helpers.go—routeParams.hostUtilityMgr; registers both the new capabilities routes and the updated utility routes.
Config shapes (internal)
// ProbeConfig — implicit, built per-call by the manager from registry + workdir.
// No Model — probes must omit --model so session/new returns the agent default
// plus the full availableModels list.
//
// PromptConfig — uses the existing InferenceConfigDTO; Model is required,
// Mode is optional and when set triggers session/set_mode after session/new.
Caller responsibilities
| Param | Probe | Sessionless prompt | Task-scoped prompt |
|---|---|---|---|
| WorkDir | host tmp dir (manager-owned) | host tmp dir | task workspace (unchanged) |
| Model | omitted | required (utility record → user default → cached currentModelId) | from utility record / user default |
| Mode | unused | optional | optional |
Scope (v1)
- ACP-native agents only (
Runtime().Protocol == ProtocolACP): claude-acp, codex-acp, copilot-acp, amp-acp, opencode-acp, auggie. - Non-ACP protocols (streamjson/codex/copilot/amp/opencode adapters) excluded — later iteration.
- Cache is in-memory, populated at boot and on explicit
/proberefresh. No TTL. - Tmp dirs process-scoped (
kandev-host-utility-<pid>-*); cleanup only removes dirs owned by this process.
Implementation Notes
- Lazy instance recreation.
Manager.getInstancerecreates a warm instance if it's missing (never bootstrapped or crashed). No separate health loop. - Failure isolation. Per-agent bootstrap failures land in the cache as
Status = not_installed | auth_required | failed.isAuthErroris a coarse string-match heuristic on the ACP SDK error — the SDK doesn't expose a distinct auth error code. - Env inheritance. The agentctl instance is workspace-only and inherits the backend's env. The ephemeral ACP subprocess spawned by
Probe/Executealso inherits (nocmd.Envoverride inacp_executor.go), soANTHROPIC_API_KEY,OPENAI_API_KEY, etc. flow through naturally for v1. ExecutionStorebypass deferred. The original plan called for ahost-utility:ID prefix branch inmanager_execution.go. Once it became clear thatControlClient.CreateInstance+ a regularClientdoes everything we need without touching the lifecycle manager's execution store, that branch was removed from the plan — host utility sits alongside the lifecycle manager rather than through it.- Worktree access. Sessionless utility calls cannot read workspace files by design. All current built-ins are self-contained; a
requires_workspaceflag onUtilityAgentis the documented future escape hatch for custom templates that need file access. - Lint wrinkle.
acp_executor.gohas one//nolint:unconvertonstring(m.Id)wherem.Idisacp.AuthMethodId(a named string type). The linter flags it as unnecessary, but Go requires the explicit conversion. - Frontend wiring is explicitly deferred. Settings page, new-task modal enhance button, and startup capabilities fetch land in a follow-up PR. The API surface was designed to support all three.
Verification
make fmtcleango build ./...successmake testall packages greenmake lint0 issues