task

package
v0.0.4 Latest Latest
Warning

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

 Go to latest Published: May 27, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Overview

Package task defines the canonical task-domain models, interfaces, limits, and validation helpers shared by persistence, runtime, and transport layers.

Index

Constants

View Source 
const (
	// DefaultRunLeaseDuration is the conservative lease duration used when a caller omits one.
	DefaultRunLeaseDuration = 5 * time.Minute
	// MaxRunLeaseDuration is the MVP guardrail for a single task-run lease extension.
	MaxRunLeaseDuration = 24 * time.Hour
)
View Source 
const (
	// MaxMetadataBytes caps task metadata payloads at 16 KiB.
	MaxMetadataBytes = 16 * 1024
	// MaxPayloadBytes caps persisted event-style JSON payloads at 64 KiB.
	MaxPayloadBytes = 64 * 1024
	// MaxResultBytes caps persisted run results at 64 KiB.
	MaxResultBytes = 64 * 1024
	// DefaultTaskMaxAttempts is the canonical retry budget used when callers omit an explicit value.
	DefaultTaskMaxAttempts = 3
	// MaxTaskMaxAttempts caps task-level attempt policy at ten tries.
	MaxTaskMaxAttempts = 10
	// MaxHierarchyDepth caps parent/child nesting at eight levels.
	MaxHierarchyDepth = 8
	// MaxDependencyCount caps dependency edges per task at thirty-two.
	MaxDependencyCount = 32
	// MaxDirectChildren caps direct child tasks per parent at sixty-four.
	MaxDirectChildren = 64
)
View Source 
const (
	// TaskFieldCreatedBy identifies the immutable creator identity field.
	TaskFieldCreatedBy = "created_by"
	// TaskFieldOrigin identifies the immutable technical ingress field.
	TaskFieldOrigin = "origin"
	// TaskFieldScope identifies the immutable task scope field.
	TaskFieldScope = "scope"
	// TaskFieldWorkspaceID identifies the immutable workspace binding field.
	TaskFieldWorkspaceID = "workspace_id"
	// TaskFieldParentTaskID identifies the immutable parent-task linkage field.
	TaskFieldParentTaskID = "parent_task_id"
	// TaskFieldTitle identifies the mutable task title field.
	TaskFieldTitle = "title"
	// TaskFieldDescription identifies the mutable task description field.
	TaskFieldDescription = "description"
	// TaskFieldPriority identifies the mutable task priority field.
	TaskFieldPriority = "priority"
	// TaskFieldMaxAttempts identifies the mutable task attempt-policy field.
	TaskFieldMaxAttempts = "max_attempts"
	// TaskFieldApprovalPolicy identifies the mutable approval-policy field.
	TaskFieldApprovalPolicy = "approval_policy"
	// TaskFieldMetadata identifies the mutable task metadata field.
	TaskFieldMetadata = "metadata"
	// TaskFieldNetworkChannel identifies the mutable network channel field.
	TaskFieldNetworkChannel = "network_channel"
	// TaskFieldOwner identifies the mutable ownership field.
	TaskFieldOwner = "owner"
)
View Source 
const (
	// CoordinatorModeInherit uses daemon/workspace coordinator defaults.
	CoordinatorModeInherit CoordinatorMode = "inherit"
	// CoordinatorModeGuided injects task-specific guidance into the existing coordinator.
	CoordinatorModeGuided CoordinatorMode = "guided"

	// WorkerModeInherit uses normal task/run and workspace worker defaults.
	WorkerModeInherit WorkerMode = "inherit"
	// WorkerModeSelect narrows worker selection using the task profile.
	WorkerModeSelect WorkerMode = "select"

	// SandboxModeInherit uses workspace/global sandbox defaults.
	SandboxModeInherit SandboxMode = "inherit"
	// SandboxModeNone disables task-level sandbox selection when config permits it.
	SandboxModeNone SandboxMode = "none"
	// SandboxModeRef selects one named sandbox reference at session start.
	SandboxModeRef SandboxMode = "ref"
)
View Source 
const (
	// FailureKindOperatorForced identifies an operator-authored forced terminal failure.
	FailureKindOperatorForced = "operator_forced"
	// MaxForceRunBulkIDs bounds per-request bulk recovery work.
	MaxForceRunBulkIDs = 50
	// MaxRetryRunChainDepth bounds linear retry lineage to prevent accidental retry loops.
	MaxRetryRunChainDepth = 10
	// DefaultForceRunRateLimitPerMinute bounds force operations by actor and task.
	DefaultForceRunRateLimitPerMinute = 10
)

Variables

View Source 
var (
	// ErrTaskNotFound reports that no persisted task matched the lookup.
	ErrTaskNotFound = errors.New("task: task not found")
	// ErrTaskRunNotFound reports that no persisted task run matched the lookup.
	ErrTaskRunNotFound = errors.New("task: task run not found")
	// ErrTaskRunIdempotencyNotFound reports that no persisted task-run idempotency record matched the lookup.
	ErrTaskRunIdempotencyNotFound = errors.New("task: task run idempotency not found")
	// ErrTaskDependencyNotFound reports that no persisted dependency edge matched the lookup.
	ErrTaskDependencyNotFound = errors.New("task: task dependency not found")
	// ErrTaskEventNotFound reports that no persisted task event matched the lookup.
	ErrTaskEventNotFound = errors.New("task: task event not found")
	// ErrTaskTriageStateNotFound reports that no persisted triage state matched the lookup.
	ErrTaskTriageStateNotFound = errors.New("task: task triage state not found")
	// ErrExecutionProfileNotFound reports that no persisted task execution profile matched the lookup.
	ErrExecutionProfileNotFound = errors.New("task: task execution profile not found")
	// ErrRunReviewNotFound reports that no persisted task-run review matched the lookup.
	ErrRunReviewNotFound = errors.New("task: task run review not found")
	// ErrValidation reports that a task-domain payload or state failed validation.
	ErrValidation = errors.New("task: validation failed")
	// ErrImmutableField reports that a caller attempted to change an immutable task field.
	ErrImmutableField = errors.New("task: immutable field")
	// ErrInvalidScopeBinding reports that a scope and workspace binding combination is invalid.
	ErrInvalidScopeBinding = errors.New("task: invalid scope binding")
	// ErrPayloadTooLarge reports that a JSON payload exceeded the task-domain size guardrails.
	ErrPayloadTooLarge = errors.New("task: payload too large")
	// ErrGraphLimitExceeded reports that a task hierarchy or dependency operation exceeded a bounded limit.
	ErrGraphLimitExceeded = errors.New("task: graph limit exceeded")
	// ErrCycleDetected reports that a dependency insert would introduce a cycle.
	ErrCycleDetected = errors.New("task: dependency cycle detected")
	// ErrInvalidStatusTransition reports that a task or run lifecycle transition is not allowed.
	ErrInvalidStatusTransition = errors.New("task: invalid status transition")
	// ErrConflict reports that an idempotent write conflicts with previously persisted state.
	ErrConflict = errors.New("task: conflict")
	// ErrSessionAlreadyBound reports that a run already owns a session binding.
	ErrSessionAlreadyBound = errors.New("task: session already bound")
	// ErrSessionAttachNotAllowed reports that a run cannot attach an existing session in its current state.
	ErrSessionAttachNotAllowed = errors.New("task: session attach not allowed")
	// ErrStaleNetworkChannel reports that a stored task or run channel no longer passes the active validator.
	ErrStaleNetworkChannel = errors.New("task: stale network channel")
	// ErrPermissionDenied reports that the resolved actor context lacks authority for the requested task action.
	ErrPermissionDenied = errors.New("task: permission denied")
	// ErrNoClaimableRun reports that no task run matched claim criteria.
	ErrNoClaimableRun = errors.New("task: no claimable run")
	// ErrInvalidClaimToken reports that a lease mutation did not prove ownership with the current token.
	ErrInvalidClaimToken = errors.New("task: invalid claim token")
	// ErrLeaseExpired reports that a lease mutation targeted an expired ownership lease.
	ErrLeaseExpired = errors.New("task: lease expired")
	// ErrActiveRunLease reports that a session already owns an active task-run lease.
	ErrActiveRunLease = errors.New("task: active run lease exists")
	// ErrForbiddenOperatorAction reports that config or policy forbids a force operation for the actor.
	ErrForbiddenOperatorAction = errors.New("task: forbidden operator action")
	// ErrForceOpRequiresReason reports that a force operation requires a non-empty reason.
	ErrForceOpRequiresReason = errors.New("task: force operation requires reason")
	// ErrForceOpRateLimited reports that an actor exceeded the force-operation rate limit.
	ErrForceOpRateLimited = errors.New("task: force operation rate limited")
	// ErrRetryChainTooDeep reports that retry would exceed the configured retry lineage depth.
	ErrRetryChainTooDeep = errors.New("task: retry chain too deep")
	// ErrBulkTooLarge reports that a bulk operation exceeded its bounded item limit.
	ErrBulkTooLarge = errors.New("task: bulk operation too large")
)

Functions

func ClaimTokenHash 

func ClaimTokenHash(rawToken string) (string, error)

ClaimTokenHash returns the canonical hash persisted for one raw claim token.

func DefaultSchedulerDrainTimeout 

func DefaultSchedulerDrainTimeout() time.Duration

DefaultSchedulerDrainTimeout keeps API transports from duplicating scheduler policy.

func ImmutableTaskFields 

func ImmutableTaskFields() []string

ImmutableTaskFields returns the canonical immutable task field names.

func IsImmutableTaskField 

func IsImmutableTaskField(field string) bool

IsImmutableTaskField reports whether the supplied field name is immutable after task creation.

func IsMutableTaskField 

func IsMutableTaskField(field string) bool

IsMutableTaskField reports whether the supplied field name is directly mutable on a task.

func IsTerminalRunStatus 

func IsTerminalRunStatus(status RunStatus) bool

func MutableTaskFields 

func MutableTaskFields() []string

MutableTaskFields returns the canonical mutable task field names.

func NewClaimToken 

func NewClaimToken() (string, error)

NewClaimToken generates one raw bearer token for a successful claim response.

func RedactClaimTokens 

func RedactClaimTokens(value string) string

RedactClaimTokens replaces raw claim bearer tokens in free-form strings.

func ValidateApprovalSemantics 

func ValidateApprovalSemantics(policy ApprovalPolicy, state ApprovalState, path string) error

ValidateApprovalSemantics reports whether one approval policy and state pair is internally consistent.

func ValidateCapabilityIDs 

func ValidateCapabilityIDs(values []string, path string) error

ValidateCapabilityIDs reports whether every capability identifier is safe for exact matching.

func ValidateDependencyCount 

func ValidateDependencyCount(count int) error

ValidateDependencyCount reports whether the supplied dependency count stays within the bounded edge limit.

func ValidateDirectChildCount 

func ValidateDirectChildCount(count int) error

ValidateDirectChildCount reports whether the supplied direct-child count stays within the bounded fan-out limit.

func ValidateHierarchyDepth 

func ValidateHierarchyDepth(depth int) error

ValidateHierarchyDepth reports whether the supplied task depth stays within the bounded hierarchy limit.

func ValidateImmutableTaskFields 

func ValidateImmutableTaskFields(current Task, next Task) error

ValidateImmutableTaskFields reports whether an update attempted to change immutable task fields.

func ValidateMetadataSize 

func ValidateMetadataSize(payload json.RawMessage, path string) error

ValidateMetadataSize reports whether metadata JSON respects the shared 16 KiB guardrail.

func ValidatePayloadSize 

func ValidatePayloadSize(payload json.RawMessage, path string) error

ValidatePayloadSize reports whether a persisted JSON payload respects the shared 64 KiB guardrail.

func ValidateResultSize 

func ValidateResultSize(payload json.RawMessage, path string) error

ValidateResultSize reports whether a persisted run result respects the shared 64 KiB guardrail.

func ValidateScopeBinding 

func ValidateScopeBinding(scope Scope, workspaceBinding string, path string, workspaceField string) error

ValidateScopeBinding enforces the canonical scope/workspace invariant shared by task-domain records.

func VerifyClaimToken 

func VerifyClaimToken(rawToken string, persistedHash string) bool

VerifyClaimToken reports whether rawToken hashes to the persisted canonical hash.

Types

type ActorContext 

type ActorContext struct {
	Actor     ActorIdentity `json:"actor"`
	Origin    Origin        `json:"origin"`
	Authority Authority     `json:"authority"`
}

ActorContext carries the authenticated principal, ingress origin, and resolved task authority.

func DeriveAgentSessionActorContext 

func DeriveAgentSessionActorContext(sessionRef string) (ActorContext, error)

DeriveAgentSessionActorContext derives one trusted agent-session actor context. The session ref becomes both the immutable actor ref and origin ref.

func DeriveAgentSessionActorContextForOrigin 

func DeriveAgentSessionActorContextForOrigin(
	sessionRef string,
	originKind OriginKind,
	originRef string,
) (ActorContext, error)

DeriveAgentSessionActorContextForOrigin derives one trusted agent-session actor context for an authenticated agent ingress operation.

func DeriveAutomationActorContext 

func DeriveAutomationActorContext(actorRef string, originRef string) (ActorContext, error)

DeriveAutomationActorContext derives one trusted automation actor context. If originRef is empty, the actor ref is reused as the durable origin ref.

func DeriveAutomationLinkedAgentSessionActorContext 

func DeriveAutomationLinkedAgentSessionActorContext(sessionRef string, originRef string) (ActorContext, error)

DeriveAutomationLinkedAgentSessionActorContext derives one trusted agent-session actor context for work created explicitly by an automation- launched session. The session remains the immutable actor while the origin is anchored to the automation activation that launched it.

func DeriveDaemonActorContext 

func DeriveDaemonActorContext(actorRef string, originRef string) (ActorContext, error)

DeriveDaemonActorContext derives one trusted daemon-owned actor context. If originRef is empty, the actor ref is reused as the durable origin ref.

func DeriveExtensionActorContext 

func DeriveExtensionActorContext(actorRef string, originRef string) (ActorContext, error)

DeriveExtensionActorContext derives one trusted extension actor context. If originRef is empty, the actor ref is reused as the durable origin ref.

func DeriveHumanActorContext 

func DeriveHumanActorContext(actorRef string, originKind OriginKind, originRef string) (ActorContext, error)

DeriveHumanActorContext derives one trusted local-human actor context for CLI, web, HTTP, or UDS task ingress.

func DeriveNetworkPeerActorContext 

func DeriveNetworkPeerActorContext(actorRef string, originRef string) (ActorContext, error)

DeriveNetworkPeerActorContext derives one trusted network-peer actor context. If originRef is empty, the actor ref is reused as the durable origin ref so ingress layers may include peer or peer/channel details as needed.

func (ActorContext) Validate 

func (a ActorContext) Validate() error

Validate reports whether the actor context contains a valid principal, origin, and authority envelope.

type ActorIdentity 

type ActorIdentity struct {
	Kind ActorKind `json:"kind"`
	Ref  string    `json:"ref"`
}

ActorIdentity is the immutable server-derived actor identity attached to task and run writes.

func (ActorIdentity) Validate 

func (a ActorIdentity) Validate(path string) error

Validate reports whether the actor identity contains a supported kind and non-empty reference.

type ActorKind 

type ActorKind string

ActorKind identifies the authenticated principal class behind task writes. 

const (
	// ActorKindHuman identifies a human principal writing through CLI, web, HTTP, or UDS surfaces.
	ActorKindHuman ActorKind = "human"
	// ActorKindAgentSession identifies an AGH agent session principal.
	ActorKindAgentSession ActorKind = "agent_session"
	// ActorKindAutomation identifies daemon-owned automation flows.
	ActorKindAutomation ActorKind = "automation"
	// ActorKindExtension identifies an authenticated extension runtime principal.
	ActorKindExtension ActorKind = "extension"
	// ActorKindNetworkPeer identifies an authenticated network peer principal.
	ActorKindNetworkPeer ActorKind = "network_peer"
	// ActorKindDaemon identifies daemon-owned system work.
	ActorKindDaemon ActorKind = "daemon"
)

func (ActorKind) Normalize 

