agents

package
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 25, 2026 License: AGPL-3.0 Imports: 31 Imported by: 0

Documentation

Overview

Package agents owns the agent-lifecycle business logic: create, configure, build/upgrade/rollback, start/stop/suspend, list/get detail, and the per-agent git-remote bindings.

Index

Constants

View Source 
const (
	GitModeReadWrite  = "read_write"
	GitModeReadOnly   = "read_only"
	GitModeImportOnce = "import_once"
)

Variables

View Source 
var (
	ErrSourcePreconditionRequired = errors.New("source precondition required")
	ErrSourceStateMismatch        = errors.New("source state mismatch")
)

Functions

This section is empty.

Types

type BridgeStopper 

type BridgeStopper interface {
	TeardownBridge(id uuid.UUID)
	RemoveBridge(id uuid.UUID)
}

BridgeStopper is the subset of *trigger.BridgeManager Delete uses.

type BuildWithTarget 

type BuildWithTarget struct {
	Build  dbq.AgentBuild
	Target *dbq.AgentBuild
}

GetBuild fetches one agent_build row plus the rollback-target row (for source_ref denormalization) if the build is a rollback. The second value is nil when the build isn't a rollback or the target row can't be loaded.

type CloneRequest 

type CloneRequest struct {
	Name string
	Slug string
}

CloneRequest is the input to Clone.

type ConnectGitRequest 

type ConnectGitRequest struct {
	RemoteURL     string
	CredentialID  string
	DefaultBranch string
	Mode          string
}

ConnectGitRequest is the input to ConnectGit.

type CreateRequest 

type CreateRequest struct {
	Name             string
	Slug             string
	Description      string
	BuildModel       string
	BuildProviderID  string
	ExecModel        string
	ExecProviderID   string
	Instructions     string
	GitRemoteURL     string
	GitCredentialID  string
	GitDefaultBranch string
	GitMode          string
	SkipInitialBuild bool
	// SystemConversationID, when set (system-agent create_agent path),
	// routes the build-completion outcome back to that conversation.
	SystemConversationID string
}

CreateRequest is the input to Create — mirrors CreateAgentRequest but in plain Go.

type Detail 

type Detail struct {
	Agent       dbq.Agent                              `json:"agent"`
	Running     bool                                   `json:"running"`
	IsOwner     bool                                   `json:"is_owner"`
	YourAccess  agentsdk.Access                        `json:"your_access"`
	Connections []dbq.ListConnectionNeedsByAgentRow    `json:"connections"`
	Webhooks    []dbq.ListWebhooksByAgentWithStatusRow `json:"webhooks"`
	Schedules   []dbq.ListSchedulesWithNextFireRow     `json:"schedules"`
	Routes      []dbq.AgentRoute                       `json:"routes"`
}

Detail is the Get response payload — the agent plus the per-agent resource lists the agent-detail page renders. YourAccess mirrors ListItem.YourAccess so callers don't need a second lookup.

type FireScheduleResult 

type FireScheduleResult struct {
	OccurrenceID uuid.UUID
}

FireScheduleResult identifies the durable manual cron occurrence.

type GitConfig 

type GitConfig struct {
	RemoteURL      string
	CredentialID   string // empty when not connected
	CredentialName string
	DefaultBranch  string
	WebhookSecret  string
	LastSyncedRef  string
	Mode           string
}

GitConfig is the read-side view of the agent's external git binding.

type ListItem 

type ListItem struct {
	Agent      dbq.Agent       `json:"agent"`
	Running    bool            `json:"running"`
	YourAccess agentsdk.Access `json:"your_access"`
	// OwnerName is the agent owner principal's display name (user display name
	// or group name); IsOwner is true when the caller owns the agent (the owner
	// principal is in the caller's grantee set).
	OwnerName string `json:"owner_name"`
	IsOwner   bool   `json:"is_owner"`
}

ListItem is one row from List plus the live container-running flag and the caller's effective access on this agent.

YourAccess is "admin" / "user" / "public" (see agentsdk.Access), resolved from agent_grants at list time. It exists so any caller — web UI, A2A, the in-airlock system agent — can decide locally which per-agent actions to offer without re-authorizing each one.

type RollbackRequest 

type RollbackRequest struct {
	BuildID        string
	ConversationID string
	// SystemConversationID is set when the rollback was triggered from a
	// system-agent conversation. Mutually exclusive with ConversationID; the
	// builder routes the post-build notification to whichever is set.
	SystemConversationID string
}

