agentinstance

package
v0.5.4 Latest Latest
Warning

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

Go to latest
Published: Nov 7, 2026 License: MIT Imports: 28 Imported by: 0

Documentation

Index

Constants

View Source
const LocalOperator = "local-operator"

LocalOperator identifies the single authenticated human authority of the local daemon.

View Source
const ReportKindProposal = "proposal"
View Source
const SkillReviewPending = "pending"

Variables

View Source
var (
	ErrWorkspaceAccessDenied = errors.New("workspace_access_denied")
	ErrSessionNotRoot        = errors.New("session_not_root")
	ErrPaused                = errors.New("agent_instance_paused")
	ErrLimit                 = errors.New("agent_instance_limit")
	ErrExists                = errors.New("agent_instance_exists")
	ErrStarting              = errors.New("agent_instance_starting")
	ErrForbidden             = errors.New("agent_instance_forbidden")
	ErrDepth                 = errors.New("agent_instance_depth")
	ErrNotAlwaysOn           = errors.New("agent_not_always_on")
	ErrDefinitionMissing     = errors.New("agent_definition_missing")
	ErrNotFound              = errors.New("agent_instance_not_found")
	ErrScopeMismatch         = errors.New("session_scope_mismatch")
)
View Source
var (
	ErrSkillReviewLimit = errors.New("skill_review_limit")
	ErrSkillReviewStale = errors.New("skill_review_stale")
	// ErrSkillReviewInvalid means the reviewed digest still matches but the draft cannot be installed:
	// its bytes, name or file paths fail verification. Only rejection can settle such a review.
	ErrSkillReviewInvalid      = errors.New("skill_review_invalid")
	ErrSkillReviewNotFound     = errors.New("skill_review_not_found")
	ErrSkillReviewOperatorOnly = errors.New("skill_review_operator_only")
)
View Source
var ErrRotationChanged = errors.New("agentinstance: rotation state changed")
View Source
var ErrSkillProposeUnverified = errors.New("skill_propose_unverified")
View Source
var ErrSkillReviewNoTarget = errors.New("skill_review_no_target")

Functions

func ErrorMessage

func ErrorMessage(err error, activeLimit int) string

ErrorMessage describes a domain failure without changing its stable code.

func OperatorOnlyResume

func OperatorOnlyResume(reason string) bool

OperatorOnlyResume keeps safety and unknown pauses under operator control.

func WriteSkillDraft

func WriteSkillDraft(root string, scanRoots []string, draft SkillDraft) (path, digest string, err error)

Types

type Activity

type Activity struct {
	ReportsByDay  []ActivityDay  `json:"reports_by_day"`
	CostByProject []ActivityCost `json:"cost_by_project"`
	BusyByHour    []ActivityHour `json:"busy_by_hour"`
}

type ActivityCost

type ActivityCost struct {
	WorkspaceID string  `json:"workspace_id"`
	Scope       string  `json:"scope"`
	USDEstimate float64 `json:"usd_estimate"`
	Tokens      int64   `json:"tokens"`
}

type ActivityDay

type ActivityDay struct {
	Day       string `json:"day"`
	Quiet     int    `json:"quiet"`
	Told      int    `json:"told"`
	NeededYou int    `json:"needed_you"`
}

type ActivityHour

type ActivityHour struct {
	Weekday int `json:"weekday"`
	Hour    int `json:"hour"`
	Events  int `json:"events"`
}

type ActivityQuery

type ActivityQuery struct {
	ProfileID    string
	AgentName    string
	WorkspaceIDs []string
	Since        time.Time
}

type ActivityReader

type ActivityReader interface {
	ReadActivity(context.Context, ActivityQuery) (Activity, error)
	ReadActivities(context.Context, []ActivityQuery) ([]Activity, error)
}

type Admission

type Admission interface {
	ResolveCreate(context.Context, CreateRequest) (Instance, error)
	ValidateResume(context.Context, Instance) error
	ResolveAdopt(context.Context, AdoptRequest) (Instance, error)
}

Admission resolves authenticated lineage, definition and intersected permissions at the daemon boundary.

type AdoptRequest

type AdoptRequest struct {
	CreateRequest
	SessionID string
}

type Authority

type Authority struct{ Callers CallerReader }

func (Authority) Authorize

func (a Authority) Authorize(
	ctx context.Context,
	actor workspaceaccess.ActorRef,
	instance Instance,
	verb string,
) error

func (Authority) AuthorizeMemory

func (a Authority) AuthorizeMemory(ctx context.Context, sessionID, agentName, profileID string) error

AuthorizeMemory requires a daemon-resolved instance lineage for the named agent.

type Caller

type Caller struct {
	SessionID, AgentName, ProfileID, InstanceID string
	InstanceDepth                               int
	PermissionPolicy                            store.SessionPermissionPolicy
	Grant                                       string
}