func (k ActorKind) Normalize() ActorKind

Normalize returns the normalized representation of the actor kind.

func (ActorKind) Validate 

func (k ActorKind) Validate(path string) error

Validate reports whether the actor kind is supported.

type AddDependency 

type AddDependency struct {
	TaskID          string         `json:"task_id"`
	DependsOnTaskID string         `json:"depends_on_task_id"`
	Kind            DependencyKind `json:"kind"`
}

AddDependency captures one dependency-edge creation request.

func (AddDependency) Validate 

func (r AddDependency) Validate(path string) error

Validate reports whether the dependency-create request is internally consistent.

type ApprovalPolicy 

type ApprovalPolicy string

ApprovalPolicy identifies whether a task requires an explicit approval step. 

const (
	// ApprovalPolicyNone identifies tasks that do not require approval.
	ApprovalPolicyNone ApprovalPolicy = "none"
	// ApprovalPolicyManual identifies tasks that require an explicit approve or reject action.
	ApprovalPolicyManual ApprovalPolicy = "manual"
	// DefaultApprovalPolicy is the canonical policy used when callers omit approval requirements.
	DefaultApprovalPolicy ApprovalPolicy = ApprovalPolicyNone
)

func (ApprovalPolicy) Normalize 

func (p ApprovalPolicy) Normalize() ApprovalPolicy

Normalize returns the normalized representation of the approval policy.

func (ApprovalPolicy) Validate 

func (p ApprovalPolicy) Validate(path string) error

Validate reports whether the approval policy is one of the supported values.

type ApprovalState 

type ApprovalState string

ApprovalState identifies the current approval outcome for one task. 

const (
	// ApprovalStateNotRequired identifies tasks whose policy does not require approval.
	ApprovalStateNotRequired ApprovalState = "not_required"
	// ApprovalStatePending identifies tasks waiting for approval.
	ApprovalStatePending ApprovalState = "pending"
	// ApprovalStateApproved identifies tasks that were approved.
	ApprovalStateApproved ApprovalState = "approved"
	// ApprovalStateRejected identifies tasks that were rejected.
	ApprovalStateRejected ApprovalState = "rejected"
)

func (ApprovalState) Normalize 

func (s ApprovalState) Normalize() ApprovalState

Normalize returns the normalized representation of the approval state.

func (ApprovalState) Validate 

func (s ApprovalState) Validate(path string) error

Validate reports whether the approval state is one of the supported values.

type Authority 

type Authority struct {
	Read            bool `json:"read"`
	Write           bool `json:"write"`
	CreateGlobal    bool `json:"create_global"`
	CreateWorkspace bool `json:"create_workspace"`
}

Authority captures the task-domain permissions resolved for one authenticated principal.

func FullAccessAuthority 

func FullAccessAuthority() Authority

FullAccessAuthority returns the v1 broad task-domain authority granted to authenticated first-class task surfaces after ingress-level authentication and capability checks succeed.

func (Authority) Validate 

func (a Authority) Validate(path string) error

Validate reports whether the authority flags are internally consistent.

type AutonomyError 

type AutonomyError struct {
	Reason AutonomyReasonCode
	Err    error
}

AutonomyError carries the deterministic reason for a session-bound autonomy rejection.

func (*AutonomyError) Error 

func (e *AutonomyError) Error() string

Error returns the redacted public error string.

func (*AutonomyError) Unwrap 

func (e *AutonomyError) Unwrap() error

Unwrap returns the wrapped task-domain sentinel.

type AutonomyLeaseAuthority 

type AutonomyLeaseAuthority interface {
	LookupActiveRunForSession(
		ctx context.Context,
		sessionID string,
		runID string,
	) (AutonomyLeaseHandle, error)
}

AutonomyLeaseAuthority resolves the internal lease credential for the calling session without exposing the raw claim token at public boundaries.

type AutonomyLeaseHandle 

type AutonomyLeaseHandle struct {
	RunID          string
	TaskID         string
	WorkspaceID    string
	SessionID      string
	Status         RunStatus
	ClaimedBy      *ActorIdentity
	ClaimToken     string
	ClaimTokenHash string
	LeaseUntil     time.Time
	HeartbeatAt    time.Time
}

AutonomyLeaseHandle is the internal-only active lease handle used to call the existing token-fenced lease writers.

type AutonomyLeaseStore 

type AutonomyLeaseStore interface {
	ListAutonomyLeaseHandles(ctx context.Context, sessionID string) ([]AutonomyLeaseHandle, error)
}

AutonomyLeaseStore is the narrowed internal store surface required by the session-bound autonomy lookup.

type AutonomyReasonCode 

type AutonomyReasonCode string

AutonomyReasonCode is the stable machine-readable reason for session-bound autonomy lease lookup failures. 

const (
	AutonomySessionRequired  AutonomyReasonCode = "AUTONOMY_SESSION_REQUIRED"
	AutonomyNoActiveLease    AutonomyReasonCode = "AUTONOMY_NO_ACTIVE_LEASE"
	AutonomyForeignRun       AutonomyReasonCode = "AUTONOMY_FOREIGN_RUN"
	AutonomyLeaseExpired     AutonomyReasonCode = "AUTONOMY_LEASE_EXPIRED"
	AutonomyLeaseAlreadyHeld AutonomyReasonCode = "AUTONOMY_LEASE_ALREADY_HELD"
)

func AutonomyReasonOf 

func AutonomyReasonOf(err error) (AutonomyReasonCode, bool)

AutonomyReasonOf extracts a deterministic autonomy reason code from an error.

type BindRunReviewSessionRequest 

type BindRunReviewSessionRequest struct {
	ReviewID          string `json:"review_id"`
	SessionID         string `json:"session_id"`
	ReviewerAgentName string `json:"reviewer_agent_name,omitempty"`
	ReviewerPeerID    string `json:"reviewer_peer_id,omitempty"`
	ReviewerChannelID string `json:"reviewer_channel_id,omitempty"`
}

BindRunReviewSessionRequest captures a reviewer-session binding.

func (BindRunReviewSessionRequest) Normalize 

func (r BindRunReviewSessionRequest) Normalize() BindRunReviewSessionRequest

Normalize returns a canonical reviewer-session binding request.

func (BindRunReviewSessionRequest) Validate 

func (r BindRunReviewSessionRequest) Validate(path string) error

Validate reports whether the binding request can bind a reviewer session.

type BulkForceRunItem 

type BulkForceRunItem struct {
	RunID string `json:"run_id"`
	OK    bool   `json:"ok"`
	Run   *Run   `json:"run,omitempty"`
	Err   error  `json:"-"`
}

BulkForceRunItem records one per-run bulk recovery outcome.

type BulkForceRunRequest 

type BulkForceRunRequest struct {
	RunIDs   []string        `json:"run_ids"`
	Reason   string          `json:"reason,omitempty"`
	Metadata json.RawMessage `json:"metadata,omitempty"`
}

BulkForceRunRequest captures a bounded release/fail batch.

type BulkForceRunResult 

type BulkForceRunResult struct {
	Items []BulkForceRunItem `json:"items"`
}

BulkForceRunResult records bounded per-row outcomes.

type CancelRun 

type CancelRun struct {
	Reason   string          `json:"reason,omitempty"`
	Metadata json.RawMessage `json:"metadata,omitempty"`
}

CancelRun captures one run-cancellation request.

func (CancelRun) Validate 

func (r CancelRun) Validate(path string) error

Validate reports whether the cancel-run request is internally consistent.

type CancelTask 

type CancelTask struct {
	Reason   string          `json:"reason,omitempty"`
	Metadata json.RawMessage `json:"metadata,omitempty"`
}

CancelTask captures the task-level cancellation request payload.

func (CancelTask) Validate 

func (r CancelTask) Validate(path string) error

Validate reports whether the task-cancellation request is internally consistent.

type ClaimCriteria 

type ClaimCriteria struct {
	Scope                 Scope                `json:"scope,omitempty"`
	WorkspaceID           string               `json:"workspace_id,omitempty"`
	ClaimerSessionID      string               `json:"claimer_session_id"`
	ClaimedBy             *ActorIdentity       `json:"claimed_by,omitempty"`
	AgentName             string               `json:"agent_name,omitempty"`
	RequiredCapabilities  []string             `json:"required_capabilities,omitempty"`
	PriorityMin           int                  `json:"priority_min,omitempty"`
	CoordinationChannelID string               `json:"coordination_channel_id,omitempty"`
	Soul                  *SoulClaimProvenance `json:"soul,omitempty"`
	LeaseDuration         time.Duration        `json:"lease_duration"`
	Now                   time.Time            `json:"now"`
}

ClaimCriteria captures the atomic next-work filters for one claiming session.

func (ClaimCriteria) Normalize 

func (c ClaimCriteria) Normalize(defaultNow time.Time) (ClaimCriteria, error)

Normalize returns a validated claim criteria with default scope, time, and lease duration applied.

func (ClaimCriteria) Validate 

func (c ClaimCriteria) Validate(path string) error

Validate reports whether the claim criteria is safe to execute transactionally.

type ClaimResult 

type ClaimResult struct {
	Task                Task                         `json:"task"`
	Run                 Run                          `json:"run"`
	ClaimToken          string                       `json:"claim_token"`
	LeaseUntil          time.Time                    `json:"lease_until"`
	CoordinationChannel *CoordinationChannelMetadata `json:"coordination_channel,omitempty"`
}

ClaimResult is the successful synchronous claim result. ClaimToken is raw and must not cross public surfaces.

type ClaimRun 

type ClaimRun struct {
	IdempotencyKey string `json:"idempotency_key,omitempty"`
}

ClaimRun captures one run-claim request.

func (ClaimRun) Validate 

func (r ClaimRun) Validate(path string) error

Validate reports whether the claim-run request is internally consistent.

type ContextBundle 

type ContextBundle struct {
	Task               Reference           `json:"task"`
	LatestEventSeq     int64               `json:"latest_event_seq"`
	CurrentRun         *RunSummary         `json:"current_run,omitempty"`
	PriorAttempts      []RunSummary        `json:"prior_attempts"`
	RecentEvents       []TimelineItem      `json:"recent_events"`
	HandoffSummary     string              `json:"handoff_summary,omitempty"`
	Limits             RuntimeLimits       `json:"limits"`
	ExecutionProfile   *ExecutionProfile   `json:"execution_profile,omitempty"`
	ReviewContinuation *ReviewContinuation `json:"review_continuation,omitempty"`
	ReviewHistory      []RunReviewSummary  `json:"review_history"`
}

ContextBundle is the bounded task/run context injected into task sessions.

func NormalizeContextBundle 

func NormalizeContextBundle(bundle ContextBundle) ContextBundle

NormalizeContextBundle returns a bundle with stable empty array fields.

type ContextRequest 

type ContextRequest struct {
	SessionID string    `json:"session_id"`
	RunID     string    `json:"run_id,omitempty"`
	Now       time.Time `json:"now"`
}

ContextRequest identifies the active lease context one agent session may read.

type CoordinationChannelMetadata 

type CoordinationChannelMetadata struct {
	ID                  string    `json:"id"`
	Channel             string    `json:"channel,omitempty"`
	DisplayName         string    `json:"display_name"`
	Purpose             string    `json:"purpose,omitempty"`
	WorkspaceID         string    `json:"workspace_id,omitempty"`
	TaskID              string    `json:"task_id,omitempty"`
	RunID               string    `json:"run_id,omitempty"`
	WorkflowID          string    `json:"workflow_id,omitempty"`
	AllowedMessageKinds []string  `json:"allowed_message_kinds,omitempty"`
	LastActivityAt      time.Time `json:"last_activity_at"`
}

CoordinationChannelMetadata is the safe channel display metadata returned with a claim.

type CoordinatorMode 

type CoordinatorMode string

CoordinatorMode identifies task-specific coordinator bootstrap behavior.

func (CoordinatorMode) Normalize 

func (m CoordinatorMode) Normalize() CoordinatorMode

Normalize returns the normalized coordinator mode.

type CoordinatorProfile 

type CoordinatorProfile struct {
	Mode      CoordinatorMode `json:"mode"`
	AgentName string          `json:"agent_name,omitempty"`
	Provider  string          `json:"provider,omitempty"`
	Model     string          `json:"model,omitempty"`
	Guidance  string          `json:"guidance,omitempty"`
}

CoordinatorProfile supplies optional guidance to the existing coordinator runtime.

type CreateTask 

type CreateTask struct {
	ID             string          `json:"id,omitempty"`
	Identifier     string          `json:"identifier,omitempty"`
	Scope          Scope           `json:"scope"`
	WorkspaceID    string          `json:"workspace_id,omitempty"`
	ParentTaskID   string          `json:"parent_task_id,omitempty"`
	NetworkChannel string          `json:"network_channel,omitempty"`
	Title          string          `json:"title"`
	Description    string          `json:"description,omitempty"`
	Priority       Priority        `json:"priority,omitempty"`
	MaxAttempts    *int            `json:"max_attempts,omitempty"`
	Draft          bool            `json:"draft,omitempty"`
	ApprovalPolicy ApprovalPolicy  `json:"approval_policy,omitempty"`
	Owner          *Ownership      `json:"owner,omitempty"`
	Metadata       json.RawMessage `json:"metadata,omitempty"`
}

CreateTask captures the mutable inputs accepted when creating a new task.

func (CreateTask) Validate 

func (r CreateTask) Validate(path string) error

Validate reports whether the create-task request is internally consistent.

type DeleteTaskMutationStore 

type DeleteTaskMutationStore interface {
	GetTask(ctx context.Context, id string) (Task, error)
	UpdateTask(ctx context.Context, task Task) error
	DeleteTask(ctx context.Context, id string) error
	CountDirectChildren(ctx context.Context, parentTaskID string) (int, error)
	ListDependencies(ctx context.Context, taskID string) ([]Dependency, error)
	ListDependents(ctx context.Context, dependsOnTaskID string) ([]Dependency, error)
	ListTaskRuns(ctx context.Context, query RunQuery) ([]Run, error)
}

DeleteTaskMutationStore is the narrowed persistence surface required to execute task deletion and dependent reconciliation as one unit.

type DeleteTaskTransactionStore 

type DeleteTaskTransactionStore interface {
	WithDeleteTaskTransaction(ctx context.Context, fn func(DeleteTaskMutationStore) error) error
}

DeleteTaskTransactionStore optionally exposes transactional delete-task execution so the manager can roll back the primary delete when dependent reconciliation fails.

type Dependency 

type Dependency struct {
	TaskID          string         `json:"task_id"`
	DependsOnTaskID string         `json:"depends_on_task_id"`
	Kind            DependencyKind `json:"kind"`
	CreatedAt       time.Time      `json:"created_at"`
}

Dependency is the durable edge record connecting one task to a blocking dependency.

func (Dependency) Validate 

func (d Dependency) Validate() error

Validate reports whether the dependency edge contains the canonical persisted shape.

type DependencyKind 

type DependencyKind string

DependencyKind identifies the semantic meaning of one dependency edge. 

const (
	// DependencyKindBlocks identifies a dependency that must resolve before the task may proceed.
	DependencyKindBlocks DependencyKind = "blocks"
)

func (DependencyKind) Normalize 

func (k DependencyKind) Normalize() DependencyKind

Normalize returns the normalized representation of the dependency kind.

func (DependencyKind) Validate 

func (k DependencyKind) Validate(path string) error

Validate reports whether the dependency kind is supported.

type DependencyReference 

type DependencyReference struct {
	TaskID          string         `json:"task_id"`
	DependsOnTaskID string         `json:"depends_on_task_id"`
	Kind            DependencyKind `json:"kind"`
	CreatedAt       time.Time      `json:"created_at"`
	DependsOn       Reference      `json:"depends_on"`
}

DependencyReference enriches one dependency edge with the referenced blocker identity.

type DependencyStore 

type DependencyStore interface {
	CreateDependency(ctx context.Context, dependency Dependency) error
	DeleteDependency(ctx context.Context, taskID string, dependsOnID string) error
	ListDependencies(ctx context.Context, taskID string) ([]Dependency, error)
	ListDependents(ctx context.Context, dependsOnTaskID string) ([]Dependency, error)
	CountDependencies(ctx context.Context, taskID string) (int, error)
	HasDependencyPath(ctx context.Context, fromTaskID string, toTaskID string) (bool, error)
}

