runtimetool

package
v0.0.0-...-804b954 Latest Latest
Warning

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

Go to latest
Published: Aug 13, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package runtimetool owns capability-bound external tool execution.

Index

Constants

This section is empty.

Variables

View Source
var ErrDenied = errors.New("tool admission denied")

ErrDenied reports a policy refusal without disclosing whether the policy, tool name, or revision was absent. The broker does not construct a Tool intent, Approval, grant, or execution when it returns this error.

Functions

This section is empty.

Types

type Adapter

type Adapter interface {
	Execute(context.Context, Request) (Response, error)
	Reconcile(context.Context, Request) (Response, error)
}

type Admission

type Admission struct {
	ToolCallID string
	ApprovalID agentruntime.ApprovalID
}

Admission is the sealed durable correlation returned only to the private model worker. The public API exposes the resulting Approval by its own authorization rules.

type AdmissionRequest

type AdmissionRequest struct {
	Tenant                         runtimecontent.TenantID
	Principal                      runtimecontent.PrincipalID
	SessionID                      agentruntime.SessionID
	TurnID                         agentruntime.TurnID
	ToolCallID                     string
	ApprovalID                     agentruntime.ApprovalID
	PolicyName                     string
	PolicyRevision                 uint64
	ToolName                       string
	ActionDigest, CapabilityDigest string
	Action                         agentruntime.ApprovalAction
	MaximumUses                    uint32
	ExpiresAt                      time.Time
	Descriptor                     runtimecontent.ContentHandoff
	IdempotencyKey                 string
}

AdmissionRequest is a model-worker-only normalized Tool request. The model adapter supplies opaque, preallocated correlations; it does not receive a capability grant or sandbox client.

type Broker

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

Broker owns the only supported transition from normalized model Tool intent to durable authorization state. It has no adapter: execution remains owned by Worker after an owner has approved and a grant has been consumed.

func NewBroker

func NewBroker(config BrokerConfig) (*Broker, error)

NewBroker constructs the private model-to-tool authority boundary.

func (*Broker) Admit

func (broker *Broker) Admit(ctx context.Context, request AdmissionRequest) (Admission, error)

Admit evaluates one immutable policy revision and, only when that revision requires approval, atomically persists the Tool intent and pending Approval. A replay with the same idempotency key returns the same atomic state plan.

type BrokerConfig

type BrokerConfig struct {
	Store    runtimestate.RuntimeStateStore
	Compiler *runtimestate.Compiler
	Planner  *runtimestate.RuntimeStatePlanner
	Clock    clock.Clock
}

BrokerConfig supplies the state authorities required to seal an admission.

type BuiltinAdapter

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

BuiltinAdapter labels an in-process tool implementation while preserving the broker-only Worker entry point and external-effect recovery contract.

func NewBuiltinAdapter

func NewBuiltinAdapter(adapter ContractAdapter) (*BuiltinAdapter, error)

NewBuiltinAdapter constructs a broker-only builtin adapter seam.

func (*BuiltinAdapter) Execute

func (adapter *BuiltinAdapter) Execute(ctx context.Context, request Request) (Response, error)

Execute delegates only after Worker authorization.

func (*BuiltinAdapter) ExternalEffectContract

func (adapter *BuiltinAdapter) ExternalEffectContract() ExternalEffectContract

ExternalEffectContract preserves the wrapped adapter declaration.

func (*BuiltinAdapter) Reconcile

func (adapter *BuiltinAdapter) Reconcile(ctx context.Context, request Request) (Response, error)

Reconcile observes the exact existing operation without submission.

type Config

type Config struct {
	Store    runtimestate.RuntimeStateStore
	Tenants  runtimestate.OutboxTenantSource
	Compiler *runtimestate.Compiler
	Planner  *runtimestate.RuntimeStatePlanner
	Clock    clock.Clock
	Content  *runtimecontent.Store
	Adapter  Adapter
	Claimer  string
	// LeaseRenewalInterval bounds how long a healthy worker may wait before
	// extending its exact outbox claim. Zero uses half the fixed recovery lease.
	LeaseRenewalInterval time.Duration
	// LeaseScheduler drives claim-renewal checks and is required at the
	// composition root; deterministic tests can inject explicit ticks.
	LeaseScheduler LeaseScheduler
}

