Documentation
¶
Overview ¶
Package runtimetool owns capability-bound external tool execution.
Index ¶
Constants ¶
This section is empty.
Variables ¶
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 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.
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) ExternalEffectContract ¶
func (adapter *BuiltinAdapter) ExternalEffectContract() ExternalEffectContract
ExternalEffectContract preserves the wrapped adapter declaration.
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 ¶
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) ExternalEffectContract ¶
func (adapter *MCPAdapter) ExternalEffectContract() ExternalEffectContract
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) ExternalEffectContract ¶
func (adapter *SandboxAdapter) ExternalEffectContract() ExternalEffectContract
ExternalEffectContract declares sandbox-control's operation-ID recovery path.