DependencyStore is the persistence surface for durable dependency edges.

type EnqueueRun 

type EnqueueRun struct {
	TaskID         string          `json:"task_id"`
	IdempotencyKey string          `json:"idempotency_key,omitempty"`
	NetworkChannel string          `json:"network_channel,omitempty"`
	Metadata       json.RawMessage `json:"metadata,omitempty"`
}

EnqueueRun captures the mutable inputs accepted when queuing a task run.

func (EnqueueRun) Validate 

func (r EnqueueRun) Validate(path string) error

Validate reports whether the enqueue-run request is internally consistent.

type Event 

type Event struct {
	ID        string          `json:"id"`
	TaskID    string          `json:"task_id"`
	RunID     string          `json:"run_id,omitempty"`
	EventType string          `json:"event_type"`
	Actor     ActorIdentity   `json:"actor"`
	Origin    Origin          `json:"origin"`
	Payload   json.RawMessage `json:"payload,omitempty"`
	Timestamp time.Time       `json:"timestamp"`
}

Event is the immutable audit record emitted for task-domain actions.

func (Event) Validate 

func (e Event) Validate() error

Validate reports whether the audit event contains the canonical persisted shape.

type EventObserver 

type EventObserver interface {
	OnTaskEvent(ctx context.Context, record EventRecord)
}

EventObserver receives immutable task events after durable persistence.

type EventQuery 

type EventQuery struct {
	TaskID    string `json:"task_id,omitempty"`
	RunID     string `json:"run_id,omitempty"`
	EventType string `json:"event_type,omitempty"`
	Limit     int    `json:"limit,omitempty"`
}

EventQuery captures the supported list filters for task-event reads.

func (EventQuery) Validate 

func (q EventQuery) Validate(path string) error

Validate reports whether the task-event query filters are internally consistent.

type EventRecord 

type EventRecord struct {
	Sequence int64 `json:"sequence"`
	Event    Event `json:"event"`
}

EventRecord is one immutable task event plus its stable stream sequence.

type EventRecordQuery 

type EventRecordQuery struct {
	TaskID        string `json:"task_id,omitempty"`
	AfterSequence int64  `json:"after_sequence,omitempty"`
	Limit         int    `json:"limit,omitempty"`
	Descending    bool   `json:"descending,omitempty"`
}

EventRecordQuery captures low-level task event record reads that include a stable sequence.

func (EventRecordQuery) Validate 

func (q EventRecordQuery) Validate(path string) error

Validate reports whether the sequenced event record query is internally consistent.

type EventSequenceStore 

type EventSequenceStore interface {
	GetTaskEventRecord(ctx context.Context, eventID string) (EventRecord, error)
	ListTaskEventRecords(ctx context.Context, query EventRecordQuery) ([]EventRecord, error)
}

EventSequenceStore is the persistence surface for stable task event sequencing used by live reads.

type EventStore 

type EventStore interface {
	CreateTaskEvent(ctx context.Context, event Event) error
	ListTaskEvents(ctx context.Context, query EventQuery) ([]Event, error)
}

EventStore is the persistence surface for immutable task audit events.

type Execution 

type Execution struct {
	Task        Task            `json:"task"`
	Run         Run             `json:"run"`
	Action      ExecutionAction `json:"action"`
	ExistingRun bool            `json:"existing_run,omitempty"`
}

Execution captures the task and run created or resolved at the explicit execution boundary.

type ExecutionAction 

type ExecutionAction string

ExecutionAction identifies the operator action that crossed the create-versus-execute lifecycle boundary. 

const (
	// ExecutionActionStart records an explicit operator start request.
	ExecutionActionStart ExecutionAction = "start"
	// ExecutionActionPublish records a draft publish request that also starts execution.
	ExecutionActionPublish ExecutionAction = "publish"
	// ExecutionActionApproval records an approval request that also starts execution.
	ExecutionActionApproval ExecutionAction = "approval"
)

type ExecutionProfile 

type ExecutionProfile struct {
	TaskID       string             `json:"task_id"`
	Coordinator  CoordinatorProfile `json:"coordinator"`
	Worker       WorkerProfile      `json:"worker"`
	Review       ReviewProfile      `json:"review"`
	Participants ParticipantPolicy  `json:"participants"`
	Sandbox      SandboxPolicy      `json:"sandbox"`
	CreatedAt    time.Time          `json:"created_at"`
	UpdatedAt    time.Time          `json:"updated_at"`
}

ExecutionProfile is the typed task-owned orchestration selection state.

func DefaultExecutionProfile 

func DefaultExecutionProfile(taskID string) ExecutionProfile

DefaultExecutionProfile returns the inherit-mode profile for one task.

func (*ExecutionProfile) Normalize 

func (p *ExecutionProfile) Normalize(options ExecutionProfileValidationOptions) (ExecutionProfile, error)

Normalize returns a canonical copy with trimmed fields, default modes, and stable selector sets.

func (*ExecutionProfile) Validate 

func (p *ExecutionProfile) Validate(options ExecutionProfileValidationOptions) error

Validate reports whether the profile can be persisted as typed orchestration state.

type ExecutionProfileStore 

type ExecutionProfileStore interface {
	GetExecutionProfile(ctx context.Context, taskID string) (ExecutionProfile, error)
	UpsertExecutionProfile(ctx context.Context, profile *ExecutionProfile) (ExecutionProfile, error)
	DeleteExecutionProfile(ctx context.Context, taskID string) error
}

ExecutionProfileStore is the persistence surface for task-owned execution profiles.

type ExecutionProfileValidationOptions 

type ExecutionProfileValidationOptions struct {
	AllowProviderOverride       bool
	AllowSandboxNone            bool
	AllowSandboxRef             bool
	MaxCoordinatorGuidanceBytes int
}

ExecutionProfileValidationOptions carries config-backed gates without coupling task to config.

func DefaultExecutionProfileValidationOptions 

func DefaultExecutionProfileValidationOptions() ExecutionProfileValidationOptions

DefaultExecutionProfileValidationOptions returns the permissive built-in gates.

type ExecutionRequest 

type ExecutionRequest struct {
	IdempotencyKey string          `json:"idempotency_key,omitempty"`
	NetworkChannel string          `json:"network_channel,omitempty"`
	Metadata       json.RawMessage `json:"metadata,omitempty"`
}

ExecutionRequest captures the mutable inputs accepted when an operator publish, start, or approval action enqueues executable work.

func (ExecutionRequest) Validate 

func (r ExecutionRequest) Validate(path string) error

Validate reports whether the task execution request is internally consistent.

type ExpiredLeaseRecovery 

type ExpiredLeaseRecovery struct {
	Now    time.Time `json:"now"`
	Reason string    `json:"reason,omitempty"`
	Limit  int       `json:"limit,omitempty"`
}

ExpiredLeaseRecovery captures deterministic recovery of stale task-run leases.

func (ExpiredLeaseRecovery) Normalize 

func (r ExpiredLeaseRecovery) Normalize(defaultNow time.Time) (ExpiredLeaseRecovery, error)

Normalize returns a validated expired-lease recovery request.

func (ExpiredLeaseRecovery) Validate 

func (r ExpiredLeaseRecovery) Validate(path string) error

Validate reports whether the expired-lease recovery request is internally consistent.

type ExpiredLeaseRecoveryResult 

type ExpiredLeaseRecoveryResult struct {
	Run                    Run       `json:"run"`
	PreviousRunStatus      RunStatus `json:"previous_run_status"`
	PreviousSessionID      string    `json:"previous_session_id,omitempty"`
	PreviousLeaseUntil     time.Time `json:"previous_lease_until"`
	PreviousClaimTokenHash string    `json:"previous_claim_token_hash,omitempty"`
	Reason                 string    `json:"reason,omitempty"`
}

ExpiredLeaseRecoveryResult records one recovered lease and its previous owner state.

type ForceFailRun 

type ForceFailRun struct {
	Reason   string          `json:"reason"`
	Metadata json.RawMessage `json:"metadata,omitempty"`
}

ForceFailRun captures one operator/agent forced failure request.

type ForceFailRunMutation 

type ForceFailRunMutation struct {
	RunID  string    `json:"run_id"`
	Reason string    `json:"reason"`
	Now    time.Time `json:"now"`
}

ForceFailRunMutation captures one transactional force-fail write.

type ForceRecoveryOptions 

type ForceRecoveryOptions struct {
	AllowAgentForce    bool `json:"allow_agent_force"`
	RateLimitPerMinute int  `json:"rate_limit_per_minute,omitempty"`
}

ForceRecoveryOptions controls operator/agent force-operation policy.

type ForceReleaseRun 

type ForceReleaseRun struct {
	Reason   string          `json:"reason,omitempty"`
	Metadata json.RawMessage `json:"metadata,omitempty"`
}

ForceReleaseRun captures one operator/agent force release request.

type ForceReleaseRunMutation 

type ForceReleaseRunMutation struct {
	RunID string    `json:"run_id"`
	Now   time.Time `json:"now"`
}

ForceReleaseRunMutation captures one transactional force-release write.

type ForceRunMutationResult 

type ForceRunMutationResult struct {
	Previous Run `json:"previous"`
	Run      Run `json:"run"`
}

ForceRunMutationResult records the before/after state for one force mutation.

type IdempotencyStore 

type IdempotencyStore interface {
	GetTaskRunByIdempotencyKey(ctx context.Context, key string, origin Origin) (Run, error)
	SaveTaskRunIdempotency(ctx context.Context, record RunIdempotency) error
}

IdempotencyStore is the persistence surface for non-human run idempotency tracking.

type InspectEventSummary 

type InspectEventSummary struct {
	ID        string    `json:"id"`
	Type      string    `json:"type"`
	SessionID string    `json:"session_id,omitempty"`
	TaskID    string    `json:"task_id,omitempty"`
	RunID     string    `json:"run_id,omitempty"`
	Outcome   string    `json:"outcome,omitempty"`
	Summary   string    `json:"summary,omitempty"`
	Timestamp time.Time `json:"timestamp"`
}

InspectEventSummary is the recent event summary projection used by task inspect.

type InspectNextAction 

type InspectNextAction string

InspectNextAction is the deterministic next-step hint emitted by task inspect. 

const (
	InspectNextActionClaimAvailable    InspectNextAction = "claim_available"
	InspectNextActionWaitingForSession InspectNextAction = "waiting_for_session"
	InspectNextActionStranded          InspectNextAction = "stranded"
	InspectNextActionRunning           InspectNextAction = "running"
	InspectNextActionRecoveryRequired  InspectNextAction = "recovery_required"
	InspectNextActionTerminal          InspectNextAction = "terminal"
)

type InspectRunSummary 

type InspectRunSummary struct {
	RunID                   string    `json:"run_id"`
	TaskID                  string    `json:"task_id"`
	Status                  RunStatus `json:"status"`
	ClaimTokenHashTruncated string    `json:"claim_token_hash_truncated,omitempty"`
	LeaseUntil              time.Time `json:"lease_until"`
	HeartbeatAt             time.Time `json:"heartbeat_at"`
	HeartbeatAgeSeconds     *int64    `json:"heartbeat_age_seconds,omitempty"`
	Retries                 int       `json:"retries,omitempty"`
	LastErrorSummary        string    `json:"last_error_summary,omitempty"`
	FailureKind             string    `json:"failure_kind,omitempty"`
	BoundSessionID          string    `json:"bound_session_id,omitempty"`
	StartedAt               time.Time `json:"started_at"`
	EndedAt                 time.Time `json:"ended_at"`
	PreviousRunID           string    `json:"previous_run_id,omitempty"`
	QueuedAt                time.Time `json:"queued_at"`
	Attempt                 int       `json:"attempt"`
}

InspectRunSummary is the redacted run projection used by task inspect.

type InspectSchedulerState 

type InspectSchedulerState struct {
	Paused    bool      `json:"paused"`
	PausedBy  string    `json:"paused_by,omitempty"`
	PausedAt  time.Time `json:"paused_at"`
	Reason    string    `json:"reason,omitempty"`
	UpdatedAt time.Time `json:"updated_at"`
}

InspectSchedulerState captures the read-only scheduler pause state used by diagnostics.

type InspectSessionSummary 

type InspectSessionSummary struct {
	SessionID      string    `json:"session_id"`
	State          string    `json:"state,omitempty"`
	AgentName      string    `json:"agent_name,omitempty"`
	ProviderName   string    `json:"provider_name,omitempty"`
	WorkspaceID    string    `json:"workspace_id,omitempty"`
	StartedAt      time.Time `json:"started_at"`
	LastActivityAt time.Time `json:"last_activity_at"`
	StopReason     string    `json:"stop_reason,omitempty"`
	FailureKind    string    `json:"failure_kind,omitempty"`
}

InspectSessionSummary is the session projection used by task inspect.

type InspectStateReader 

type InspectStateReader interface {
	ListSessions(ctx context.Context, query store.SessionListQuery) ([]store.SessionInfo, error)
	ListEventSummaries(ctx context.Context, query store.EventSummaryQuery) ([]store.EventSummary, error)
	GetSchedulerPauseState(ctx context.Context) (InspectSchedulerState, error)
}

InspectStateReader supplies read-only runtime state for task inspect diagnostics.

type InspectTarget 

type InspectTarget string

InspectTarget identifies whether an inspect response was requested by task or run id. 

const (
	// InspectTargetTask reports an inspect request rooted at a task id.
	InspectTargetTask InspectTarget = "task"
	// InspectTargetRun reports an inspect request rooted at a run id.
	InspectTargetRun InspectTarget = "run"
)

type InspectView 

type InspectView struct {
	Target                InspectTarget                       `json:"target"`
	Task                  Summary                             `json:"task"`
	CurrentRun            *InspectRunSummary                  `json:"current_run,omitempty"`
	BoundSession          *InspectSessionSummary              `json:"bound_session,omitempty"`
	RecentRuns            []InspectRunSummary                 `json:"recent_runs,omitempty"`
	RecentEvents          []InspectEventSummary               `json:"recent_events,omitempty"`
	Scheduler             InspectSchedulerState               `json:"scheduler"`
	Diagnostics           []diagnosticcontract.DiagnosticItem `json:"diagnostics,omitempty"`
	NextAction            InspectNextAction                   `json:"next_action"`
	AsOf                  time.Time                           `json:"as_of"`
	EligibleSessionCount  int                                 `json:"-"`
	SessionCatalogPresent bool                                `json:"-"`
}

InspectView is the task-domain read-only snapshot behind CLI/API inspect.

type LeaseCompletion 

type LeaseCompletion struct {
	RunID      string    `json:"run_id"`
	ClaimToken string    `json:"claim_token"`
	Result     RunResult `json:"result"`
	Now        time.Time `json:"now"`
}

LeaseCompletion captures a token-fenced successful terminal transition.

func (LeaseCompletion) Normalize 

func (c LeaseCompletion) Normalize(defaultNow time.Time) (LeaseCompletion, error)

Normalize returns a validated completion request with default time applied.

func (LeaseCompletion) Validate 

func (c LeaseCompletion) Validate(path string) error

Validate reports whether the completion request is internally consistent.

type LeaseFailure 

type LeaseFailure struct {
	RunID      string     `json:"run_id"`
	ClaimToken string     `json:"claim_token"`
	Failure    RunFailure `json:"failure"`
	Now        time.Time  `json:"now"`
}

LeaseFailure captures a token-fenced failed terminal transition.

func (LeaseFailure) Normalize 

func (f LeaseFailure) Normalize(defaultNow time.Time) (LeaseFailure, error)

Normalize returns a validated failure request with default time applied.

func (LeaseFailure) Validate 

func (f LeaseFailure) Validate(path string) error

Validate reports whether the failure request is internally consistent.

type LeaseHeartbeat 

type LeaseHeartbeat struct {
	RunID         string        `json:"run_id"`
	ClaimToken    string        `json:"claim_token"`
	LeaseDuration time.Duration `json:"lease_duration"`
	Now           time.Time     `json:"now"`
}

