agents

package
v0.6.2 Latest Latest
Warning

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

 Go to latest Published: Sep 2, 2026 License: AGPL-3.0 Imports: 33 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
	Agent    dbq.Agent
	Blockers []dbq.SummarizeAgentBuildBlockingJobsRow
}

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 {
	JobID uuid.UUID
}

FireScheduleResult identifies the durable job created by a manual cron fire.

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, jobWake func(), logger *zap.Logger) *Service

func (*Service) CancelBuild 

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

CancelBuild durably requests cancellation of the agent's current build and best-effort signals it when this replica owns the in-memory worker.

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, and broadcasts the sibling change. Connector deletion triggers fence active transfers and detach their parent references so storage cleanup retains its durable job ownership chain.

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 creates an immediate durable job from a synced cron declaration.

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) GetBuildForAgent added in v0.5.0 

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

GetBuildForAgent returns an authoritative deployment snapshot and requires the build to belong to agentID.

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 typed-job cron declarations and occurrence state. 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.