execution

package
v0.7.0-rc.3 Latest Latest
Warning

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

 Go to latest Published: Sep 15, 2026 License: AGPL-3.0 Imports: 22 Imported by: 0

Documentation

Overview

Package execution admits runs with immutable host-derived origin and rechecks their credential and grant state across replicas. Input payloads are never identity.

Index

Constants

This section is empty.

Variables

View Source 
var ErrAgentBudget = errors.New("agent budget exceeded")
View Source 
var ErrAgentUsageUnavailable = errors.New("model did not report input and output usage required by the agent token budget")

Functions

func Access 

func Access(ctx context.Context, q *dbq.Queries, p authz.Principal, agentID uuid.UUID) (agentsdk.Access, error)

Access provides verified ingress policy for transport-side presentation.

func AdmitAgentTx 

func AdmitAgentTx(ctx context.Context, q *dbq.Queries, agentID uuid.UUID, generation int64, conversationID uuid.UUID, definition string, input json.RawMessage) (dbq.Run, error)

AdmitAgentTx binds a task to an app-owned conversation inside the scheduler's admission transaction. The task record and origin must commit together.

func AppOrigin 

func AppOrigin(ctx context.Context, q *dbq.Queries, agentID uuid.UUID, generation int64, ingress string) (dbq.ExecutionOrigin, error)

AppOrigin records an app-owned trigger against its live authenticated runtime generation. Host schedulers use the generation locked with their cron record.

func AuthorizeInvocationCompletion 

func AuthorizeInvocationCompletion(ctx context.Context, q *dbq.Queries, agentID, runID uuid.UUID, generation int64, proof InvocationProof) error

AuthorizeInvocationCompletion permits terminal telemetry for active nonhosted work, including closed delivery receipts until expiry. It returns no authority and does not require the initiating human credential to remain live. Callers must lock the run and retain the terminal update's cancellation/attempt fences.

func CloseInvocation 

func CloseInvocation(q *dbq.Queries, token string) error

CloseInvocation uses an independent bounded context so cancelled dispatches still close their receipt on every replica. Expiry also fences crashed hosts.

func ContinuationPrincipal 

func ContinuationPrincipal(ctx context.Context, q *dbq.Queries, agentID, conversationID, sourceRunID uuid.UUID) (authz.Principal, error)

ContinuationPrincipal restores the exact initiating run, never whichever run happens to be newest in a conversation. Display coordinates are not proof.

func IssueInvocation 

func IssueInvocation(ctx context.Context, q *dbq.Queries, agentID, runID, ownerToken uuid.UUID, expiresAt time.Time) (wire.RuntimeContext, error)

IssueInvocation is host-only. Call it immediately before dispatch and close the receipt when delivery finishes. The plaintext never enters shared storage.

func MatchRoute 

func MatchRoute(routes []dbq.AgentRoute, req *http.Request) (selected dbq.AgentRoute, ok bool, err error)

MatchRoute uses the same ServeMux semantics as the app listener.

func Principal 

func Principal(ctx context.Context, q *dbq.Queries, p authz.Principal) (authz.Principal, error)

Principal validates a supplied opaque admission proof before policy evaluation.

func RecordAgentTaskUsage 

func RecordAgentTaskUsage(ctx context.Context, database *db.DB, appID, runID, ownerToken, requestID uuid.UUID, tokens int64, reported bool) error

RecordAgentTaskUsage settles one model request exactly once. A historical claim can report incurred usage after lease loss, but cannot authorize another model/tool call. The run/session/token binding is verified from durable claims.

func RequireRuntimeProtocol 

func RequireRuntimeProtocol(ctx context.Context, q *dbq.Queries, agentID uuid.UUID) error

RequireRuntimeProtocol fences admission against the current generation's complete synchronized app manifest, independently of SDK semver.

func ReserveAgentTaskStep 

func ReserveAgentTaskStep(ctx context.Context, database *db.DB, appID, runID, ownerToken uuid.UUID) error

ReserveAgentTaskStep reserves one reasoning turn for the exact live owner. Native callbacks and hosted agent models share the same root accounting.

func ResumeConversation 

func ResumeConversation(ctx context.Context, q *dbq.Queries, p authz.Principal, agentID, runID uuid.UUID) (uuid.UUID, error)

ResumeConversation validates the exact platform credential binding without consuming the checkpoint. Admit performs the transactional single-use claim.