LeaseHeartbeat captures a token-fenced lease extension request.

func (LeaseHeartbeat) Normalize 

func (h LeaseHeartbeat) Normalize(defaultNow time.Time) (LeaseHeartbeat, error)

Normalize returns a validated heartbeat request with default time and lease duration applied.

func (LeaseHeartbeat) Validate 

func (h LeaseHeartbeat) Validate(path string) error

Validate reports whether the heartbeat request is internally consistent.

type LeaseRelease 

type LeaseRelease struct {
	RunID      string    `json:"run_id"`
	ClaimToken string    `json:"claim_token"`
	Reason     string    `json:"reason,omitempty"`
	Now        time.Time `json:"now"`
}

LeaseRelease captures a token-fenced release request.

func (LeaseRelease) Normalize 

func (r LeaseRelease) Normalize(defaultNow time.Time) (LeaseRelease, error)

Normalize returns a validated release request with default time applied.

func (LeaseRelease) Validate 

func (r LeaseRelease) Validate(path string) error

Validate reports whether the release request is internally consistent.

type LiveService 

type LiveService interface {
	Timeline(ctx context.Context, taskID string, query TimelineQuery, actor ActorContext) ([]TimelineItem, error)
	Stream(ctx context.Context, taskID string, query StreamQuery, actor ActorContext) (<-chan StreamEvent, error)
	Tree(ctx context.Context, taskID string, actor ActorContext) (*TreeView, error)
	RunDetail(ctx context.Context, runID string, actor ActorContext) (*RunDetailView, error)
}

LiveService exposes task-native live and run-detail reads for downstream API handlers.

type Manager 

type Manager interface {
	CreateTask(ctx context.Context, spec CreateTask, actor ActorContext) (*Task, error)
	CreateChildTask(ctx context.Context, parentTaskID string, spec CreateTask, actor ActorContext) (*Task, error)
	DeleteTask(ctx context.Context, id string, actor ActorContext) error
	UpdateTask(ctx context.Context, id string, patch Patch, actor ActorContext) (*Task, error)
	PublishTask(ctx context.Context, id string, req ExecutionRequest, actor ActorContext) (*Execution, error)
	StartTask(ctx context.Context, id string, req ExecutionRequest, actor ActorContext) (*Execution, error)
	ApproveTask(ctx context.Context, id string, req ExecutionRequest, actor ActorContext) (*Execution, error)
	RejectTask(ctx context.Context, id string, actor ActorContext) (*Task, error)
	CancelTask(ctx context.Context, id string, req CancelTask, actor ActorContext) (*Task, error)
	PauseTask(ctx context.Context, id string, req PauseTaskRequest, actor ActorContext) (*Task, error)
	ResumeTask(ctx context.Context, id string, req ResumeTaskRequest, actor ActorContext) (*Task, error)
	MarkTaskRead(ctx context.Context, id string, actor ActorContext) (TriageState, error)
	ArchiveTask(ctx context.Context, id string, actor ActorContext) (TriageState, error)
	DismissTask(ctx context.Context, id string, actor ActorContext) (TriageState, error)

	GetExecutionProfile(ctx context.Context, taskID string, actor ActorContext) (ExecutionProfile, error)
	SetExecutionProfile(
		ctx context.Context,
		taskID string,
		profile *ExecutionProfile,
		actor ActorContext,
	) (ExecutionProfile, error)
	DeleteExecutionProfile(ctx context.Context, taskID string, actor ActorContext) error

	RequestRunReview(ctx context.Context, req RunReviewRequest, actor ActorContext) (RunReview, bool, error)
	GetRunReview(ctx context.Context, reviewID string, actor ActorContext) (RunReview, error)
	RecordRunReview(ctx context.Context, req RecordRunReviewRequest, actor ActorContext) (RunReviewResult, error)
	BindRunReviewSession(
		ctx context.Context,
		req BindRunReviewSessionRequest,
		actor ActorContext,
	) (RunReviewBinding, error)
	LookupRunReviewForSession(ctx context.Context, sessionID string, actor ActorContext) (RunReviewBinding, error)
	ListRunReviews(ctx context.Context, query RunReviewQuery, actor ActorContext) ([]RunReview, error)

	AddDependency(ctx context.Context, spec AddDependency, actor ActorContext) error
	RemoveDependency(ctx context.Context, taskID string, dependsOnID string, actor ActorContext) error

	EnqueueRun(ctx context.Context, spec EnqueueRun, actor ActorContext) (*Run, error)
	ClaimNextRun(ctx context.Context, criteria ClaimCriteria, actor ActorContext) (*ClaimResult, error)
	ClaimRun(ctx context.Context, runID string, claim ClaimRun, actor ActorContext) (*Run, error)
	StartRun(ctx context.Context, runID string, req StartRun, actor ActorContext) (*Run, error)
	AttachRunSession(ctx context.Context, runID string, sessionID string, actor ActorContext) (*Run, error)
	HeartbeatRunLease(ctx context.Context, heartbeat LeaseHeartbeat, actor ActorContext) (*Run, error)
	ReleaseRunLease(ctx context.Context, release LeaseRelease, actor ActorContext) (*Run, error)
	ForceReleaseRun(ctx context.Context, runID string, release ForceReleaseRun, actor ActorContext) (*Run, error)
	ForceFailRun(ctx context.Context, runID string, failure ForceFailRun, actor ActorContext) (*Run, error)
	RetryRun(ctx context.Context, runID string, retry RetryRunRequest, actor ActorContext) (*RetryRunResult, error)
	BulkForceReleaseRuns(ctx context.Context, req BulkForceRunRequest, actor ActorContext) (BulkForceRunResult, error)
	BulkForceFailRuns(ctx context.Context, req BulkForceRunRequest, actor ActorContext) (BulkForceRunResult, error)
	CompleteRunLease(ctx context.Context, completion LeaseCompletion, actor ActorContext) (*Run, error)
	FailRunLease(ctx context.Context, failure LeaseFailure, actor ActorContext) (*Run, error)
	CompleteRun(ctx context.Context, runID string, result RunResult, actor ActorContext) (*Run, error)
	FailRun(ctx context.Context, runID string, failure RunFailure, actor ActorContext) (*Run, error)
	CancelRun(ctx context.Context, runID string, req CancelRun, actor ActorContext) (*Run, error)
	RecoverExpiredRunLeases(
		ctx context.Context,
		recovery ExpiredLeaseRecovery,
		actor ActorContext,
	) ([]ExpiredLeaseRecoveryResult, error)
	SchedulerStatus(ctx context.Context, actor ActorContext) (SchedulerStatus, error)
	PauseScheduler(ctx context.Context, req SchedulerPauseRequest, actor ActorContext) (SchedulerStatus, error)
	ResumeScheduler(ctx context.Context, req SchedulerResumeRequest, actor ActorContext) (SchedulerStatus, error)
	DrainScheduler(ctx context.Context, req SchedulerDrainRequest, actor ActorContext) (SchedulerDrainResult, error)
	SchedulerBacklog(ctx context.Context, query SchedulerBacklogQuery, actor ActorContext) (SchedulerBacklog, error)

	GetTask(ctx context.Context, id string, actor ActorContext) (*View, error)
	InspectTask(ctx context.Context, taskID string, actor ActorContext) (*InspectView, error)
	InspectRun(ctx context.Context, runID string, actor ActorContext) (*InspectView, error)
	ListTaskRuns(ctx context.Context, taskID string, query RunQuery, actor ActorContext) ([]Run, error)
	ListTasks(ctx context.Context, query Query, actor ActorContext) ([]Summary, error)

	LiveService
}

Manager is the task-domain authority for task and run lifecycle operations.

type OperatorTaskContextRequest 

type OperatorTaskContextRequest struct {
	TaskID string    `json:"task_id"`
	Now    time.Time `json:"now"`
}

OperatorTaskContextRequest identifies the task context an operator read path may request.

type Option 

type Option func(*managerOptions)

Option customizes Service construction.

func WithCancelGracePeriod 

func WithCancelGracePeriod(timeout time.Duration) Option

WithCancelGracePeriod overrides the cooperative-stop grace period used before requesting forced session termination during task-driven cancellation.

func WithEventObserver 

func WithEventObserver(observer EventObserver) Option

WithEventObserver injects a best-effort observer for immutable task events.

func WithExecutionProfileValidationOptions 

func WithExecutionProfileValidationOptions(options ExecutionProfileValidationOptions) Option

WithExecutionProfileValidationOptions injects config-backed profile gates.

func WithForceRecoveryOptions 

func WithForceRecoveryOptions(options ForceRecoveryOptions) Option

WithForceRecoveryOptions injects config-backed force-operation policy.

func WithIDGenerator 

func WithIDGenerator(newID func(prefix string) string) Option

WithIDGenerator overrides identifier generation for deterministic tests.

func WithInspectStateReader 

func WithInspectStateReader(reader InspectStateReader) Option

WithInspectStateReader injects read-only runtime state used by task inspect.

func WithManagerNow 

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

WithManagerNow overrides the manager clock for deterministic tests.

func WithNetworkChannelValidator 

func WithNetworkChannelValidator(validator func(string) error) Option

WithNetworkChannelValidator injects the active channel validator used to check task and run bindings without coupling the task package to the network runtime implementation.

func WithRunReviewRequestedObserver 

func WithRunReviewRequestedObserver(observer RunReviewRequestedObserver) Option

WithRunReviewRequestedObserver injects a best-effort observer for newly persisted run review requests.

func WithRuntimeViewReader 

func WithRuntimeViewReader(reader RuntimeViewReader) Option

WithRuntimeViewReader injects optional session telemetry enrichment for task live reads.

func WithSessionExecutor 

func WithSessionExecutor(sessions SessionExecutor) Option

WithSessionExecutor injects the runtime session bridge used by later task-run lifecycle operations.

func WithStore 

func WithStore(store Store) Option

WithStore injects the durable task-domain store consumed by the manager.

func WithTaskRunHooks 

func WithTaskRunHooks(hooks RunHookDispatcher) Option

WithTaskRunHooks injects the task-run hook bridge used at authoritative run transitions.

type Origin 

type Origin struct {
	Kind OriginKind `json:"kind"`
	Ref  string     `json:"ref"`
}

Origin is the immutable technical ingress context attached to task and run writes.

func (Origin) Validate 

func (o Origin) Validate(path string) error

Validate reports whether the origin contains a supported kind and non-empty reference.

type OriginKind 

type OriginKind string

OriginKind identifies the technical ingress surface that produced a task-domain write. 

const (
	// OriginKindCLI identifies CLI ingress.
	OriginKindCLI OriginKind = "cli"
	// OriginKindWeb identifies web UI ingress.
	OriginKindWeb OriginKind = "web"
	// OriginKindUDS identifies local UDS ingress.
	OriginKindUDS OriginKind = "uds"
	// OriginKindHTTP identifies HTTP ingress.
	OriginKindHTTP OriginKind = "http"
	// OriginKindAutomation identifies automation ingress.
	OriginKindAutomation OriginKind = "automation"
	// OriginKindExtension identifies extension ingress.
	OriginKindExtension OriginKind = "extension"
	// OriginKindNetwork identifies network ingress.
	OriginKindNetwork OriginKind = "network"
	// OriginKindAgentSession identifies session tool-call ingress.
	OriginKindAgentSession OriginKind = "agent_session"
	// OriginKindDaemon identifies daemon-owned internal ingress.
	OriginKindDaemon OriginKind = "daemon"
)

func (OriginKind) Normalize 

func (k OriginKind) Normalize() OriginKind

Normalize returns the normalized representation of the origin kind.

func (OriginKind) Validate 

func (k OriginKind) Validate(path string) error

Validate reports whether the origin kind is supported.

type OwnerKind 

type OwnerKind string

OwnerKind identifies who currently owns a task operationally. 

const (
	// OwnerKindHuman identifies a human owner.
	OwnerKindHuman OwnerKind = "human"
	// OwnerKindAgentSession identifies an agent-session owner.
	OwnerKindAgentSession OwnerKind = "agent_session"
	// OwnerKindAutomation identifies an automation owner.
	OwnerKindAutomation OwnerKind = "automation"
	// OwnerKindExtension identifies an extension owner.
	OwnerKindExtension OwnerKind = "extension"
	// OwnerKindNetworkPeer identifies a network-peer owner.
	OwnerKindNetworkPeer OwnerKind = "network_peer"
	// OwnerKindPool identifies pooled ownership without a dedicated assignee.
	OwnerKindPool OwnerKind = "pool"
)

func (OwnerKind) Normalize 

func (k OwnerKind) Normalize() OwnerKind

Normalize returns the normalized representation of the owner kind.

func (OwnerKind) Validate 

func (k OwnerKind) Validate(path string) error

Validate reports whether the owner kind is supported.

type Ownership 

type Ownership struct {
	Kind OwnerKind `json:"kind"`
	Ref  string    `json:"ref"`
}

Ownership is the optional mutable operational assignee attached to a task.

func (Ownership) IsZero 

func (o Ownership) IsZero() bool

IsZero reports whether the ownership value is empty.

func (Ownership) Validate 

func (o Ownership) Validate(path string) error

Validate reports whether the ownership value contains a supported kind and non-empty reference.

type ParticipantPolicy 

type ParticipantPolicy struct {
	AllowedChannelIDs     []string `json:"allowed_channel_ids,omitempty"`
	PreferredChannelIDs   []string `json:"preferred_channel_ids,omitempty"`
	AllowedPeerIDs        []string `json:"allowed_peer_ids,omitempty"`
	PreferredPeerIDs      []string `json:"preferred_peer_ids,omitempty"`
	AllowedAgentNames     []string `json:"allowed_agent_names,omitempty"`
	PreferredAgentNames   []string `json:"preferred_agent_names,omitempty"`
	RequiredCapabilities  []string `json:"required_capabilities,omitempty"`
	PreferredCapabilities []string `json:"preferred_capabilities,omitempty"`
}

ParticipantPolicy is an upper-bound routing policy, not a permission grant.

type Patch 

type Patch struct {
	Title          *string          `json:"title,omitempty"`
	Description    *string          `json:"description,omitempty"`
	Priority       *Priority        `json:"priority,omitempty"`
	MaxAttempts    *int             `json:"max_attempts,omitempty"`
	ApprovalPolicy *ApprovalPolicy  `json:"approval_policy,omitempty"`
	Metadata       *json.RawMessage `json:"metadata,omitempty"`
	NetworkChannel *string          `json:"network_channel,omitempty"`
	Owner          *Ownership       `json:"owner,omitempty"`
	ClearOwner     bool             `json:"clear_owner,omitempty"`
}

Patch captures the mutable task fields accepted by update operations.

func (Patch) Validate 

func (p Patch) Validate(path string) error

Validate reports whether the task patch contains at least one mutable field and valid values.

type PauseMutation 

type PauseMutation struct {
	TaskID   string    `json:"task_id"`
	Actor    string    `json:"actor"`
	Reason   string    `json:"reason"`
	PausedAt time.Time `json:"paused_at"`
}

PauseMutation captures one persisted per-task pause write.

type PauseState 

type PauseState struct {
	TaskID          string    `json:"task_id"`
	Paused          bool      `json:"paused"`
	PausedBy        string    `json:"paused_by,omitempty"`
	PausedAt        time.Time `json:"paused_at,omitzero"`
	PausedReason    string    `json:"paused_reason,omitempty"`
	EffectivePaused bool      `json:"effective_paused"`
	PausedByTaskID  string    `json:"paused_by_task_id,omitempty"`
}

PauseState reports direct and inherited pause state for one task.

type PauseTaskRequest 

type PauseTaskRequest struct {
	Reason   string          `json:"reason"`
	Metadata json.RawMessage `json:"metadata,omitempty"`
}

PauseTaskRequest captures one per-task pause request.

type Priority 

type Priority string

Priority identifies the operator-facing urgency assigned to one task. 