RollbackRequest is the input to Rollback.

type Service 

type Service struct {
	// contains filtered or unexported fields
}

func New 

func New(d *db.DB, build *builder.BuildService, dispatcher *trigger.Dispatcher, containers container.ContainerManager, bridgeMgr BridgeStopper, secretStore secrets.Store, logger *zap.Logger) *Service

func (*Service) CancelBuild 

func (s *Service) CancelBuild(ctx context.Context, p authz.Principal, agentID uuid.UUID) error

CancelBuild cancels the agent's in-progress build. Requires agent-admin.

func (*Service) Clone 

func (s *Service) Clone(ctx context.Context, p authz.Principal, sourceID uuid.UUID, req CloneRequest) (dbq.Agent, error)

Clone forks sourceID's code into a new agent owned by the caller. It copies the git repo (committed code) plus authored config — description, model-slot choices (providers are tenant-wide), emoji, protocol flags — and NOTHING else: no DB data, no S3 objects, no secrets, no resource bindings. The clone builds fresh (new schema, empty storage) and its first-boot Sync repopulates every code-derived declaration. Requires manager tenant role AND membership (AccessUser) of the source agent.

func (*Service) ConnectGit 

func (s *Service) ConnectGit(ctx context.Context, p authz.Principal, agentID uuid.UUID, req ConnectGitRequest) (GitConfig, error)

ConnectGit binds an external HTTPS git remote to the agent. Stores the URL, credential FK, default branch, and a freshly-generated HMAC secret for the webhook ingress.

func (*Service) Create 

func (s *Service) Create(ctx context.Context, p authz.Principal, req CreateRequest) (dbq.Agent, error)

Create creates an agent row (status=draft), records explicit per-agent model overrides if provided, auto-adds the creator as agent-admin, and kicks off the async build pipeline. Returns the freshly-inserted row; the build runs in a background goroutine and reports state via agent_builds + the runtime WebSocket.

func (*Service) Delete 

func (s *Service) Delete(ctx context.Context, p authz.Principal, agentID uuid.UUID) error

Delete cancels in-flight builds, stops bridge pollers, stops the container, removes the image, drops the per-agent schema/role, removes the local repo, deletes the row (CASCADE handles the rest), and broadcasts the sibling change.

func (*Service) DisconnectGit 

func (s *Service) DisconnectGit(ctx context.Context, p authz.Principal, agentID uuid.UUID) error

DisconnectGit resets the agent to internal-only mode. Local repo + image untouched.

func (*Service) DownloadSource 

func (s *Service) DownloadSource(ctx context.Context, p authz.Principal, agentID uuid.UUID, w io.Writer) (string, error)

DownloadSource writes the canonical source archive and returns its state.

func (*Service) FireSchedule 

func (s *Service) FireSchedule(ctx context.Context, p authz.Principal, agentID uuid.UUID, slug string) (FireScheduleResult, error)

FireSchedule queues a durable manual occurrence of a cron handler. Runtime one-shot handlers require caller-owned domain data and cannot be fired here.

func (*Service) Get 

func (s *Service) Get(ctx context.Context, p authz.Principal, agentID uuid.UUID) (Detail, error)

Get returns the member-readable agent detail. Agent-admin collections are included only when the caller satisfies their corresponding policy action.

func (*Service) GetBuild 

func (s *Service) GetBuild(ctx context.Context, p authz.Principal, buildID uuid.UUID) (BuildWithTarget, error)

func (*Service) GetGitConfig 

func (s *Service) GetGitConfig(ctx context.Context, p authz.Principal, agentID uuid.UUID) (GitConfig, error)

GetGitConfig returns the current git binding (zero-valued fields when not connected). Agent member gate.

func (*Service) List 

func (s *Service) List(ctx context.Context, p authz.Principal) ([]ListItem, error)

List returns the agents the caller can access — grant-joined (own + member + group-shared), annotated with the live container-running flag. Tenant admins do NOT see every agent here: the main page is the caller's working set. The all-agents governance surface is ListAll.

func (*Service) ListAll 

func (s *Service) ListAll(ctx context.Context, p authz.Principal) ([]ListItem, error)

ListAll returns every agent in the tenant — the admin governance surface behind Settings. Agents the caller isn't a member of come back with YourAccess=public and IsOwner=false, so the UI can offer Claim. Admin-only.

func (*Service) ListBuilds 

func (s *Service) ListBuilds(ctx context.Context, p authz.Principal, agentID uuid.UUID) ([]dbq.ListAgentBuildsByAgentRow, error)