type CallerReader

type CallerReader interface {
	InstanceCaller(context.Context, string) (Caller, error)
}

type CheckIn

type CheckIn struct {
	ID        string
	Result    string
	Detail    string
	Reason    string
	CreatedAt time.Time
}

type CheckInReader

type CheckInReader interface {
	CountQuietCheckIns(context.Context, string, *time.Time) (int64, error)
	ListCheckIns(context.Context, string, string, int) ([]CheckIn, error)
}

type CreateRequest

type CreateRequest struct {
	Agent, Workspace, Profile string
	Actor                     workspaceaccess.ActorRef
}

type Instance

type Instance struct {
	ID                string
	ProfileID         string
	AgentName         string
	WorkspaceID       string
	State             string
	PauseReason       string
	MainSessionID     string
	GrantCeiling      string
	PermissionCeiling string
	ChecksEnabled     bool
	Depth             int
	CreatedByKind     string
	CreatedByID       string
	CreatedAt         time.Time
	UpdatedAt         time.Time
	ArchivedAt        *time.Time
}

type LifecycleHooks

type LifecycleHooks interface {
	DispatchAgentInstance(context.Context, hooks.AgentInstancePayload) (hooks.AgentInstancePayload, error)
}

type ListQuery

type ListQuery struct {
	ProfileID, WorkspaceID, AfterID string
	AgentName, State                string
	AllWorkspaces                   bool
	// AllProfiles reads the owner-labeled aggregate; ProfileID is then empty.
	AllProfiles bool
	Limit       int
}

type MainSessionRotator

type MainSessionRotator interface {
	Eligible(context.Context, Instance) (RotationDecision, error)
	Rotate(context.Context, Instance, RotationDecision) error
	Cleanup(context.Context, Instance) error
}

type MainSessionStarter

type MainSessionStarter interface {
	Start(context.Context, StartMainSession) (string, error)
	Stop(context.Context, string) error
}

type Metrics

type Metrics struct {
	PauseCounts    map[string]int64 `json:"pause_counts"`
	HeldInputCount int64            `json:"held_input_count"`
}

Metrics counts live paused instances and held inputs within one profile and workspace.

type Occurrence

type Occurrence struct {
	State, Result, Reason, ReportID string
}

type Option

type Option func(*Service)

func WithActiveLimit

func WithActiveLimit(limit int) Option

func WithAdmission

func WithAdmission(admission Admission) Option

func WithClock

func WithClock(now func() time.Time) Option

func WithInstanceChanged

func WithInstanceChanged(changed func(Instance)) Option

func WithLifecycleHooks

func WithLifecycleHooks(dispatcher LifecycleHooks) Option

func WithMainSessionRotator

func WithMainSessionRotator(rotator MainSessionRotator) Option

func WithMainSessions

func WithMainSessions(starter MainSessionStarter) Option

func WithStateEffects

func WithStateEffects(effects func(context.Context, Instance) error) Option

WithStateEffects reconciles durable pause/resume obligations through their owning services.

func WithStore

func WithStore(store InstanceStore) Option

type PauseResult

type PauseResult struct {
	Instance
	Changed bool
}

type ReconciliationSessions

type ReconciliationSessions interface {
	StartOutcome(context.Context, Instance) (StartOutcome, error)
	DiscardFailedStart(context.Context, Instance, string) error
}

type Report

type Report struct {
	ID         string
	InstanceID string
	ReportInput
	State             string
	PromptAdmissionID string
	EventSessionID    string
	EventSeq          int64
	CreatedAt         time.Time
	DeliveredAt       *time.Time
}

type ReportEventWriter

type ReportEventWriter interface {
	Publish(context.Context, string, Report) (int64, error)
}

Publish must durably deduplicate by (sessionID, Report.ID), including after restart.

type ReportInput

type ReportInput struct {
	SourceKey   string
	Kind        string
	Payload     jsontext.Value
	Fingerprint string
}

func (ReportInput) Validate

func (r ReportInput) Validate() error

type ReportPublication

type ReportPublication struct {
	Report        Report
	MainSessionID string
}

type ReportPublisher

type ReportPublisher struct {
	Store     ReportStore
	Writer    ReportEventWriter
	BatchSize int
}

func (ReportPublisher) Sweep

func (p ReportPublisher) Sweep(ctx context.Context) error

type ReportQuery

type ReportQuery struct {
	State          string
	InstanceID     string
	AfterCreatedAt time.Time
	AfterID        string
	Limit          int
}

type ReportStore

type ReportStore interface {
	AppendReport(context.Context, string, ReportInput) (Report, error)
	ListReports(context.Context, ReportQuery) ([]Report, error)
	UnpublishedReports(context.Context, string, int) ([]ReportPublication, error)
	MarkReportPublished(context.Context, string, string, int64) error
}

type RotationDecision