const (
	// PriorityLow identifies the lowest urgency.
	PriorityLow Priority = "low"
	// PriorityMedium identifies the default urgency.
	PriorityMedium Priority = "medium"
	// PriorityHigh identifies elevated urgency.
	PriorityHigh Priority = "high"
	// PriorityUrgent identifies the highest urgency.
	PriorityUrgent Priority = "urgent"
	// DefaultPriority is the canonical priority used when callers omit the field.
	DefaultPriority Priority = PriorityMedium
)

func (Priority) Normalize 

func (p Priority) Normalize() Priority

Normalize returns the normalized representation of the task priority.

func (Priority) Validate 

func (p Priority) Validate(path string) error

Validate reports whether the task priority is one of the supported values.

type Query 

type Query struct {
	Scope          Scope         `json:"scope,omitempty"`
	WorkspaceID    string        `json:"workspace_id,omitempty"`
	Status         Status        `json:"status,omitempty"`
	Priority       Priority      `json:"priority,omitempty"`
	ApprovalState  ApprovalState `json:"approval_state,omitempty"`
	OwnerKind      OwnerKind     `json:"owner_kind,omitempty"`
	OwnerRef       string        `json:"owner_ref,omitempty"`
	ParentTaskID   string        `json:"parent_task_id,omitempty"`
	NetworkChannel string        `json:"network_channel,omitempty"`
	Search         string        `json:"search,omitempty"`
	Limit          int           `json:"limit,omitempty"`
}

Query captures the supported list filters for task reads.

func (Query) Validate 

func (q Query) Validate(path string) error

Validate reports whether the task-query filters are internally consistent.

type RecordRunReviewRequest 

type RecordRunReviewRequest struct {
	ReviewID string           `json:"review_id"`
	RunID    string           `json:"run_id"`
	Verdict  RunReviewVerdict `json:"verdict"`
}

RecordRunReviewRequest captures an authoritative persisted review verdict write.

func (RecordRunReviewRequest) Normalize 

func (r RecordRunReviewRequest) Normalize() RecordRunReviewRequest

Normalize returns a canonical verdict-recording request.

func (RecordRunReviewRequest) Validate 

func (r RecordRunReviewRequest) Validate(path string) error

Validate reports whether the verdict-recording request can identify a review and run.

type RecordStore 

type RecordStore interface {
	CreateTask(ctx context.Context, task Task) error
	DeleteTask(ctx context.Context, id string) error
	UpdateTask(ctx context.Context, task Task) error
	GetTask(ctx context.Context, id string) (Task, error)
	ListTasks(ctx context.Context, query Query) ([]Summary, error)
	CountDirectChildren(ctx context.Context, parentTaskID string) (int, error)
}

RecordStore is the persistence surface for durable task records.

type Reference 

type Reference struct {
	ID              string     `json:"id"`
	Identifier      string     `json:"identifier,omitempty"`
	Title           string     `json:"title"`
	Status          Status     `json:"status"`
	Priority        Priority   `json:"priority,omitempty"`
	Owner           *Ownership `json:"owner,omitempty"`
	Scope           Scope      `json:"scope"`
	WorkspaceID     string     `json:"workspace_id,omitempty"`
	LatestEventSeq  int64      `json:"latest_event_seq"`
	Paused          bool       `json:"paused,omitempty"`
	EffectivePaused bool       `json:"effective_paused,omitempty"`
	PausedByTaskID  string     `json:"paused_by_task_id,omitempty"`
}

Reference is the human-meaningful task identity used in enriched read models.

type ResumeMutation 

type ResumeMutation struct {
	TaskID    string    `json:"task_id"`
	ResumedAt time.Time `json:"resumed_at"`
}

ResumeMutation captures one persisted per-task resume write.

type ResumeTaskRequest 

type ResumeTaskRequest struct {
	Metadata json.RawMessage `json:"metadata,omitempty"`
}

ResumeTaskRequest captures one per-task resume request.

type RetryRunMutation 

type RetryRunMutation struct {
	SourceRunID string          `json:"source_run_id"`
	NewRunID    string          `json:"new_run_id"`
	Origin      Origin          `json:"origin"`
	Metadata    json.RawMessage `json:"metadata,omitempty"`
	QueuedAt    time.Time       `json:"queued_at"`
}

RetryRunMutation captures one transactional retry write.

type RetryRunRequest 

type RetryRunRequest struct {
	Metadata json.RawMessage `json:"metadata,omitempty"`
}

RetryRunRequest captures one operator/agent retry request.

type RetryRunResult 

type RetryRunResult struct {
	PreviousRun Run `json:"previous_run"`
	Run         Run `json:"run"`
}

RetryRunResult records the source terminal run and the newly queued retry.

type ReviewContinuation 

type ReviewContinuation struct {
	ReviewID          string   `json:"review_id"`
	ReviewedRunID     string   `json:"reviewed_run_id"`
	ReviewRound       int      `json:"review_round"`
	Outcome           string   `json:"outcome"`
	Reason            string   `json:"reason"`
	MissingWork       []string `json:"missing_work"`
	NextRoundGuidance string   `json:"next_round_guidance"`
}

ReviewContinuation is the rejected-review guidance that produced a continuation run.

type ReviewPolicy 

type ReviewPolicy string

ReviewPolicy identifies when a terminal task run needs a review gate. 

const (
	// ReviewPolicyNone disables review gating.
	ReviewPolicyNone ReviewPolicy = "none"
	// ReviewPolicyOnSuccess requests review only after a successful run.
	ReviewPolicyOnSuccess ReviewPolicy = "on_success"
	// ReviewPolicyOnFailure requests review only after a failed or canceled run.
	ReviewPolicyOnFailure ReviewPolicy = "on_failure"
	// ReviewPolicyAlways requests review after every terminal run.
	ReviewPolicyAlways ReviewPolicy = "always"
)

func (ReviewPolicy) MatchesRunStatus 

func (p ReviewPolicy) MatchesRunStatus(status RunStatus) bool

MatchesRunStatus reports whether this policy applies to a terminal run status.

func (ReviewPolicy) Normalize 

func (p ReviewPolicy) Normalize() ReviewPolicy

Normalize returns the normalized review policy value.

func (ReviewPolicy) Validate 

func (p ReviewPolicy) Validate(path string) error

Validate reports whether the review policy is one of the supported values.

type ReviewProfile 

type ReviewProfile struct {
	AgentName             string   `json:"agent_name,omitempty"`
	Provider              string   `json:"provider,omitempty"`
	Model                 string   `json:"model,omitempty"`
	AllowedAgentNames     []string `json:"allowed_agent_names,omitempty"`
	PreferredAgentNames   []string `json:"preferred_agent_names,omitempty"`
	AllowedChannelIDs     []string `json:"allowed_channel_ids,omitempty"`
	PreferredChannelIDs   []string `json:"preferred_channel_ids,omitempty"`
	AllowedPeerIDs        []string `json:"allowed_peer_ids,omitempty"`
	PreferredPeerIDs      []string `json:"preferred_peer_ids,omitempty"`
	RequiredCapabilities  []string `json:"required_capabilities,omitempty"`
	PreferredCapabilities []string `json:"preferred_capabilities,omitempty"`
}

ReviewProfile narrows reviewer execution shape; verdict authority stays in task review APIs.

type Run 

type Run struct {
	ID                    string            `json:"id"`
	TaskID                string            `json:"task_id"`
	Status                RunStatus         `json:"status"`
	Attempt               int               `json:"attempt"`
	PreviousRunID         string            `json:"previous_run_id,omitempty"`
	FailureKind           string            `json:"failure_kind,omitempty"`
	ClaimedBy             *ActorIdentity    `json:"claimed_by,omitempty"`
	SessionID             string            `json:"session_id,omitempty"`
	Origin                Origin            `json:"origin"`
	IdempotencyKey        string            `json:"idempotency_key,omitempty"`
	NetworkChannel        string            `json:"network_channel,omitempty"`
	ClaimToken            string            `json:"-"`
	ClaimTokenHash        string            `json:"claim_token_hash,omitempty"`
	LeaseUntil            time.Time         `json:"lease_until"`
	HeartbeatAt           time.Time         `json:"heartbeat_at"`
	CoordinationChannelID string            `json:"coordination_channel_id,omitempty"`
	RequiredCapabilities  []string          `json:"required_capabilities,omitempty"`
	PreferredCapabilities []string          `json:"preferred_capabilities,omitempty"`
	Review                *RunReviewLineage `json:"review,omitempty"`
	Metadata              json.RawMessage   `json:"metadata,omitempty"`
	QueuedAt              time.Time         `json:"queued_at"`
	ClaimedAt             time.Time         `json:"claimed_at"`
	StartedAt             time.Time         `json:"started_at"`
	EndedAt               time.Time         `json:"ended_at"`
	Error                 string            `json:"error,omitempty"`
	Result                json.RawMessage   `json:"result,omitempty"`
}

Run is the durable execution record for one task attempt.

func (Run) Validate 

func (r Run) Validate() error

Validate reports whether the task-run record contains the canonical persisted shape.

type RunBootRecovery 

type RunBootRecovery struct {
	Action         RunBootRecoveryAction `json:"action"`
	Reason         string                `json:"reason,omitempty"`
	SessionState   string                `json:"session_state,omitempty"`
	Classification string                `json:"classification,omitempty"`
	Detail         string                `json:"detail,omitempty"`
}

RunBootRecovery captures one daemon-owned recovery decision for an in-flight run discovered during boot reconciliation.

func (RunBootRecovery) Validate 

func (r RunBootRecovery) Validate(path string) error

Validate reports whether the boot-recovery request contains one supported recovery action.

type RunBootRecoveryAction 

type RunBootRecoveryAction string

RunBootRecoveryAction identifies the manager-owned recovery action applied to a non-terminal run during daemon startup reconciliation. 

const (
	// RunBootRecoveryRequeue resets one claimed run back to the durable queue.
	RunBootRecoveryRequeue RunBootRecoveryAction = "requeue"
	// RunBootRecoveryMarkRunning promotes one live attached run into running.
	RunBootRecoveryMarkRunning RunBootRecoveryAction = "mark_running"
	// RunBootRecoveryFail marks one orphaned attached run as failed.
	RunBootRecoveryFail RunBootRecoveryAction = "fail"
)

func (RunBootRecoveryAction) Normalize 

func (a RunBootRecoveryAction) Normalize() RunBootRecoveryAction

Normalize returns the normalized representation of the boot-recovery action.

func (RunBootRecoveryAction) Validate 

func (a RunBootRecoveryAction) Validate(path string) error

Validate reports whether the boot-recovery action is supported.

type RunDetailView 

type RunDetailView struct {
	Run     Run                   `json:"run"`
	Task    Reference             `json:"task"`
	Session *RunSessionRef        `json:"session,omitempty"`
	Summary RunOperationalSummary `json:"summary"`
}

RunDetailView is the task-owned run detail payload for task run deep links.

type RunFailure 

type RunFailure struct {
	Error    string          `json:"error"`
	Metadata json.RawMessage `json:"metadata,omitempty"`
}

RunFailure captures the durable failure payload returned by a failed run.

func (RunFailure) Validate 

func (r RunFailure) Validate(path string) error

Validate reports whether the run failure contains a message and bounded metadata.

type RunHookDispatcher 

type RunHookDispatcher interface {
	DispatchTaskRunEnqueued(
		context.Context,
		hookspkg.TaskRunEnqueuedPayload,
	) (hookspkg.TaskRunEnqueuedPayload, error)
	DispatchTaskRunPreClaim(
		context.Context,
		hookspkg.TaskRunPreClaimPayload,
	) (hookspkg.TaskRunPreClaimPayload, error)
	DispatchTaskRunPostClaim(
		context.Context,
		hookspkg.TaskRunPostClaimPayload,
	) (hookspkg.TaskRunPostClaimPayload, error)
	DispatchTaskRunLeaseExtended(
		context.Context,
		hookspkg.TaskRunLeaseExtendedPayload,
	) (hookspkg.TaskRunLeaseExtendedPayload, error)
	DispatchTaskRunLeaseExpired(
		context.Context,
		hookspkg.TaskRunLeaseExpiredPayload,
	) (hookspkg.TaskRunLeaseExpiredPayload, error)
	DispatchTaskRunLeaseRecovered(
		context.Context,
		hookspkg.TaskRunLeaseRecoveredPayload,
	) (hookspkg.TaskRunLeaseRecoveredPayload, error)
	DispatchTaskRunReleased(
		context.Context,
		hookspkg.TaskRunReleasedPayload,
	) (hookspkg.TaskRunReleasedPayload, error)
	DispatchTaskRunCompleted(
		context.Context,
		hookspkg.TaskRunCompletedPayload,
	) (hookspkg.TaskRunCompletedPayload, error)
	DispatchTaskRunFailed(
		context.Context,
		hookspkg.TaskRunFailedPayload,
	) (hookspkg.TaskRunFailedPayload, error)
}

RunHookDispatcher is the narrow hook bridge consumed by task-run transitions.

type RunIdempotency 

type RunIdempotency struct {
	IdempotencyKey string    `json:"idempotency_key"`
	RunID          string    `json:"run_id"`
	Origin         Origin    `json:"origin"`
	CreatedAt      time.Time `json:"created_at"`
}

RunIdempotency is the durable deduplication record for non-human run ingress.

func (RunIdempotency) Validate 

func (r RunIdempotency) Validate() error

Validate reports whether the persisted idempotency record contains the canonical shape.

type RunOperationalSummary 

type RunOperationalSummary struct {
	LastActivityAt time.Time `json:"last_activity_at"`
	LastEventType  string    `json:"last_event_type,omitempty"`
	ToolCallCount  *int64    `json:"tool_call_count,omitempty"`
	TurnCount      *int64    `json:"turn_count,omitempty"`
	InputTokens    *int64    `json:"input_tokens,omitempty"`
	OutputTokens   *int64    `json:"output_tokens,omitempty"`
	TotalTokens    *int64    `json:"total_tokens,omitempty"`
	TotalCost      *float64  `json:"total_cost,omitempty"`
	CostCurrency   *string   `json:"cost_currency,omitempty"`
}

RunOperationalSummary captures run-detail metrics aggregated from runtime data when available.

type RunQuery 

type RunQuery struct {
	TaskID                string    `json:"task_id,omitempty"`
	Status                RunStatus `json:"status,omitempty"`
	SessionID             string    `json:"session_id,omitempty"`
	CoordinationChannelID string    `json:"coordination_channel_id,omitempty"`
	Limit                 int       `json:"limit,omitempty"`
}

RunQuery captures the supported list filters for task-run reads.

func (RunQuery) Validate 

func (q RunQuery) Validate(path string) error

Validate reports whether the task-run query filters are internally consistent.

type RunResult 

type RunResult struct {
	Value json.RawMessage `json:"value,omitempty"`
}

RunResult captures the durable JSON result returned by a completed run.

func (RunResult) Validate 

func (r RunResult) Validate(path string) error

Validate reports whether the run result respects the shared result-size guardrail.

type RunReview 

type RunReview struct {
	ReviewID          string           `json:"review_id"`
	TaskID            string           `json:"task_id"`
	RunID             string           `json:"run_id"`
	ParentReviewID    string           `json:"parent_review_id,omitempty"`
	Policy            ReviewPolicy     `json:"policy"`
	ReviewRound       int              `json:"review_round"`
	Attempt           int              `json:"attempt"`
	Status            RunReviewStatus  `json:"status"`
	Outcome           RunReviewOutcome `json:"outcome,omitempty"`
	Confidence        *float64         `json:"confidence,omitempty"`
	Reason            string           `json:"reason,omitempty"`
	DeliveryID        string           `json:"delivery_id,omitempty"`
	MissingWork       json.RawMessage  `json:"missing_work,omitempty"`
	NextRoundGuidance string           `json:"next_round_guidance,omitempty"`
	ReviewText        string           `json:"review_text,omitempty"`
	ReviewerSessionID string           `json:"reviewer_session_id,omitempty"`
	ReviewerAgentName string           `json:"reviewer_agent_name,omitempty"`
	ReviewerPeerID    string           `json:"reviewer_peer_id,omitempty"`
	ReviewerChannelID string           `json:"reviewer_channel_id,omitempty"`
	ReviewedBy        *ActorIdentity   `json:"reviewed_by,omitempty"`
	RequestedAt       time.Time        `json:"requested_at"`
	RoutedAt          time.Time        `json:"routed_at"`
	StartedAt         time.Time        `json:"started_at"`
	ReviewedAt        time.Time        `json:"reviewed_at"`
	DeadlineAt        time.Time        `json:"deadline_at"`
	CreatedAt         time.Time        `json:"created_at"`
	UpdatedAt         time.Time        `json:"updated_at"`
}