ListBuilds returns the agent's build history (latest 50). Requires agent membership (AccessUser).

func (*Service) ListSchedules 

func (s *Service) ListSchedules(ctx context.Context, p authz.Principal, agentID uuid.UUID) ([]dbq.ListSchedulesWithNextFireRow, error)

ListSchedules returns the agent's schedule handlers (crons + schedules) with each one's next pending fire time. Requires agent-admin (config is owner-only).

func (*Service) ListTools 

func (s *Service) ListTools(ctx context.Context, p authz.Principal, agentID uuid.UUID) ([]dbq.AgentTool, error)

ListTools returns the agent's registered tool catalog. Requires agent membership (AccessUser).

func (*Service) ListWebhooks 

func (s *Service) ListWebhooks(ctx context.Context, p authz.Principal, agentID uuid.UUID) ([]dbq.ListWebhooksByAgentWithStatusRow, error)

ListWebhooks returns webhook rows with last-received status. Requires agent-admin (webhook config is owner-only).

func (*Service) Rollback 

func (s *Service) Rollback(ctx context.Context, p authz.Principal, agentID uuid.UUID, req RollbackRequest) error

Rollback reverses the agent to a previous completed build's source_ref. Same admin gate and async 202 shape as Upgrade.

func (*Service) SourceState 

func (s *Service) SourceState(ctx context.Context, p authz.Principal, agentID uuid.UUID) (string, error)

SourceState returns the canonical content state of the agent's internal HEAD.

func (*Service) Start 

func (s *Service) Start(ctx context.Context, p authz.Principal, agentID uuid.UUID) error

Start resumes a stopped agent and ensures its container is up. Requires an existing image.

func (*Service) Stop 

func (s *Service) Stop(ctx context.Context, p authz.Principal, agentID uuid.UUID) error

Stop kills the container and flips status to stopped (no auto-resume).

func (*Service) Suspend 

func (s *Service) Suspend(ctx context.Context, p authz.Principal, agentID uuid.UUID) error

Suspend kills the container but leaves status=active for auto-resume.

func (*Service) TransferOwnership 

func (s *Service) TransferOwnership(ctx context.Context, p authz.Principal, agentID, newOwnerID uuid.UUID) (dbq.Agent, error)

TransferOwnership hands the agent to newOwnerID. Moves the owner column AND the admin grant together, removes the old owner, and unbinds every owner-scoped binding — connection/MCP/exec bindings, the git credential, and bridges — because the new owner has no access to the old owner's resources. The need rows and agent code stay; only the bindings clear. Caller must be the current owner or a tenant admin. Env-var values (agent-scoped) and model slots (tenant-wide providers) are kept.

func (*Service) Update 

func (s *Service) Update(ctx context.Context, p authz.Principal, agentID uuid.UUID, req UpdateRequest) (dbq.Agent, error)

Update applies a partial update; each nil field on the request keeps the existing value. Name/slug changes trigger an async sibling refresh fan-out.

func (*Service) Upgrade 

func (s *Service) Upgrade(ctx context.Context, p authz.Principal, agentID uuid.UUID, req UpgradeRequest) error

Upgrade kicks off the upgrade pipeline. Admin-gated. Async — returns once the upgrade goroutine is queued; the runtime tracks state via agent_builds + WebSocket events.

func (*Service) UploadSource 

func (s *Service) UploadSource(ctx context.Context, p authz.Principal, agentID uuid.UUID, archive io.Reader, expectedState, rawCommitMessage string, force bool) (string, error)

UploadSource replaces an agent's internal source tree with a gzipped tar archive and starts a build from that committed source. expectedState is the state last observed by the caller; force explicitly bypasses that check.

type UpdateRequest 

type UpdateRequest struct {
	Name    *string
	Slug    *string
	AutoFix *bool
}

UpdateRequest mirrors UpdateAgentRequest. Pointer fields express "unset → keep existing".

type UpgradeRequest 

type UpgradeRequest struct {
	RunID       string
	Description string
	// SystemConversationID is set when the upgrade was triggered from a
	// system-agent conversation (sysagent tool). The builder routes the
	// post-build notification to that conversation instead of an agent
	// conversation. Mutually exclusive with the ConversationID path
	// agents take via /api/agent/upgrade.
	SystemConversationID string
}

UpgradeRequest is the input to Upgrade. RunID is optional; if set we load full error context from that run so the upgrade goes via the auto-fix path.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.