func UserJobOrigin 

func UserJobOrigin(ctx context.Context, q *dbq.Queries, p authz.Principal, agentID uuid.UUID) (dbq.ExecutionOrigin, error)

UserJobOrigin admits an operator-fired cron with verified credential coordinates. It has no fabricated app conversation or anonymous human.

func Watch 

func Watch(ctx context.Context, q *dbq.Queries, agentID, runID uuid.UUID, cancel context.CancelFunc) func()

Watch stops in-flight I/O on any failed live resolution. Only authoritative revocation requests durable job cancellation; lease recovery owns retries. Its goroutine holds no coordination state; the database is authoritative.

func WithInvocationProof 

func WithInvocationProof(ctx context.Context, proof InvocationProof) context.Context

func WithRuntimeOwner 

func WithRuntimeOwner(ctx context.Context, runID, token uuid.UUID) context.Context

WithRuntimeOwner adds an ownership ceiling to internal host operations. It conveys no authority: Resolve still restores the admitted run from the DB. Nested broker/model operations cannot borrow a replacement worker's lease.

Types

type Context 

type Context struct {
	Run       dbq.Run
	Origin    dbq.ExecutionOrigin
	Principal authz.Principal
	Runtime   wire.RuntimeContext
}

func Resolve 

func Resolve(ctx context.Context, q *dbq.Queries, agentID, runID uuid.UUID) (Context, error)

Resolve rechecks live credential state and current grants from immutable origin.

func ResolveInvocation 

func ResolveInvocation(ctx context.Context, q *dbq.Queries, agentID, runID uuid.UUID, generation int64, proof InvocationProof) (Context, error)

ResolveInvocation requires both the current app credential generation and a dispatch-bound proof before restoring any human authority from the run.

type InvocationProof 

type InvocationProof struct {
	Token      string
	JobID      string
	Attempt    int32
	LeaseToken string
}

InvocationProof is untrusted input until an invocation gate validates it. A job delivery may supply its exact attempt fence instead of a receipt.

func InvocationProofFromContext 

func InvocationProofFromContext(ctx context.Context) InvocationProof

type Kind 

type Kind string
const (
	Prompt  Kind = "prompt"
	Tool    Kind = "tool"
	Route   Kind = "route"
	Webhook Kind = "webhook"
	Job     Kind = "job"
	App     Kind = "app"
	Agent   Kind = "agent"
)

type Request 

type Request struct {
	AgentID               uuid.UUID
	Kind                  Kind
	Ref                   string
	Input                 json.RawMessage
	ConversationID        uuid.UUID
	ResumeRunID           uuid.UUID
	Method, Path, RawPath string
}

Request contains operation coordinates, not user or access assertions. Route requests copy Path and RawPath together from the incoming URL.

type RouteSelection 

type RouteSelection struct {
	Ref   string
	Asset bool
}

type Service 

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

func New 

func New(database *db.DB) *Service

func (*Service) Admit 

func (s *Service) Admit(ctx context.Context, p authz.Principal, req Request) (dbq.Run, error)

Admit validates ingress and commits origin, run, resume claim, and hosted lease atomically. A failed admission cannot consume a pending confirmation.

func (*Service) AdmitApp 

func (s *Service) AdmitApp(ctx context.Context, agentID uuid.UUID, generation int64, kind Kind, ref string, input json.RawMessage) (dbq.Run, error)

AdmitApp cannot borrow a human identity, conversation, or access assertion.

func (*Service) AdmitJob 

func (s *Service) AdmitJob(ctx context.Context, jobID uuid.UUID, attemptNumber int32, leaseToken uuid.UUID) (dbq.Run, error)

AdmitJob atomically binds exactly one token-fenced delivery attempt to a run. The immutable job origin retains its ingress independently of execution kind.

func (*Service) MaterializeDueCrons 

func (s *Service) MaterializeDueCrons(ctx context.Context, limit int32) (int, error)

MaterializeDueCrons locks due declarations across replicas and atomically records app-owned job origins, jobs, and their next scheduled occurrences. The scheduler wakes delivery only after this transaction commits.

func (*Service) RouteAccess 

func (s *Service) RouteAccess(ctx context.Context, p authz.Principal, agentID uuid.UUID, method, path, rawPath string) (RouteSelection, error)

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.