RunReview is the task-domain record for one post-terminal review gate.

func (*RunReview) Normalize 

func (r *RunReview) Normalize(now time.Time) (RunReview, error)

Normalize returns a canonical review record.

func (*RunReview) Validate 

func (r *RunReview) Validate() error

Validate reports whether the run-review record can be persisted.

type RunReviewBinding 

type RunReviewBinding struct {
	Review            RunReview `json:"review"`
	SessionID         string    `json:"session_id"`
	ReviewerAgentName string    `json:"reviewer_agent_name,omitempty"`
	ReviewerPeerID    string    `json:"reviewer_peer_id,omitempty"`
	ReviewerChannelID string    `json:"reviewer_channel_id,omitempty"`
}

RunReviewBinding is the lookup shape consumed by reviewer-session tooling.

type RunReviewLineage 

type RunReviewLineage struct {
	Required           bool            `json:"required,omitempty"`
	RequestRound       int             `json:"request_round,omitempty"`
	PolicySnapshot     ReviewPolicy    `json:"policy_snapshot,omitempty"`
	RequestID          string          `json:"request_id,omitempty"`
	ParentRunID        string          `json:"parent_run_id,omitempty"`
	ReviewID           string          `json:"review_id,omitempty"`
	ReviewRound        int             `json:"review_round,omitempty"`
	ContinuationReason string          `json:"continuation_reason,omitempty"`
	MissingWork        json.RawMessage `json:"missing_work,omitempty"`
	NextRoundGuidance  string          `json:"next_round_guidance,omitempty"`
}

RunReviewLineage captures review-gate fields attached to a task run.

type RunReviewOutcome 

type RunReviewOutcome string

RunReviewOutcome identifies the authoritative reviewer verdict. 

const (
	// RunReviewOutcomeApproved accepts the run result.
	RunReviewOutcomeApproved RunReviewOutcome = "approved"
	// RunReviewOutcomeRejected rejects the run and may request continuation work.
	RunReviewOutcomeRejected RunReviewOutcome = "rejected"
	// RunReviewOutcomeBlocked reports the review could not continue due to external blockers.
	RunReviewOutcomeBlocked RunReviewOutcome = "blocked"
	// RunReviewOutcomeError reports reviewer/tool execution failed.
	RunReviewOutcomeError RunReviewOutcome = "error"
	// RunReviewOutcomeTimeout reports the review exceeded its deadline.
	RunReviewOutcomeTimeout RunReviewOutcome = "timeout"
	// RunReviewOutcomeInvalidOutput reports the reviewer returned a malformed verdict.
	RunReviewOutcomeInvalidOutput RunReviewOutcome = "invalid_output"
)

func (RunReviewOutcome) Normalize 

func (o RunReviewOutcome) Normalize() RunReviewOutcome

Normalize returns the normalized run-review outcome.

func (RunReviewOutcome) Validate 

func (o RunReviewOutcome) Validate(path string) error

Validate reports whether the run-review outcome is supported.

type RunReviewQuery 

type RunReviewQuery struct {
	TaskID            string          `json:"task_id,omitempty"`
	RunID             string          `json:"run_id,omitempty"`
	Status            RunReviewStatus `json:"status,omitempty"`
	ReviewerSessionID string          `json:"reviewer_session_id,omitempty"`
	Limit             int             `json:"limit,omitempty"`
}

RunReviewQuery captures supported review read filters.

func (RunReviewQuery) Validate 

func (q RunReviewQuery) Validate(path string) error

Validate reports whether review query filters are internally consistent.

type RunReviewRequest 

type RunReviewRequest struct {
	TaskID         string       `json:"task_id"`
	RunID          string       `json:"run_id"`
	ReviewRound    int          `json:"review_round,omitempty"`
	Attempt        int          `json:"attempt,omitempty"`
	Policy         ReviewPolicy `json:"policy,omitempty"`
	ParentReviewID string       `json:"parent_review_id,omitempty"`
	Reason         string       `json:"reason,omitempty"`
	DeadlineAt     time.Time    `json:"deadline_at"`
}

RunReviewRequest captures one authoritative request to review a terminal run.

func (RunReviewRequest) Normalize 

func (r RunReviewRequest) Normalize() RunReviewRequest

Normalize returns a canonical review request.

func (RunReviewRequest) Validate 

func (r RunReviewRequest) Validate(path string) error

Validate reports whether the review request has enough data for a persisted request row.

type RunReviewRequestedNotification 

type RunReviewRequestedNotification struct {
	Review RunReview
	Task   Task
	Run    Run
	Actor  ActorContext
}

RunReviewRequestedNotification is emitted after one review request is durably created and its audit event has been recorded.

type RunReviewRequestedObserver 

type RunReviewRequestedObserver interface {
	OnRunReviewRequested(ctx context.Context, notification *RunReviewRequestedNotification)
}

RunReviewRequestedObserver receives typed review-request wakeups without tailing task events or storage tables.

type RunReviewResult 

type RunReviewResult struct {
	Review          RunReview `json:"review"`
	ContinuationRun *Run      `json:"continuation_run,omitempty"`
	CircuitOpened   bool      `json:"circuit_opened,omitempty"`
}

RunReviewResult reports the stored verdict and optional rejected-review continuation run.

type RunReviewStatus 

type RunReviewStatus string

RunReviewStatus identifies the lifecycle state of one run review request. 

const (
	// RunReviewStatusRequested reports a persisted review request awaiting routing.
	RunReviewStatusRequested RunReviewStatus = "requested"
	// RunReviewStatusRouted reports a review that has been routed but not yet bound.
	RunReviewStatusRouted RunReviewStatus = "routed"
	// RunReviewStatusInReview reports a review bound to a reviewer session.
	RunReviewStatusInReview RunReviewStatus = "in_review"
	// RunReviewStatusRecorded reports a persisted terminal reviewer verdict.
	RunReviewStatusRecorded RunReviewStatus = "recorded"
	// RunReviewStatusCircuitOpened reports review routing stopped by circuit policy.
	RunReviewStatusCircuitOpened RunReviewStatus = "circuit_opened"
	// RunReviewStatusCanceled reports an explicitly canceled review request.
	RunReviewStatusCanceled RunReviewStatus = "canceled"
)

func (RunReviewStatus) Normalize 

func (s RunReviewStatus) Normalize() RunReviewStatus

Normalize returns the normalized run-review status.

func (RunReviewStatus) Validate 

func (s RunReviewStatus) Validate(path string) error

Validate reports whether the run-review status is supported.

type RunReviewStore 

type RunReviewStore interface {
	RequestRunReview(ctx context.Context, review *RunReview) (RunReview, bool, error)
	GetRunReview(ctx context.Context, reviewID string) (RunReview, error)
	RecordRunReview(
		ctx context.Context,
		req RecordRunReviewRequest,
		actor ActorContext,
		recordedAt time.Time,
		continuationRunID string,
	) (RunReviewResult, error)
	BindRunReviewSession(ctx context.Context, req BindRunReviewSessionRequest, boundAt time.Time) (RunReview, error)
	LookupRunReviewBySession(ctx context.Context, sessionID string) (RunReview, error)
	ListRunReviews(ctx context.Context, query RunReviewQuery) ([]RunReview, error)
}

RunReviewStore is the persistence surface for task-run review gate records.

type RunReviewSummary 

type RunReviewSummary struct {
	ReviewID      string `json:"review_id"`
	RunID         string `json:"run_id"`
	ReviewRound   int    `json:"review_round"`
	Attempt       int    `json:"attempt"`
	Status        string `json:"status"`
	Outcome       string `json:"outcome,omitempty"`
	Reason        string `json:"reason,omitempty"`
	ReviewedAt    string `json:"reviewed_at,omitempty"`
	ReviewerLabel string `json:"reviewer_label,omitempty"`
}

RunReviewSummary is the redacted review history shape included in task context.

type RunReviewVerdict 

type RunReviewVerdict struct {
	Outcome           RunReviewOutcome `json:"outcome"`
	Confidence        *float64         `json:"confidence"`
	Reason            string           `json:"reason"`
	DeliveryID        string           `json:"delivery_id"`
	MissingWork       json.RawMessage  `json:"missing_work,omitempty"`
	NextRoundGuidance string           `json:"next_round_guidance,omitempty"`
	ReviewText        string           `json:"review_text,omitempty"`
}

RunReviewVerdict captures the terminal reviewer payload persisted by the task domain.

func (RunReviewVerdict) Normalize 

func (v RunReviewVerdict) Normalize() RunReviewVerdict

Normalize returns a canonical verdict payload.

func (RunReviewVerdict) Validate 

func (v RunReviewVerdict) Validate(path string) error

Validate reports whether the verdict can be persisted as an authoritative reviewer decision.

type RunSessionRef 

type RunSessionRef struct {
	SessionID   string    `json:"session_id"`
	WorkspaceID string    `json:"workspace_id,omitempty"`
	AgentName   string    `json:"agent_name,omitempty"`
	Name        string    `json:"name,omitempty"`
	Channel     string    `json:"channel,omitempty"`
	State       string    `json:"state,omitempty"`
	CreatedAt   time.Time `json:"created_at"`
	UpdatedAt   time.Time `json:"updated_at"`
}

RunSessionRef links one run to its backing session when available.

type RunStatus 

type RunStatus string

RunStatus identifies the canonical lifecycle state of a task run. 

const (
	// TaskRunStatusQueued reports a run that has been accepted but not yet claimed.
	TaskRunStatusQueued RunStatus = "queued"
	// TaskRunStatusClaimed reports a run that has been claimed for execution.
	TaskRunStatusClaimed RunStatus = "claimed"
	// TaskRunStatusStarting reports a run that is starting its execution session.
	TaskRunStatusStarting RunStatus = "starting"
	// TaskRunStatusRunning reports a run that is actively executing.
	TaskRunStatusRunning RunStatus = "running"
	// TaskRunStatusCompleted reports a run that finished successfully.
	TaskRunStatusCompleted RunStatus = "completed"
	// TaskRunStatusFailed reports a run that finished with an error.
	TaskRunStatusFailed RunStatus = "failed"
	// TaskRunStatusCanceled reports a run that was canceled.
	TaskRunStatusCanceled RunStatus = "canceled"
)

func (RunStatus) Normalize 

func (s RunStatus) Normalize() RunStatus

Normalize returns the normalized representation of the task-run status.

func (RunStatus) Validate 

func (s RunStatus) Validate(path string) error

Validate reports whether the task-run status is one of the supported lifecycle states.

type RunStore 

type RunStore interface {
	CreateTaskRun(ctx context.Context, run Run) error
	UpdateTaskRun(ctx context.Context, run Run) error
	GetTaskRun(ctx context.Context, id string) (Run, error)
	ListTaskRuns(ctx context.Context, query RunQuery) ([]Run, error)
	ListTaskRunsByStatus(ctx context.Context, statuses []RunStatus) ([]Run, error)
	CountActiveSessionBindings(ctx context.Context, sessionID string) (int, error)
	ClaimNextRun(ctx context.Context, criteria ClaimCriteria) (ClaimResult, error)
	HeartbeatRunLease(ctx context.Context, heartbeat LeaseHeartbeat) (Run, error)
	ReleaseRunLease(ctx context.Context, release LeaseRelease) (Run, error)
	CompleteRunLease(ctx context.Context, completion LeaseCompletion) (Run, error)
	FailRunLease(ctx context.Context, failure LeaseFailure) (Run, error)
	ForceReleaseTaskRun(ctx context.Context, release ForceReleaseRunMutation) (ForceRunMutationResult, error)
	ForceFailTaskRun(ctx context.Context, failure ForceFailRunMutation) (ForceRunMutationResult, error)
	RetryTaskRun(ctx context.Context, retry RetryRunMutation) (RetryRunResult, error)
	RecoverExpiredRunLeases(ctx context.Context, recovery ExpiredLeaseRecovery) ([]ExpiredLeaseRecoveryResult, error)
	ReserveQueuedRun(
		ctx context.Context,
		taskID string,
		runID string,
		idempotencyKey string,
		origin Origin,
		requestedChannel string,
		metadata json.RawMessage,
		queuedAt time.Time,
	) (Task, Run, bool, error)
}

RunStore is the persistence surface for durable task-run records.

type RunSummary 

type RunSummary struct {
	ID                    string         `json:"id"`
	TaskID                string         `json:"task_id"`
	Status                RunStatus      `json:"status"`
	Attempt               int            `json:"attempt"`
	PreviousRunID         string         `json:"previous_run_id,omitempty"`
	FailureKind           string         `json:"failure_kind,omitempty"`
	MaxAttempts           int            `json:"max_attempts"`
	SessionID             string         `json:"session_id,omitempty"`
	ClaimedBy             *ActorIdentity `json:"claimed_by,omitempty"`
	ClaimTokenHash        string         `json:"claim_token_hash,omitempty"`
	LeaseUntil            time.Time      `json:"lease_until"`
	HeartbeatAt           time.Time      `json:"heartbeat_at"`
	CoordinationChannelID string         `json:"coordination_channel_id,omitempty"`
	QueuedAt              time.Time      `json:"queued_at"`
	ClaimedAt             time.Time      `json:"claimed_at"`
	StartedAt             time.Time      `json:"started_at"`
	EndedAt               time.Time      `json:"ended_at"`
	Error                 string         `json:"error,omitempty"`
}

RunSummary captures the operator-facing run chip data used by enriched task cards.

type RuntimeLimits 

type RuntimeLimits struct {
	MaxRuntimeSeconds int64 `json:"max_runtime_seconds"`
	SummaryMaxBytes   int   `json:"summary_max_bytes"`
	ContextMaxBytes   int   `json:"context_body_max_bytes"`
}

RuntimeLimits reports the runtime limits relevant to one task context bundle.

type RuntimeViewReader 

type RuntimeViewReader interface {
	GetSession(ctx context.Context, sessionID string) (*RunSessionRef, error)
	ListSessionEvents(ctx context.Context, sessionID string, query store.EventQuery) ([]store.SessionEvent, error)
	ListSessionTokenStats(ctx context.Context, sessionID string) ([]store.TokenStats, error)
}

RuntimeViewReader enriches run-detail reads with session and usage telemetry when available.

type SandboxMode 

type SandboxMode string

SandboxMode identifies task-level sandbox selection behavior.

func (SandboxMode) Normalize 

func (m SandboxMode) Normalize() SandboxMode

Normalize returns the normalized sandbox mode.

type SandboxPolicy 

type SandboxPolicy struct {
	Mode       SandboxMode `json:"mode"`
	SandboxRef string      `json:"sandbox_ref,omitempty"`
}

SandboxPolicy selects task-level sandbox behavior at session start.

type SchedulerBacklog 

type SchedulerBacklog struct {
	Runs  []SchedulerBacklogRun `json:"runs"`
	Total int                   `json:"total"`
}

SchedulerBacklog reports queued scheduler backlog rows and the unbounded total.

type SchedulerBacklogQuery 

type SchedulerBacklogQuery struct {
	Limit         int    `json:"limit,omitempty"`
	WorkspaceID   string `json:"workspace_id,omitempty"`
	IncludePaused bool   `json:"include_paused,omitempty"`
}

SchedulerBacklogQuery captures read filters for queued scheduler backlog.

type SchedulerBacklogRun 

type SchedulerBacklogRun struct {
	Task            Task   `json:"task"`
	Run             Run    `json:"run"`
	EffectivePaused bool   `json:"effective_paused"`
	PausedByTaskID  string `json:"paused_by_task_id,omitempty"`
}

SchedulerBacklogRun joins one queued run with the task that owns it.

type SchedulerDrainRequest 

type SchedulerDrainRequest struct {
	Reason  string        `json:"reason,omitempty"`
	Timeout time.Duration `json:"timeout,omitempty"`
}

