Documentation
¶
Overview ¶
Package handlers is the declarative registry of agent types ("handlers") that Dejima can run inside an island. It centralizes knowledge that was previously spread across three places: the launch command (image/start.sh's case block), the on-disk state dir (the daemon's agent-state mount target), and whether an agent exposes an attach surface (the session handler's headless guard).
Adding a first-class agent type becomes a registry entry here plus an install line in the image — not a Go change scattered across packages. Richer handler metadata (host-credential mounts, event-hook wiring, workspace templates) is captured informally in docs/agent-adapters.md and folded in over later phases.
Index ¶
Constants ¶
const Headless = "headless"
Headless is the reserved agent type whose command is user-supplied (AgentSpec.Cmd) rather than baked into the image.
const Shell = "shell"
Shell is a plain interactive terminal (a bash login shell) in the island — a scratch shell you type into, not an AI agent. Attachable; runs on /workspace.
Variables ¶
This section is empty.
Functions ¶
func Attachable ¶
Attachable reports whether an agent type exposes an attach surface. Unknown (custom) types are assumed interactive/attachable, matching the image, which runs them under tmux.
Types ¶
type Handler ¶
type Handler struct {
// ID matches Project/AgentSpec.Type and the image/agents/<id> shim dir.
ID string
// Kind drives attachability and how the supervisor launches the agent.
Kind Kind
// Launch is the command run inside the container. Empty for headless, whose
// command comes from the user (AgentSpec.Cmd).
Launch string
// StateDir is the home-dir state path persisted across restarts (e.g.
// ~/.claude). Informational now that the whole /home/dejima is persisted.
StateDir string
// RequiresProviderKey reports that this framework reaches an LLM over a
// provider API key (vs OAuth-seeded agents like claude-code/codex). It drives
// the provider/model picker, credential injection, and the proactive
// "missing-provider-auth" health state. The LLM-credential subsystem is
// opt-in per handler: false leaves an agent on its existing auth path.
RequiresProviderKey bool
// SupportedProviders is an advisory allow-list of provider ids this framework
// understands (empty = any), used to populate the picker — not enforced.
SupportedProviders []string
// SuggestedModels are example "provider/model" strings shown as picker hints.
// They are NOT applied as a default: the user must pick explicitly.
SuggestedModels []string
// GatewayPort is the in-container loopback port a channel framework serves a
// web UI / HTTP API on (0 = none). Used by `dejima agent open` to forward and
// open it. 0 means there is no localhost UI to open (e.g. a messaging-only
// gateway).
GatewayPort int
}
Handler is the declarative descriptor for one agent type.
func All ¶
func All() []Handler
All returns every registered handler, sorted by ID — for capability discovery (GET /v1/agent-types) and clients that populate a provider/model picker.
func Lookup ¶
Lookup returns the registered handler for an agent type. ok is false for unknown (custom) types; callers should treat those as generic interactive agents, matching the image's behavior.
func (Handler) Attachable ¶
Attachable reports whether clients can attach to this handler's agents.
func (Handler) NeedsProviderKey ¶
NeedsProviderKey reports whether this handler requires an LLM provider key.
Source Files