Documentation
¶
Overview ¶
Package controltool defines the provider-neutral SDK contract for one optional proxy-owned model control tool.
A provider exposes a frozen Spec (name, JSON Schema, instruction, and args budget) and consumes a completed call plus request-local provenance. This package validates those contracts; it is not a tool runtime, service locator, or DI container. Tool names are provider-owned data at this layer.
Index ¶
- Constants
- Variables
- func ProviderIdentity(provider Provider) (id string, err error)
- func Reassert(call lipapi.Call, projection Projection) (lipapi.Call, error)
- func ValidateCompletedCall(c CompletedCall, maxArgsBytes int) error
- func ValidateInstruction(in Instruction) error
- func ValidateMeta(m Meta) error
- func ValidateOutcome(o Outcome) error
- func ValidateProvider(provider Provider) (err error)
- func ValidateProviderID(id string) error
- func ValidateSpec(s Spec) error
- type CompletedCall
- type Instruction
- type Meta
- type Outcome
- type OutcomeKind
- type Projection
- type Provider
- type Spec
Constants ¶
const ( ReasonActive = "" ReasonBackendToolsUnsupported = "backend_tools_unsupported" ReasonToolChoiceNone = "tool_choice_none" ReasonToolChoiceConstrained = "tool_choice_constrained" ReasonToolChoiceRequired = "tool_choice_required" ReasonAllowedToolsConstrained = "allowed_tools_constrained" ReasonToolNameCollision = "tool_name_collision" ReasonInstructionCollision = "instruction_collision" // ReasonOutputFormatUnsupported marks a requested response format the // control protocol cannot publish without breaking the client's output // contract. The proxy synthesizes the published text from a tool argument, // so only plain-text contracts are eligible until format-aware publication // exists. ReasonOutputFormatUnsupported = "output_format_unsupported" )
Bounded, content-free eligibility reasons. ReasonActive is the empty reason of an approved projection; every other value explains why an optional control feature stayed inactive without turning the condition into a candidate rejection.
const ( MaxProviderIDBytes = 128 MaxIdentifierBytes = 256 MaxReasonCodeBytes = 64 MaxInstructionBytes = 64 * 1024 MaxResultTextBytes = 64 * 1024 DefaultMaxArgsBytes = 64 * 1024 )
Bounds are measured in UTF-8 encoded bytes. DefaultMaxArgsBytes reuses the existing safe tool-call argument envelope (64 KiB).
Variables ¶
var ( ErrInvalidProvider = errors.New("controltool: invalid provider") ErrInvalidSpec = errors.New("controltool: invalid spec") ErrInvalidCall = errors.New("controltool: invalid call") ErrInvalidMeta = errors.New("controltool: invalid meta") ErrInvalidOutcome = errors.New("controltool: invalid outcome") )
Validation sentinels classify malformed control-tool contracts without exposing implementation details to callers.
var ( ErrProjectionInactive = errors.New("controltool: control projection is not active") ErrProjectionConflict = errors.New("controltool: control projection conflict") )
Reassertion failures are candidate-fatal, not per-request best effort.
Functions ¶
func ProviderIdentity ¶
ProviderIdentity validates a provider's stable identity and returns the bounded value used by generation composition. Typed-nil providers and provider identity panics fail closed as invalid providers.
func Reassert ¶
Reassert replays an already approved projection after a legitimate final canonical reconstruction. It never re-decides eligibility and never rewrites client state: the approved tool choice is compared exactly, the ordinary tool catalog must still be the approved one with the control tool as its final append, and the approved control instruction must survive exactly once at the head of the trajectory with the frozen original instruction prefix intact behind it.
A legitimate reconstruction that removed the control tool and/or the whole control prefix is restored, but only while the frozen ordinary catalog and original prefix prove the candidate is still the approved one. A duplicated, relocated, or altered control projection, and any ordinary tool catalog or instruction prefix that cannot be proved unchanged, fails closed.
func ValidateCompletedCall ¶
func ValidateCompletedCall(c CompletedCall, maxArgsBytes int) error
ValidateCompletedCall checks call identity and the supplied args budget.
func ValidateInstruction ¶
func ValidateInstruction(in Instruction) error
ValidateInstruction checks the instruction role and bounded text.
func ValidateMeta ¶
ValidateMeta checks bounded provenance identifiers.
func ValidateOutcome ¶
ValidateOutcome checks outcome kind, reason, and result-text invariants.
func ValidateProvider ¶
ValidateProvider checks identity and the frozen Spec. Typed-nil providers and Spec panics fail closed.
func ValidateProviderID ¶
ValidateProviderID checks the stable provider identity. The check is pure; callers should obtain ID once while composing a provider and retain that value for the generation lifetime.
func ValidateSpec ¶
ValidateSpec checks the frozen tool, instruction, and args budget.
Types ¶
type CompletedCall ¶
CompletedCall is the captured control-tool invocation. ToolName is opaque data; ownership is not inferred from the name at this contract.
func (CompletedCall) Validate ¶
func (c CompletedCall) Validate(maxArgsBytes int) error
Validate checks call identity and the supplied args budget.
type Instruction ¶
Instruction is the bounded, stable control text projected with the tool. V1 accepts only system or developer roles.
func (Instruction) Validate ¶
func (in Instruction) Validate() error
Validate checks the instruction role and bounded text.
type Meta ¶
type Meta struct {
TraceID string
ALegID string
BLegID string
CandidateKey string
AttemptSeq int
Scope scope.PrincipalScopeView
Session session.SessionView
Workspace workspace.WorkspaceView
}
Meta is request-local provenance supplied by the platform. Identifiers are opaque; Scope, Session, and Workspace are safe views, not authority objects.
type Outcome ¶
type Outcome struct {
Kind OutcomeKind
ResultText string
ReasonCode string
}
Outcome is the bounded provider result. OutcomeComplete requires non-empty result text. OutcomeInvalid carries no client output.
type OutcomeKind ¶
type OutcomeKind uint8
OutcomeKind identifies the only results a provider may return.
const ( // OutcomeInvalid is the zero value. It means the call is not a valid // control completion and must not carry client output. OutcomeInvalid OutcomeKind = iota // OutcomeComplete is a valid control completion with bounded result text. OutcomeComplete )
func (OutcomeKind) IsKnown ¶
func (k OutcomeKind) IsKnown() bool
IsKnown reports whether k is one of the two legal outcome kinds.
type Projection ¶
type Projection struct {
// contains filtered or unexported fields
}
Projection is the trusted, in-process result of one initial projection. It is request/attempt-local owned data: never canonical Extensions/Invocation, never serialized into frontend or backend metadata, and never reconstructed from a tool name observed on the wire. All payload is deep-owned, so accessors hand out copies and callers cannot mutate the approved projection.
func Project ¶
func Project(call lipapi.Call, spec Spec, caps lipapi.BackendCaps) (lipapi.Call, Projection, error)
Project computes the initial control projection for one candidate call. It first decides eligibility from the candidate's backend capabilities and the client tool-choice state, then clones the call and inserts exactly one control tool and one complete instruction into the backend-effective trajectory.
Ineligibility is not an error: the candidate call is returned exactly as supplied, the client tool choice is never rewritten, and the projection carries the bounded reason. That includes an exact client declaration of the spec control instruction, which stays an untouched client instruction instead of being adopted. An invalid Spec is a programming/generation error: it is returned as an error and nothing is mutated.
Project is the initial decision only. Because a same-named declaration is always a collision, re-projecting an already projected call reports ReasonToolNameCollision; every later projection point replays the approved projection with Reassert instead.
func (Projection) Active ¶
func (p Projection) Active() bool
Active reports whether the control tool and instruction were approved for the projected candidate call.
func (Projection) Instruction ¶
func (p Projection) Instruction() Instruction
Instruction returns a copy of the approved instruction.
func (Projection) MaxArgsBytes ¶
func (p Projection) MaxArgsBytes() int
MaxArgsBytes returns the approved bounded args budget for the control call, or 0 when inactive.
func (Projection) Reason ¶
func (p Projection) Reason() string
Reason returns the bounded, content-free reason for an inactive projection and the empty string for an active one.
func (Projection) Tool ¶
func (p Projection) Tool() lipapi.ToolDef
Tool returns a copy of the approved control tool definition with byte-stable schema bytes.
func (Projection) ToolChoice ¶
func (p Projection) ToolChoice() lipapi.ToolChoice
ToolChoice returns a copy of the client tool choice that was approved, so a later reassertion can prove the constraint was never rewritten.
func (Projection) ToolName ¶
func (p Projection) ToolName() string
ToolName returns the approved control tool name, or "" when inactive.
type Provider ¶
type Provider interface {
ID() string
Spec() Spec
Handle(context.Context, CompletedCall, Meta) (Outcome, error)
}
Provider is one optional proxy-owned model control tool. Handle receives a value copy of the completed call and provenance; providers have no contract capability to mutate the request, execute ordinary tools, or publish client output.
Source Files