SchedulerDrainRequest captures one drain invocation.

type SchedulerDrainResult 

type SchedulerDrainResult struct {
	Status          SchedulerStatus `json:"status"`
	Completed       bool            `json:"completed"`
	TimedOut        bool            `json:"timed_out,omitempty"`
	RemainingClaims int             `json:"remaining_claims"`
	StartedAt       time.Time       `json:"started_at"`
	CompletedAt     time.Time       `json:"completed_at"`
}

SchedulerDrainResult reports the final state observed by one drain invocation.

type SchedulerPauseMutation 

type SchedulerPauseMutation struct {
	Paused    bool      `json:"paused"`
	Actor     string    `json:"actor,omitempty"`
	Reason    string    `json:"reason,omitempty"`
	UpdatedAt time.Time `json:"updated_at"`
}

SchedulerPauseMutation captures one scheduler-wide pause-state write.

type SchedulerPauseRequest 

type SchedulerPauseRequest struct {
	Reason string `json:"reason,omitempty"`
}

SchedulerPauseRequest captures one scheduler-wide pause request.

type SchedulerPauseState 

type SchedulerPauseState struct {
	Paused    bool      `json:"paused"`
	PausedBy  string    `json:"paused_by,omitempty"`
	PausedAt  time.Time `json:"paused_at,omitzero"`
	Reason    string    `json:"reason,omitempty"`
	UpdatedAt time.Time `json:"updated_at,omitzero"`
}

SchedulerPauseState records the singleton scheduler-wide pause state.

type SchedulerResumeRequest 

type SchedulerResumeRequest struct {
	Reason string `json:"reason,omitempty"`
}

SchedulerResumeRequest captures one scheduler-wide resume request.

type SchedulerStatus 

type SchedulerStatus struct {
	Paused           bool      `json:"paused"`
	PausedBy         string    `json:"paused_by,omitempty"`
	PausedAt         time.Time `json:"paused_at,omitzero"`
	PausedReason     string    `json:"paused_reason,omitempty"`
	ActiveClaimCount int       `json:"active_claim_count"`
	QueuedRunCount   int       `json:"queued_run_count"`
	PausedTaskCount  int       `json:"paused_task_count"`
	AsOf             time.Time `json:"as_of"`
}

SchedulerStatus reports scheduler-wide pause state and live backlog counts.

type Scope 

type Scope string

Scope identifies whether a task is daemon-global or workspace-scoped. 

const (
	// ScopeGlobal identifies a daemon-wide task with no workspace binding.
	ScopeGlobal Scope = "global"
	// ScopeWorkspace identifies a task bound to one workspace.
	ScopeWorkspace Scope = "workspace"
)

func (Scope) Normalize 

func (s Scope) Normalize() Scope

Normalize returns the normalized representation of the scope.

func (Scope) Validate 

func (s Scope) Validate(path string) error

Validate reports whether the scope is one of the supported task scope values.

type Service 

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

Service centralizes canonical task-domain creation, mutation, read, and graph-management rules above the persistence layer.

func NewManager 

func NewManager(opts ...Option) (*Service, error)

NewManager constructs one task-domain manager with the supplied dependencies.

func (*Service) AddDependency 

func (m *Service) AddDependency(ctx context.Context, spec AddDependency, actor ActorContext) error

AddDependency adds one dependency edge through the manager, reconciles the task status, and records the canonical audit event.

func (*Service) ApproveTask 

func (m *Service) ApproveTask(
	ctx context.Context,
	id string,
	req ExecutionRequest,
	actor ActorContext,
) (*Execution, error)

ApproveTask records one approval decision for a manual-approval task that is currently awaiting a decision, then enqueues the approved run.

func (*Service) ArchiveTask 

func (m *Service) ArchiveTask(ctx context.Context, id string, actor ActorContext) (TriageState, error)

ArchiveTask persists the current actor-scoped triage state as archived for the task's latest known activity snapshot.

func (*Service) AttachRunSession 

func (m *Service) AttachRunSession(
	ctx context.Context,
	runID string,
	sessionID string,
	actor ActorContext,
) (*Run, error)

AttachRunSession binds one existing session to a claimed or starting run.

func (*Service) BindRunReviewSession 

func (m *Service) BindRunReviewSession(
	ctx context.Context,
	req BindRunReviewSessionRequest,
	actor ActorContext,
) (RunReviewBinding, error)

BindRunReviewSession binds one persisted review request to a reviewer session.

func (*Service) BulkForceFailRuns 

func (m *Service) BulkForceFailRuns(
	ctx context.Context,
	req BulkForceRunRequest,
	actor ActorContext,
) (BulkForceRunResult, error)

BulkForceFailRuns applies forced failure one row at a time to preserve per-row preconditions.

func (*Service) BulkForceReleaseRuns 

func (m *Service) BulkForceReleaseRuns(
	ctx context.Context,
	req BulkForceRunRequest,
	actor ActorContext,
) (BulkForceRunResult, error)

BulkForceReleaseRuns applies force release one row at a time to preserve per-row preconditions.

func (*Service) CancelRun 

func (m *Service) CancelRun(
	ctx context.Context,
	runID string,
	req CancelRun,
	actor ActorContext,
) (*Run, error)

CancelRun cancels one non-terminal task run under manager authority.

func (*Service) CancelTask 

func (m *Service) CancelTask(ctx context.Context, id string, req CancelTask, actor ActorContext) (*Task, error)

CancelTask propagates manager-owned cancellation through the target task, affected runs, and all non-terminal descendants.

func (*Service) ClaimNextRun 

func (m *Service) ClaimNextRun(
	ctx context.Context,
	criteria ClaimCriteria,
	actor ActorContext,
) (*ClaimResult, error)

ClaimNextRun atomically claims the next eligible run for one session and returns the raw claim token once.

func (*Service) ClaimRun 

func (m *Service) ClaimRun(
	ctx context.Context,
	runID string,
	claim ClaimRun,
	actor ActorContext,
) (*Run, error)

ClaimRun transitions one queued run into the claimed state.

func (*Service) CompleteRun 

func (m *Service) CompleteRun(
	ctx context.Context,
	runID string,
	result RunResult,
	actor ActorContext,
) (*Run, error)

CompleteRun marks one running task run as completed and reconciles task state.

func (*Service) CompleteRunLease 

func (m *Service) CompleteRunLease(
	ctx context.Context,
	completion LeaseCompletion,
	actor ActorContext,
) (*Run, error)

CompleteRunLease marks one active task-run lease complete after token verification.

func (*Service) CreateChildTask 

func (m *Service) CreateChildTask(
	ctx context.Context,
	parentTaskID string,
	spec CreateTask,
	actor ActorContext,
) (*Task, error)

CreateChildTask creates one child task beneath the supplied parent and emits an additional parent-scoped audit event.

func (*Service) CreateTask 

func (m *Service) CreateTask(ctx context.Context, spec CreateTask, actor ActorContext) (*Task, error)

CreateTask derives one canonical task record from trusted actor context and persists the corresponding immutable audit event.

func (*Service) DeleteExecutionProfile 

func (m *Service) DeleteExecutionProfile(
	ctx context.Context,
	taskID string,
	actor ActorContext,
) error

DeleteExecutionProfile removes the persisted profile after active-run drift checks.

func (*Service) DeleteTask 

func (m *Service) DeleteTask(ctx context.Context, id string, actor ActorContext) error

DeleteTask removes one task after verifying it is not still in use by child tasks or non-terminal runs, then reconciles any dependents unblocked by the cascade-deleted dependency edges.

func (*Service) DismissTask 

func (m *Service) DismissTask(ctx context.Context, id string, actor ActorContext) (TriageState, error)

DismissTask persists the current actor-scoped triage state as dismissed for the task's latest known activity snapshot.

func (*Service) DrainScheduler 

func (m *Service) DrainScheduler(
	ctx context.Context,
	req SchedulerDrainRequest,
	actor ActorContext,
) (SchedulerDrainResult, error)

DrainScheduler pauses the scheduler and waits until active claims reach zero or the timeout expires.

func (*Service) EnqueueRun 

func (m *Service) EnqueueRun(ctx context.Context, spec EnqueueRun, actor ActorContext) (*Run, error)

EnqueueRun persists one new queue-first task run under manager authority.

func (*Service) FailRun 

func (m *Service) FailRun(
	ctx context.Context,
	runID string,
	failure RunFailure,
	actor ActorContext,
) (*Run, error)

FailRun marks one starting or running task run as failed and reconciles task state.

func (*Service) FailRunLease 

func (m *Service) FailRunLease(
	ctx context.Context,
	failure LeaseFailure,
	actor ActorContext,
) (*Run, error)

FailRunLease marks one active task-run lease failed after token verification.

func (*Service) ForceFailRun 

func (m *Service) ForceFailRun(
	ctx context.Context,
	runID string,
	failure ForceFailRun,
	actor ActorContext,
) (*Run, error)

ForceFailRun marks one queued or claimed run failed without requiring the raw claim token.

func (*Service) ForceReleaseRun 

func (m *Service) ForceReleaseRun(
	ctx context.Context,
	runID string,
	release ForceReleaseRun,
	actor ActorContext,
) (*Run, error)

ForceReleaseRun releases one claimed run without requiring the raw claim token.

func (*Service) GetExecutionProfile 

func (m *Service) GetExecutionProfile(
	ctx context.Context,
	taskID string,
	actor ActorContext,
) (ExecutionProfile, error)

GetExecutionProfile returns the persisted profile or the default inherit profile.

func (*Service) GetRunReview 

func (m *Service) GetRunReview(ctx context.Context, reviewID string, actor ActorContext) (RunReview, error)

GetRunReview returns one persisted task-run review.

func (*Service) GetTask 

func (m *Service) GetTask(ctx context.Context, id string, actor ActorContext) (*View, error)

GetTask returns one expanded task view after enforcing read authority.

func (*Service) HeartbeatRunLease 

func (m *Service) HeartbeatRunLease(
	ctx context.Context,
	heartbeat LeaseHeartbeat,
	actor ActorContext,
) (*Run, error)

HeartbeatRunLease extends one active task-run lease after token verification.

func (*Service) InspectRun 

func (m *Service) InspectRun(ctx context.Context, runID string, actor ActorContext) (*InspectView, error)

InspectRun returns a deterministic read-only snapshot rooted at one run id.

func (*Service) InspectTask 

func (m *Service) InspectTask(ctx context.Context, taskID string, actor ActorContext) (*InspectView, error)

InspectTask returns a deterministic read-only snapshot for one task id.

func (*Service) ListRunReviews 

func (m *Service) ListRunReviews(
	ctx context.Context,
	query RunReviewQuery,
	actor ActorContext,
) ([]RunReview, error)

ListRunReviews returns persisted review requests that match the supplied filters.

func (*Service) ListTaskRuns 

func (m *Service) ListTaskRuns(
	ctx context.Context,
	taskID string,
	query RunQuery,
	actor ActorContext,
) ([]Run, error)

ListTaskRuns returns task runs for one task after enforcing read authority and task existence.

func (*Service) ListTasks 

func (m *Service) ListTasks(ctx context.Context, query Query, actor ActorContext) ([]Summary, error)

ListTasks returns task summaries that satisfy the supplied query filters after enforcing read authority.

func (*Service) LookupActiveRunForSession 

func (m *Service) LookupActiveRunForSession(
	ctx context.Context,
	sessionID string,
	runID string,
) (AutonomyLeaseHandle, error)

LookupActiveRunForSession resolves the internal claim token for a session-owned run while preserving the existing token-fenced lease writers as the sole mutation authority.

func (*Service) LookupRunReviewForSession 

func (m *Service) LookupRunReviewForSession(
	ctx context.Context,
	sessionID string,
	actor ActorContext,
) (RunReviewBinding, error)

LookupRunReviewForSession returns the active review bound to one reviewer session.

func (*Service) MarkTaskRead 

func (m *Service) MarkTaskRead(ctx context.Context, id string, actor ActorContext) (TriageState, error)

MarkTaskRead persists the current actor-scoped triage state as read for the task's latest known activity snapshot.

func (*Service) PauseScheduler 

func (m *Service) PauseScheduler(
	ctx context.Context,
	req SchedulerPauseRequest,
	actor ActorContext,
) (SchedulerStatus, error)

PauseScheduler marks the daemon scheduler as paused for new dispatch and claims.

func (*Service) PauseTask 

func (m *Service) PauseTask(
	ctx context.Context,
	id string,
	req PauseTaskRequest,
	actor ActorContext,
) (*Task, error)

PauseTask marks one task as paused for future scheduler and claim eligibility.

func (*Service) PublishTask 

func (m *Service) PublishTask(
	ctx context.Context,
	id string,
	req ExecutionRequest,
	actor ActorContext,
) (*Execution, error)

PublishTask transitions one durable draft into manager-owned runnable reconciliation, then enqueues the executable run for the explicit execution boundary.

func (*Service) RecordRunReview 

func (m *Service) RecordRunReview(
	ctx context.Context,
	req RecordRunReviewRequest,
	actor ActorContext,
) (RunReviewResult, error)

RecordRunReview persists an authoritative reviewer verdict and optional continuation run.

func (*Service) RecoverExpiredRunLeases 

func (m *Service) RecoverExpiredRunLeases(
	ctx context.Context,
	recovery ExpiredLeaseRecovery,
	actor ActorContext,
) ([]ExpiredLeaseRecoveryResult, error)

RecoverExpiredRunLeases requeues stale task-run leases and emits lease-expiration hooks once.

func (*Service) RecoverRunOnBoot 

func (m *Service) RecoverRunOnBoot(
	ctx context.Context,
	runID string,
	recovery RunBootRecovery,
	actor ActorContext,
) (*Run, error)

RecoverRunOnBoot applies one daemon-owned recovery decision to a non-terminal run discovered during startup reconciliation.

func (*Service) RejectTask 

func (m *Service) RejectTask(ctx context.Context, id string, actor ActorContext) (*Task, error)

RejectTask records one rejection decision for a manual-approval task that is currently awaiting a decision and reconciles the resulting task status.

func (*Service) ReleaseRunLease 

func (m *Service) ReleaseRunLease(
	ctx context.Context,
	release LeaseRelease,
	actor ActorContext,
) (*Run, error)

ReleaseRunLease releases one active task-run lease after token verification and requeues the run.

func (*Service) ReleaseSessionRunLeases 

func (m *Service) ReleaseSessionRunLeases(
	ctx context.Context,
	release SessionLeaseRelease,
	actor ActorContext,
) ([]SessionLeaseReleaseResult, error)

ReleaseSessionRunLeases structurally releases every active task-run lease bound to one session without requiring the raw claim token. This is reserved for daemon-owned runtime cleanup paths such as safe-spawn reaping.

func (*Service) RemoveDependency 

func (m *Service) RemoveDependency(
	ctx context.Context,
	taskID string,
	dependsOnID string,
	actor ActorContext,
) error

RemoveDependency deletes one dependency edge through the manager, reconciles the task status, and records the canonical audit event.

func (*Service) RequestRunReview 

func (m *Service) RequestRunReview(
	ctx context.Context,
	req RunReviewRequest,
	actor ActorContext,
) (RunReview, bool, error)

RequestRunReview persists or returns the idempotent review request for a terminal task run.

func (*Service) ResumeScheduler 

func (m *Service) ResumeScheduler(
	ctx context.Context,
	_ SchedulerResumeRequest,
	actor ActorContext,
) (SchedulerStatus, error)

ResumeScheduler clears the daemon scheduler pause flag.

func (*Service) ResumeTask 

func (m *Service) ResumeTask(
	ctx context.Context,
	id string,
	req ResumeTaskRequest,
	actor ActorContext,
) (*Task, error)

ResumeTask clears one task pause for future scheduler and claim eligibility.

func (*Service) RetryRun 

func (m *Service) RetryRun(
	ctx context.Context,
	runID string,
	retry RetryRunRequest,
	actor ActorContext,
) (*RetryRunResult, error)

RetryRun creates one new queued run linked to a failed source run.

func (*Service) RunDetail 

