agentdef

type Agent struct {
	ID           string `json:"id"`
	UserID       string `json:"user_id"`
	SpaceID      string `json:"space_id,omitempty"`
	Name         string `json:"name"`
	Description  string `json:"description"`
	Instructions string `json:"instructions"`
	// Model names the catalog model this agent's background runs call, by the
	// operator-facing model name the LLM gateway lists. Empty means the
	// deployment default. It takes effect only on the managed (buildmax)
	// worker transport; a direct-transport worker reads the model from its
	// own server.yaml and ignores this field.
	Model string `json:"model,omitempty"`
	// Plugins names the catalog plugins this agent loads for a background run.
	// Nothing is inherited from the space's activations: an agent that names
	// none loads none. See docs/design/plugin-space-distribution.md §5.3.
	Plugins []string `json:"plugins,omitempty"`
	// SandboxNetworkTier and SandboxFilesystemTier declare this agent's
	// worker sandbox needs. Nothing is inherited from a space default: an
	// agent that sets neither gets the strictest tier on both axes, the same
	// way an agent that names no Plugins loads none. See
	// docs/design/agent-sandbox-policy.md §4.2.
	SandboxNetworkTier    string `json:"sandbox_network_tier,omitempty"`
	SandboxFilesystemTier string `json:"sandbox_filesystem_tier,omitempty"`
	// SecretConsumption declares which Space Secrets this agent consumes and
	// how. It versions with the definition, so an old revision still answers
	// what a run of it received. See docs/design/space-secrets.md §6.
	SecretConsumption SecretConsumption `json:"secret_consumption,omitempty"`
	// Revision numbers the agent_revision row holding this content. It starts
	// at 1 and advances every time the definition changes.
	Revision int `json:"revision"`
	// DeletedAt is set when the agent was deleted. The row stays because work
	// that already refers to it — a task's agent, a step run's target, a
	// revision's subject — would otherwise point at nothing. A deleted agent is
	// invisible to every path that would start new work with it.
	DeletedAt *time.Time `json:"deleted_at,omitempty"`
	CreatedAt time.Time  `json:"created_at"`
}

type CreateInput struct {
	SpaceID string
	UserID  string
	Def     Definition
}

type Definition struct {
	Name         string
	Description  string
	Instructions string
	// Model is the catalog model name this agent's runs call, validated against
	// the deployment's model catalog before a write is accepted when a catalog
	// is available. Empty means the deployment default. See Agent.Model.
	Model string
	// Plugins names catalog plugins, never releases. The version and digest
	// come from the space's activation, so moving a plugin to a new release
	// stays one edit in one place.
	Plugins []string
	// SandboxNetworkTier and SandboxFilesystemTier are validated against
	// config.ValidSandboxNetworkTier / ValidSandboxFilesystemTier before a
	// write is accepted. See Agent.SandboxNetworkTier.
	SandboxNetworkTier    string
	SandboxFilesystemTier string
	// SecretConsumption is validated against the space's live Secrets before a
	// write is accepted. See docs/design/space-secrets.md §6.
	SecretConsumption SecretConsumption
}

type Revision struct {
	AgentID      string `json:"agent_id"`
	Revision     int    `json:"revision"`
	Name         string `json:"name"`
	Description  string `json:"description"`
	Instructions string `json:"instructions"`
	// Model is the model this revision recorded, versioned with the rest of the
	// definition. See Agent.Model.
	Model string `json:"model,omitempty"`
	// Plugins is the selection this revision recorded. It versions with the
	// rest of the definition, so an old revision still answers what that agent
	// named.
	Plugins []string `json:"plugins,omitempty"`
	// SandboxNetworkTier and SandboxFilesystemTier are the tiers this
	// revision recorded. See Agent.SandboxNetworkTier.
	SandboxNetworkTier    string `json:"sandbox_network_tier,omitempty"`
	SandboxFilesystemTier string `json:"sandbox_filesystem_tier,omitempty"`
	// SecretConsumption is the Secret consumption this revision recorded.
	SecretConsumption SecretConsumption `json:"secret_consumption,omitempty"`
	// CreatedBy is the user who wrote this revision, which is not necessarily
	// the agent's owner.
	CreatedBy string    `json:"created_by"`
	CreatedAt time.Time `json:"created_at"`
}

type SecretConsumption struct {
	Env []SecretEnvGrant `json:"env,omitempty"`
}

type SecretEnvGrant struct {
	// Secret is the public id of a Secret in the Agent's own Space.
	Secret string `json:"secret"`
	// Item names one item of the group; empty means the whole group.
	Item string `json:"item,omitempty"`
	// EnvName is the variable name for a selected item. Unused for a whole
	// group, which uses each item's own name.
	EnvName string `json:"env_name,omitempty"`
	// Prefix is prepended to each item name when the whole group is taken.
	Prefix string `json:"prefix,omitempty"`
	// Optional makes a missing grant a skip rather than a run failure.
	Optional bool `json:"optional,omitempty"`
}

type Store interface {
	ListAgentsByUser(ctx context.Context, userID string) ([]Agent, error)
	ListAgentsBySpace(ctx context.Context, spaceID string) ([]Agent, error)
	// GetAgent returns a live agent. A deleted one reads as not found, so no
	// caller can start new work with it by forgetting to check.
	GetAgent(ctx context.Context, agentID string) (*Agent, error)
	// GetAgentIncludingDeleted resolves an agent a record already refers to,
	// deleted or not. Use it to finish or describe work that named the agent
	// before it was deleted, never to start work with it.
	GetAgentIncludingDeleted(ctx context.Context, agentID string) (*Agent, error)
	CreateAgentInSpace(ctx context.Context, in CreateInput) (*Agent, error)
	UpdateAgentInSpace(ctx context.Context, in UpdateInput) (*Agent, error)
	// DeleteAgent and DeleteAgentInSpace mark the agent deleted rather than
	// removing the row. Deleting an agent a published workflow still names is
	// refused above this layer; see the delete handler.
	// Both return ErrNotFound when there is no such live agent for that owner.
	DeleteAgent(ctx context.Context, agentID, userID string) error
	DeleteAgentInSpace(ctx context.Context, agentID, spaceID string) error
	// ListAgentRevisions returns an agent's revisions, newest first, with the
	// total count.
	ListAgentRevisions(ctx context.Context, agentID string, limit, offset int) ([]Revision, int, error)
	// GetAgentRevision returns one revision, or nil when the agent has no such
	// revision number.
	GetAgentRevision(ctx context.Context, agentID string, revision int) (*Revision, error)
}

type UpdateInput struct {
	AgentID string
	SpaceID string
	// UpdatedBy is taken because a space agent is edited by whoever holds the
	// permission, not only by its owner, and a revision that cannot name its
	// author is not much of a record.
	UpdatedBy string
	Def       Definition
}