type ContractAdapter

type ContractAdapter interface {
	Adapter
	ExternalEffectContract() ExternalEffectContract
}

ContractAdapter is the sealed construction boundary for adapters that can cause an external effect.

type ExternalEffectContract

type ExternalEffectContract struct {
	IdempotencyKey string
	Reconciles     bool
}

ExternalEffectContract declares the two runtime guarantees every concrete tool adapter must preserve. The adapter uses OperationID as its application idempotency key and Reconcile observes that exact key without resubmission.

type LeaseScheduler

type LeaseScheduler interface {
	// NewLeaseTicker returns one ticker for the supplied positive interval.
	NewLeaseTicker(time.Duration) LeaseTicker
}

LeaseScheduler constructs managed renewal tickers for active claims.

func NewRealtimeLeaseScheduler

func NewRealtimeLeaseScheduler() LeaseScheduler

NewRealtimeLeaseScheduler returns the production scheduler for injection at an application composition root.

type LeaseTicker

type LeaseTicker interface {
	// C returns the renewal channel.
	C() <-chan time.Time
	// Stop releases the ticker after the claim is terminal or lost.
	Stop()
	// Handled records that the owning worker consumed a tick.
	Handled()
}

LeaseTicker delivers recurring renewal opportunities for one owned claim.

type MCPAdapter

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

MCPAdapter labels an MCP transport adapter behind the same broker-only seam.

func NewMCPAdapter

func NewMCPAdapter(adapter ContractAdapter) (*MCPAdapter, error)

NewMCPAdapter constructs a broker-only MCP adapter seam.

func (*MCPAdapter) Execute

func (adapter *MCPAdapter) Execute(ctx context.Context, request Request) (Response, error)

func (*MCPAdapter) ExternalEffectContract

func (adapter *MCPAdapter) ExternalEffectContract() ExternalEffectContract

func (*MCPAdapter) Reconcile

func (adapter *MCPAdapter) Reconcile(ctx context.Context, request Request) (Response, error)

type Request

type Request struct {
	Tenant      runtimecontent.TenantID
	SessionID   agentruntime.SessionID
	TurnID      agentruntime.TurnID
	ToolCallID  string
	OperationID runtimestate.OperationID
	// Descriptor is the exact verified immutable sandbox-control action. It is
	// supplied only after the worker's state authorization succeeds.
	Descriptor []byte
	// Arguments are the exact canonical model input sealed with Descriptor at
	// admission. They are private to the authorized adapter dispatch path.
	Arguments []byte
	// contains filtered or unexported fields
}

type Response

type Response struct {
	Output    []byte
	MediaType string
	Failure   *agentruntime.Failure
	Uncertain bool
}

type SandboxAdapter

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

SandboxAdapter executes only canonical sandbox.control/v1 requests supplied by the worker's verified descriptor reader. It never constructs an action from runtime metadata, and recovered claims query the same durable sandbox operation instead of submitting again.

func NewSandboxAdapter

func NewSandboxAdapter(client sandbox.Client) (*SandboxAdapter, error)

NewSandboxAdapter constructs the concrete external-effect adapter.

func (*SandboxAdapter) Execute

func (adapter *SandboxAdapter) Execute(ctx context.Context, request Request) (Response, error)

func (*SandboxAdapter) ExternalEffectContract

func (adapter *SandboxAdapter) ExternalEffectContract() ExternalEffectContract

ExternalEffectContract declares sandbox-control's operation-ID recovery path.

func (*SandboxAdapter) Reconcile

func (adapter *SandboxAdapter) Reconcile(ctx context.Context, request Request) (Response, error)

type Worker

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

func NewWorker

func NewWorker(c Config) (*Worker, error)

func (*Worker) ScanOnce

func (w *Worker) ScanOnce(ctx context.Context) error

Jump to

Keyboard shortcuts

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