type RotationDecision struct {
	Publication RotationPublication
	Eligible    bool
}

type RotationPublication

type RotationPublication struct {
	InstanceID     string
	PredecessorID  string
	SuccessorID    string
	AdmissionCount int64
}

type SeenStore

type SeenStore interface {
	LastSeen(context.Context, string, string) (*time.Time, error)
	MarkSeen(context.Context, string, string, time.Time) (time.Time, error)
}

type Service

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

func NewService

func NewService(options ...Option) (*Service, error)

func (*Service) Adopt

func (s *Service) Adopt(ctx context.Context, req AdoptRequest) (Instance, error)

func (*Service) AfterPause

func (s *Service) AfterPause(ctx context.Context, trip store.InstancePauseTrip) error

func (*Service) ApplyPause

func (s *Service) ApplyPause(ctx context.Context, instance Instance) error

func (*Service) Archive

func (s *Service) Archive(ctx context.Context, id string) error

func (*Service) Create

func (s *Service) Create(ctx context.Context, req CreateRequest) (Instance, bool, error)

func (*Service) EnsureMain

func (s *Service) EnsureMain(ctx context.Context, id string) (Instance, error)

func (*Service) List

func (s *Service) List(ctx context.Context, q ListQuery) ([]Instance, error)

func (*Service) Pause

func (s *Service) Pause(ctx context.Context, id, reason string) (Instance, error)

Pause persists the winning pause reason before applying its runtime effects.

func (*Service) Reconcile

func (s *Service) Reconcile(ctx context.Context) error

func (*Service) Resume

func (s *Service) Resume(ctx context.Context, id string, actor workspaceaccess.ActorRef) (Instance, error)

type SkillAutomaticContents

type SkillAutomaticContents struct{ Hooks, MCPServers, Scripts int }

SkillAutomaticContents inventories declarations for review; it never executes them.

type SkillDraft

type SkillDraft struct {
	Name  string           `json:"name"`
	Files []SkillDraftFile `json:"files"`
}

func PrepareSkillDraft

func PrepareSkillDraft(name, description, body string, files []SkillDraftFile) (SkillDraft, error)

func ReadSkillDraft

func ReadSkillDraft(path, digest string) (SkillDraft, error)

func (SkillDraft) AutomaticContents

func (draft SkillDraft) AutomaticContents() (SkillAutomaticContents, error)

type SkillDraftFile

type SkillDraftFile struct {
	Path    string `json:"path"`
	Content string `json:"content"`
}

type SkillProposalInput

type SkillProposalInput struct {
	Name               string
	Description        string
	Body               string
	Files              []SkillDraftFile
	EvidenceSessionIDs []string
}

type SkillProposalService

type SkillProposalService struct {
	Store     SkillReviewStore
	Authority Authority
	DraftRoot string
	ScanRoots []string
}

func (*SkillProposalService) Approve

func (s *SkillProposalService) Approve(
	ctx context.Context,
	actor workspaceaccess.ActorRef,
	instance Instance,
	id, digest, operator, targetRoot string,
) (err error)

func (*SkillProposalService) Propose

func (s *SkillProposalService) Propose(
	ctx context.Context,
	actor workspaceaccess.ActorRef,
	instance Instance,
	targetRoot string,
	input SkillProposalInput,
) (SkillReview, error)

func (*SkillProposalService) Reject

func (s *SkillProposalService) Reject(
	ctx context.Context,
	actor workspaceaccess.ActorRef,
	instance Instance,
	id, digest, operator string,
) error

func (*SkillProposalService) Review

func (*SkillProposalService) Reviews

func (s *SkillProposalService) Reviews(
	ctx context.Context,
	actor workspaceaccess.ActorRef,
	instance Instance,
	query SkillReviewQuery,
) ([]SkillReview, error)

type SkillReview

type SkillReview struct {
	ID              string
	InstanceID      string
	ProfileID       string
	WorkspaceID     string
	AgentName       string
	SkillName       string
	Digest          string
	State           string
	DraftPath       string
	SourceSessionID string
	DecidedBy       string
	CreatedAt       time.Time
	DecidedAt       *time.Time
}

type SkillReviewQuery

type SkillReviewQuery struct {
	ProfileID      string
	WorkspaceID    string
	InstanceID     string
	State          string
	AfterCreatedAt time.Time
	AfterID        string
	Limit          int
}

type SkillReviewStore

type SkillReviewStore interface {
	CreateReview(context.Context, SkillReview, ReportInput) (SkillReview, error)
	GetReview(context.Context, string) (SkillReview, error)
	ListReviews(context.Context, SkillReviewQuery) ([]SkillReview, error)
	DecideReview(context.Context, string, string, string, string) error
}

type StartMainSession

type StartMainSession struct{ Instance Instance }

type StartOutcome

type StartOutcome struct {
	SessionID string
	State     string
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL