Documentation
¶
Overview ¶
Package builder implements the AI app builder: agent sandboxes (containers built from per-profile Dockerfiles) driven over the Agent Client Protocol, with sessions and full activity persisted in the metadata database
Index ¶
- Constants
- func AgentTypeFromName(name string) (string, error)
- func AgentTypes() []string
- func EmbeddedDockerfile(agentType string) ([]byte, error)
- func RemoveStateVolume(ctx context.Context, cli, sessionId string) error
- func StopOrphanSandboxes(ctx context.Context, cli string) error
- func SweepOrphanStateVolumes(ctx context.Context, cli string, sessionExists func(id string) bool) error
- type Event
- type Manager
- func (m *Manager) CancelTurn(id string) error
- func (m *Manager) CreateSession(ctx context.Context, ...) (*types.BuilderSession, error)
- func (m *Manager) DeleteSession(ctx context.Context, id, userID string) error
- func (m *Manager) Enabled() bool
- func (m *Manager) GetSession(ctx context.Context, id string) (*types.BuilderSession, error)
- func (m *Manager) ListActivity(ctx context.Context, sessionId, afterId string, limit int) ([]*types.BuilderActivity, error)
- func (m *Manager) ListFiles(ctx context.Context, id string) ([]string, error)
- func (m *Manager) ListSessions(ctx context.Context, userID string) ([]*types.BuilderSession, error)
- func (m *Manager) LiveState(id string) (isLive, turnActive bool, partial string)
- func (m *Manager) LogActivity(sessionId, userID, kind, content string, metadata map[string]any)
- func (m *Manager) ReadFile(ctx context.Context, id, relPath string) (string, error)
- func (m *Manager) ResumeSession(ctx context.Context, id, userID string) error
- func (m *Manager) SendMessage(ctx context.Context, id, userID, text string) error
- func (m *Manager) Start(ctx context.Context) error
- func (m *Manager) Stop()
- func (m *Manager) StopSession(id, userID string) error
- func (m *Manager) Subscribe(id string) (<-chan Event, func(), error)
- func (m *Manager) UpdateSessionInfo(ctx context.Context, session *types.BuilderSession) error
- func (m *Manager) ValidateConfig() error
- func (m *Manager) VerifyProfile(ctx context.Context, name string, testPrompt bool) error
Constants ¶
const ( SpecKindContainer = "container" SpecKindStarlark = "starlark" )
Spec kinds, decided by the spec scaffold (Containerfile present or not)
const ( // SandboxLabelFilter selects agent containers in docker/podman ps // (used by the console containers view). "Agent" is the term for the // app builder's AI containers everywhere in code and APIs; "builder" // alone refers to the feature (and kaniko image builds elsewhere) SandboxLabelFilter = sandboxLabel + "=1" // SandboxSessionLabel carries the owning builder session id SandboxSessionLabel = sandboxSessionLabel )
const AgentTypeCustom = "custom"
Variables ¶
This section is empty.
Functions ¶
func AgentTypeFromName ¶
AgentTypeFromName infers the agent type from the [builder_agent.*] entry name, like auth entries: the part before the first underscore must be a predefined type or "custom" (opencode, opencode_dev, pi, custom_myagent)
func AgentTypes ¶
func AgentTypes() []string
AgentTypes lists the predefined agent types with embedded Dockerfiles
func EmbeddedDockerfile ¶
EmbeddedDockerfile returns the embedded Dockerfile content for a predefined agent type
func RemoveStateVolume ¶ added in v0.18.7
RemoveStateVolume deletes a session's agent state volume (session delete). Best effort: a missing volume is fine
func StopOrphanSandboxes ¶
StopOrphanSandboxes removes any builder sandbox containers left over from a previous server run (matched by label)
Types ¶
type Event ¶
type Event struct {
SessionId string `json:"session_id"`
Kind string `json:"kind"` // agent_chunk|thought_chunk|tool_call|tool_call_update|turn_started|turn_done|status|error
Text string `json:"text,omitempty"`
ToolCallId string `json:"tool_call_id,omitempty"`
Title string `json:"title,omitempty"`
ToolKind string `json:"tool_kind,omitempty"`
ToolStatus string `json:"tool_status,omitempty"`
StopReason string `json:"stop_reason,omitempty"`
Status string `json:"status,omitempty"`
}
Event is one builder session event relayed to console SSE viewers
type Manager ¶
type Manager struct {
*types.Logger
// OnTurnDone is called (on its own goroutine) after each completed
// prompt turn; the server uses it to create/refresh the preview app
OnTurnDone func(sessionId string)
// contains filtered or unexported fields
}
Manager owns builder sessions: sandbox lifecycle, the ACP driver and the activity log. Preview app creation and publishing live in the server package; the OnTurnDone hook lets the server react to completed turns
func NewManager ¶
func (*Manager) CancelTurn ¶
CancelTurn sends the ACP cancel notification for the in-flight turn
func (*Manager) CreateSession ¶
func (m *Manager) CreateSession(ctx context.Context, userID, name, prompt, spec, specKind, profileChoice, editApp string, services []string, seed func(*types.BuilderSession) error) (*types.BuilderSession, error)
CreateSession creates the session row and workspace, then launches the sandbox and sends the composed first prompt asynchronously. The returned session is in starting state; progress streams over session events. profileChoice names a [builder_profile.*] entry chosen by the user; empty resolves the implicit default (no profiles) or the only configured one. The resolved profile decides the agent config, git target and publish restrictions and is stored on the session. editApp marks a session editing an existing published app: the caller (server) validates the app. seed populates the workspace (spec scaffold or the edited app's source) and may set session fields (EditVersion, PublishPath); it runs to completion BEFORE the agent launches, so the first prompt never races an empty or half-copied workspace. A seed failure aborts the create with nothing left behind
func (*Manager) DeleteSession ¶
DeleteSession stops the sandbox and removes the workspace and session row. Activity rows are retained; the caller (server) removes the preview app
func (*Manager) GetSession ¶
GetSession returns one session row
func (*Manager) ListActivity ¶
func (m *Manager) ListActivity(ctx context.Context, sessionId, afterId string, limit int) ([]*types.BuilderActivity, error)
ListActivity returns activity rows for a session
func (*Manager) ListFiles ¶
ListFiles returns the workspace file tree (relative paths), skipping VCS and dependency directories
func (*Manager) ListSessions ¶
ListSessions returns session rows, optionally filtered by user
func (*Manager) LiveState ¶
LiveState returns the in-flight turn state for a session: whether a turn is running and the partial agent message accumulated so far
func (*Manager) LogActivity ¶
LogActivity writes one activity row on behalf of the server (preview and publish events)
func (*Manager) ResumeSession ¶
ResumeSession relaunches the sandbox for a detached session. The agent conversation starts fresh over the same sources; the transcript history stays in the activity log
func (*Manager) SendMessage ¶
SendMessage starts a prompt turn with the user's message
func (*Manager) Start ¶
Start reconciles orphan sandboxes from a previous run, marks their sessions detached and starts the idle reaper
func (*Manager) StopSession ¶
StopSession stops the sandbox; the workspace and preview app remain
func (*Manager) UpdateSessionInfo ¶
UpdateSessionInfo persists caller changes (preview/publish path, status)
func (*Manager) ValidateConfig ¶
ValidateConfig checks the app_builder and builder_agent config. Called at startup when enabled; also the first part of the verify checklist
func (*Manager) VerifyProfile ¶
VerifyProfile runs the sandbox checks for one agent profile: profile and config_files validation, secret resolution, image build and the ACP handshake in a throwaway container. With testPrompt, one real prompt round-trips through the model ("reply with OK") to prove credentials work
Source Files