func (m *Service) RunDetail(
	ctx context.Context,
	runID string,
	actor ActorContext,
) (*RunDetailView, error)

func (*Service) SchedulerBacklog 

func (m *Service) SchedulerBacklog(
	ctx context.Context,
	query SchedulerBacklogQuery,
	actor ActorContext,
) (SchedulerBacklog, error)

SchedulerBacklog returns queued scheduler backlog rows.

func (*Service) SchedulerStatus 

func (m *Service) SchedulerStatus(ctx context.Context, actor ActorContext) (SchedulerStatus, error)

SchedulerStatus returns scheduler-wide pause state and live queue pressure.

func (*Service) SetExecutionProfile 

func (m *Service) SetExecutionProfile(
	ctx context.Context,
	taskID string,
	profile *ExecutionProfile,
	actor ActorContext,
) (ExecutionProfile, error)

SetExecutionProfile validates and persists one task-owned execution profile.

func (*Service) StartRun 

func (m *Service) StartRun(ctx context.Context, runID string, req StartRun, actor ActorContext) (*Run, error)

StartRun transitions one claimed or starting run into active execution.

func (*Service) StartTask 

func (m *Service) StartTask(
	ctx context.Context,
	id string,
	req ExecutionRequest,
	actor ActorContext,
) (*Execution, error)

StartTask enqueues one executable run for an already-created task.

func (*Service) Stream 

func (m *Service) Stream(
	ctx context.Context,
	taskID string,
	query StreamQuery,
	actor ActorContext,
) (<-chan StreamEvent, error)

func (*Service) Timeline 

func (m *Service) Timeline(
	ctx context.Context,
	taskID string,
	query TimelineQuery,
	actor ActorContext,
) ([]TimelineItem, error)

func (*Service) Tree 

func (m *Service) Tree(ctx context.Context, taskID string, actor ActorContext) (*TreeView, error)

func (*Service) UpdateTask 

func (m *Service) UpdateTask(ctx context.Context, id string, patch Patch, actor ActorContext) (*Task, error)

UpdateTask applies one mutable patch while preserving immutable identity and structural fields under manager control.

type SessionExecutor 

type SessionExecutor interface {
	StartTaskSession(ctx context.Context, spec *StartTaskSession) (*SessionRef, error)
	AttachTaskSession(ctx context.Context, runID string, sessionID string) (*SessionRef, error)
	RequestTaskStop(ctx context.Context, sessionID string, reason StopReason) error
	ForceTaskStop(ctx context.Context, sessionID string, reason StopReason) error
}

SessionExecutor is the injected runtime bridge used to start, attach, and stop task sessions.

type SessionLeaseRelease 

type SessionLeaseRelease struct {
	SessionID string    `json:"session_id"`
	Reason    string    `json:"reason,omitempty"`
	Now       time.Time `json:"now"`
}

SessionLeaseRelease captures a daemon-owned structural release for all active leases bound to one runtime session.

func (SessionLeaseRelease) Normalize 

func (r SessionLeaseRelease) Normalize(defaultNow time.Time) (SessionLeaseRelease, error)

Normalize returns a validated structural session lease release request.

func (SessionLeaseRelease) Validate 

func (r SessionLeaseRelease) Validate(path string) error

Validate reports whether the structural session lease release is internally consistent.

type SessionLeaseReleaseResult 

type SessionLeaseReleaseResult struct {
	Run                    Run       `json:"run"`
	PreviousRunStatus      RunStatus `json:"previous_run_status"`
	PreviousSessionID      string    `json:"previous_session_id,omitempty"`
	PreviousLeaseUntil     time.Time `json:"previous_lease_until"`
	PreviousClaimTokenHash string    `json:"previous_claim_token_hash,omitempty"`
	Reason                 string    `json:"reason,omitempty"`
}

SessionLeaseReleaseResult records one structurally released session lease.

type SessionRef 

type SessionRef struct {
	SessionID   string    `json:"session_id"`
	WorkspaceID string    `json:"workspace_id,omitempty"`
	StartedAt   time.Time `json:"started_at"`
}

SessionRef is the task-domain view of a runtime session binding.

func (SessionRef) Validate 

func (r SessionRef) Validate() error

Validate reports whether the session reference returned by the bridge is usable.

type SoulClaimProvenance 

type SoulClaimProvenance struct {
	SnapshotID string    `json:"snapshot_id,omitempty"`
	Digest     string    `json:"digest,omitempty"`
	AgentName  string    `json:"agent_name,omitempty"`
	CapturedAt time.Time `json:"captured_at"`
}

SoulClaimProvenance captures pre-resolved session Soul data at claim time.

func (SoulClaimProvenance) Validate 

func (p SoulClaimProvenance) Validate(path string) error

Validate reports whether pre-resolved Soul claim provenance is internally consistent.

type StartRun 

type StartRun struct {
	IdempotencyKey string `json:"idempotency_key,omitempty"`
}

StartRun captures one run-start request.

func (StartRun) Validate 

func (r StartRun) Validate(path string) error

Validate reports whether the start-run request is internally consistent.

type StartTaskSession 

type StartTaskSession struct {
	Task             Task              `json:"task"`
	Run              Run               `json:"run"`
	ExecutionProfile *ExecutionProfile `json:"execution_profile,omitempty"`
	Actor            ActorContext      `json:"actor"`
}

StartTaskSession captures the task and run context needed to allocate a dedicated session.

func (*StartTaskSession) Validate 

func (r *StartTaskSession) Validate() error

Validate reports whether the session-start request contains the task and run context required by the bridge.

type Status 

type Status string

Status identifies the canonical lifecycle state of a task. 

const (
	// TaskStatusDraft reports a saved draft that is not yet runnable.
	TaskStatusDraft Status = "draft"
	// TaskStatusPending reports a task that exists but has not yet been reconciled into ready work.
	TaskStatusPending Status = "pending"
	// TaskStatusBlocked reports a task with unresolved dependencies.
	TaskStatusBlocked Status = "blocked"
	// TaskStatusReady reports a task that may execute because dependencies are satisfied.
	TaskStatusReady Status = "ready"
	// TaskStatusInProgress reports a task with an active starting or running run.
	TaskStatusInProgress Status = "in_progress"
	// TaskStatusCompleted reports a task that finished successfully.
	TaskStatusCompleted Status = "completed"
	// TaskStatusFailed reports a task that ended unsuccessfully.
	TaskStatusFailed Status = "failed"
	// TaskStatusCanceled reports a task that was canceled before successful completion.
	TaskStatusCanceled Status = "canceled"
)

func (Status) Normalize 

func (s Status) Normalize() Status

Normalize returns the normalized representation of the task status.

func (Status) Validate 

func (s Status) Validate(path string) error

Validate reports whether the task status is one of the supported lifecycle states.

type StopReason 

type StopReason string

StopReason identifies why the task domain asked the session bridge to stop a session. 

const (
	// StopReasonCompleted identifies successful task-run completion.
	StopReasonCompleted StopReason = "completed"
	// StopReasonFailed identifies failed task-run termination.
	StopReasonFailed StopReason = "failed"
	// StopReasonCancellation identifies explicit task or run cancellation.
	StopReasonCancellation StopReason = "cancellation"
	// StopReasonShutdown identifies daemon shutdown or boot recovery stop requests.
	StopReasonShutdown StopReason = "shutdown"
	// StopReasonOrphanedRun identifies orphaned-run recovery handling.
	StopReasonOrphanedRun StopReason = "orphaned_run"
)

func (StopReason) Normalize 

func (r StopReason) Normalize() StopReason

Normalize returns the normalized representation of the session stop reason.

func (StopReason) Validate 

func (r StopReason) Validate(path string) error

Validate reports whether the stop reason is supported.

type Store 

type Store interface {
	RecordStore
	DependencyStore
	RunStore
	EventStore
	EventSequenceStore
	IdempotencyStore
	TriageStore
	ExecutionProfileStore
	RunReviewStore
}

Store composes the task-domain persistence surfaces consumed by the manager.

type StreamEvent 

type StreamEvent struct {
	Sequence int64        `json:"sequence"`
	Type     string       `json:"type"`
	Timeline TimelineItem `json:"timeline"`
}

StreamEvent is one task-scoped replayable live event suitable for SSE transport.

type StreamQuery 

type StreamQuery struct {
	AfterSequence int64 `json:"after_sequence,omitempty"`
}

StreamQuery captures reconnect-friendly task stream replay semantics.

func (StreamQuery) Validate 

func (q StreamQuery) Validate(path string) error

Validate reports whether the task stream query filters are internally consistent.

type Summary 

type Summary struct {
	ID              string                `json:"id"`
	Identifier      string                `json:"identifier,omitempty"`
	Scope           Scope                 `json:"scope"`
	WorkspaceID     string                `json:"workspace_id,omitempty"`
	ParentTaskID    string                `json:"parent_task_id,omitempty"`
	NetworkChannel  string                `json:"network_channel,omitempty"`
	Title           string                `json:"title"`
	Priority        Priority              `json:"priority,omitempty"`
	Status          Status                `json:"status"`
	ApprovalPolicy  ApprovalPolicy        `json:"approval_policy,omitempty"`
	ApprovalState   ApprovalState         `json:"approval_state,omitempty"`
	CurrentRunID    string                `json:"current_run_id,omitempty"`
	PausedBy        string                `json:"paused_by,omitempty"`
	PausedReason    string                `json:"paused_reason,omitempty"`
	PausedByTaskID  string                `json:"paused_by_task_id,omitempty"`
	CreatedBy       ActorIdentity         `json:"created_by"`
	Origin          Origin                `json:"origin"`
	Owner           *Ownership            `json:"owner,omitempty"`
	Dependencies    []DependencyReference `json:"dependencies,omitempty"`
	ActiveRun       *RunSummary           `json:"active_run,omitempty"`
	MaxAttempts     int                   `json:"max_attempts,omitempty"`
	LatestEventSeq  int64                 `json:"latest_event_seq"`
	ChildCount      int                   `json:"child_count,omitempty"`
	DependencyCount int                   `json:"dependency_count,omitempty"`
	Draft           bool                  `json:"draft"`
	Paused          bool                  `json:"paused,omitempty"`
	EffectivePaused bool                  `json:"effective_paused,omitempty"`
	PausedAt        time.Time             `json:"paused_at,omitzero"`
	CreatedAt       time.Time             `json:"created_at"`
	UpdatedAt       time.Time             `json:"updated_at"`
	ClosedAt        time.Time             `json:"closed_at"`
	LastActivityAt  time.Time             `json:"last_activity_at"`
}

Summary is the lightweight read model returned from list-oriented task queries.

type Task 

type Task struct {
	ID             string          `json:"id"`
	Identifier     string          `json:"identifier,omitempty"`
	Scope          Scope           `json:"scope"`
	WorkspaceID    string          `json:"workspace_id,omitempty"`
	ParentTaskID   string          `json:"parent_task_id,omitempty"`
	NetworkChannel string          `json:"network_channel,omitempty"`
	Title          string          `json:"title"`
	Description    string          `json:"description,omitempty"`
	Priority       Priority        `json:"priority,omitempty"`
	MaxAttempts    int             `json:"max_attempts,omitempty"`
	Status         Status          `json:"status"`
	ApprovalPolicy ApprovalPolicy  `json:"approval_policy,omitempty"`
	ApprovalState  ApprovalState   `json:"approval_state,omitempty"`
	Owner          *Ownership      `json:"owner,omitempty"`
	CurrentRunID   string          `json:"current_run_id,omitempty"`
	LatestEventSeq int64           `json:"latest_event_seq"`
	Paused         bool            `json:"paused,omitempty"`
	PausedBy       string          `json:"paused_by,omitempty"`
	PausedAt       time.Time       `json:"paused_at,omitzero"`
	PausedReason   string          `json:"paused_reason,omitempty"`
	CreatedBy      ActorIdentity   `json:"created_by"`
	Origin         Origin          `json:"origin"`
	CreatedAt      time.Time       `json:"created_at"`
	UpdatedAt      time.Time       `json:"updated_at"`
	ClosedAt       time.Time       `json:"closed_at"`
	Metadata       json.RawMessage `json:"metadata,omitempty"`
}

Task is the durable coordination record owned by the task domain.

func (Task) Validate 

func (t Task) Validate() error

Validate reports whether the task record contains the canonical persisted shape.

type TimelineItem 

type TimelineItem struct {
	Sequence  int64           `json:"sequence"`
	EventID   string          `json:"event_id"`
	Task      Reference       `json:"task"`
	Run       *RunSummary     `json:"run,omitempty"`
	EventType string          `json:"event_type"`
	Actor     ActorIdentity   `json:"actor"`
	Origin    Origin          `json:"origin"`
	Payload   json.RawMessage `json:"payload,omitempty"`
	Timestamp time.Time       `json:"timestamp"`
}

TimelineItem is the normalized task event row consumed by live task surfaces.

type TimelineQuery 

type TimelineQuery struct {
	AfterSequence int64 `json:"after_sequence,omitempty"`
	Limit         int   `json:"limit,omitempty"`
}

TimelineQuery captures reconnect-friendly task timeline windowing semantics.

func (TimelineQuery) Validate 

func (q TimelineQuery) Validate(path string) error

Validate reports whether the task timeline query filters are internally consistent.

type TreeNode 

type TreeNode struct {
	Task           Reference   `json:"task"`
	ParentTaskID   string      `json:"parent_task_id,omitempty"`
	Depth          int         `json:"depth"`
	ChildCount     int         `json:"child_count,omitempty"`
	ActiveRun      *RunSummary `json:"active_run,omitempty"`
	LastActivityAt time.Time   `json:"last_activity_at"`
}

TreeNode is one node inside a task-tree live snapshot.

type TreeView 

type TreeView struct {
	Root        TreeNode   `json:"root"`
	Descendants []TreeNode `json:"descendants,omitempty"`
}

TreeView is the manager-owned live snapshot for one task tree.

type TriageState 

type TriageState struct {
	TaskID             string        `json:"task_id"`
	Actor              ActorIdentity `json:"actor"`
	Read               bool          `json:"read"`
	Archived           bool          `json:"archived"`
	Dismissed          bool          `json:"dismissed"`
	LastSeenActivityAt time.Time     `json:"last_seen_activity_at"`
	UpdatedAt          time.Time     `json:"updated_at"`
}

TriageState is the durable actor-scoped inbox and triage state for one task.

func (TriageState) Validate 

func (t TriageState) Validate() error

Validate reports whether the durable task triage state contains the canonical shape.

type TriageStore 

type TriageStore interface {
	GetTaskTriageState(ctx context.Context, taskID string, actor ActorIdentity) (TriageState, error)
	UpsertTaskTriageState(ctx context.Context, state TriageState) error
}

TriageStore is the persistence surface for durable actor-scoped task triage state.

type View 

type View struct {
	Summary              Summary               `json:"summary"`
	Task                 Task                  `json:"task"`
	Children             []Summary             `json:"children,omitempty"`
	Dependencies         []Dependency          `json:"dependencies,omitempty"`
	DependencyReferences []DependencyReference `json:"dependency_references,omitempty"`
	Runs                 []Run                 `json:"runs,omitempty"`
	Events               []Event               `json:"events,omitempty"`
}

View is the expanded read model returned from single-task lookups.

type WorkerMode 

type WorkerMode string

WorkerMode identifies how a task narrows worker selection.

func (WorkerMode) Normalize 

func (m WorkerMode) Normalize() WorkerMode

Normalize returns the normalized worker mode.

type WorkerProfile 

type WorkerProfile struct {
	Mode                  WorkerMode `json:"mode"`
	AgentName             string     `json:"agent_name,omitempty"`
	Provider              string     `json:"provider,omitempty"`
	Model                 string     `json:"model,omitempty"`
	AllowedAgentNames     []string   `json:"allowed_agent_names,omitempty"`
	PreferredAgentNames   []string   `json:"preferred_agent_names,omitempty"`
	RequiredCapabilities  []string   `json:"required_capabilities,omitempty"`
	PreferredCapabilities []string   `json:"preferred_capabilities,omitempty"`
}

WorkerProfile narrows eligible task workers without granting runtime authority.

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.