handlers

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
• func Attachable(agentType string) bool
• type Handler
  • func All() []Handler
  • func Lookup(agentType string) (h Handler, ok bool)
  • func (h Handler) Attachable() bool
  • func (h Handler) LaunchFor(resume bool) string
  • func (h Handler) NeedsProviderKey() bool
• type Kind

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.

Functions

func Attachable

func Attachable(agentType string) bool

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
	// DashboardTokenCmd, when set, is a command run INSIDE the container that prints
	// the framework's gateway auth token to stdout. `dejima agent open` runs it over
	// the façade and appends DashboardTokenSuffix (with the token substituted) to the
	// tunnel URL, so the browser auto-authenticates instead of landing on a connect
	// form. This is the framework-specific knowledge kept DECLARATIVE (like Launch),
	// so core's agent-open stays generic. Empty = open the gateway root.
	DashboardTokenCmd string
	// DashboardTokenSuffix is appended to the console URL with the literal "{token}"
	// replaced by the (url-escaped) token — e.g. "#token={token}" (OpenClaw reads it
	// from the URL fragment) or "?token={token}". Only meaningful with
	// DashboardTokenCmd.
	DashboardTokenSuffix string
	// Bundled marks a TIER-1 agent preinstalled in the island image (claude-code,
	// codex): no first-use install wait. Tier-2 agents (Bundled=false) self-install
	// on first launch instead — see InstallCmd and the self-installing Launch line.
	Bundled bool
	// InstallCmd is the tier-2 install command (informational: surfaced in the
	// picker as "installs on first use"). The actual install happens inside the
	// self-installing Launch line, matching the existing goose/letta/hermes pattern.
	InstallCmd []string
	// ResumeLaunch is the Launch variant used for a GRACEFUL, operator-initiated
	// restart (e.g. applying a new secret): it continues the agent's previous
	// conversation instead of a cold start. Empty means the framework has no
	// resume affordance, so a restart falls back to a normal (fresh) Launch.
	ResumeLaunch string
}

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

func Lookup(agentType string) (h Handler, ok bool)

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

func (h Handler) Attachable() bool

Attachable reports whether clients can attach to this handler's agents.

func (Handler) LaunchFor

func (h Handler) LaunchFor(resume bool) string

LaunchFor returns the command to run for this handler, honoring resume when the handler supports it. Falls back to the normal Launch otherwise.

func (Handler) NeedsProviderKey

func (h Handler) NeedsProviderKey() bool

NeedsProviderKey reports whether this handler requires an LLM provider key.

type Kind

type Kind string

Kind distinguishes how an agent runs inside an island.

const (
	// KindInteractive agents own a tmux session and are attachable.
	KindInteractive Kind = "interactive"
	// KindHeadless agents run as a supervised process with no attach surface.
	KindHeadless Kind = "headless"
)