Documentation
¶
Overview ¶
Package hooks defines stable plugin contracts for submit, part, and tool-reactor hooks. The core runtime imports these interfaces; hook implementations live in feature plugins.
Hook interface shape (intentional):
- SubmitHook, RequestPartHook, and ResponsePartHook each expose four methods: ID, Order, a policy selector (FailureMode), and the handler. That is a deliberate trade-off: the hook bus can sort, log, and branch on identity and policy without auxiliary registries or reflection. Splitting metadata into smaller interfaces would scatter the contract across multiple types the core would still need to satisfy together, without simplifying callers.
- ToolReactor is narrower (three methods) because its error semantics are selected by the hook bus via ToolReactorErrorPolicy, not a per-hook FailureMode method.
pkg/lipsdk stays free of internal/runtime types; only lipapi shapes appear in hook signatures.
Tool reactions are expressed with lipapi.ToolEvent (canonical stream tool lifecycle); they must not depend on provider SDK event types (R9, R15).
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrSubmitRejected = errors.New("lipsdk/hooks: submit hook rejected request")
ErrSubmitRejected is returned when a submit hook rejects the call.
Functions ¶
func IsSubmitReject ¶
IsSubmitReject reports whether err is or wraps a submit rejection.
Types ¶
type FailureMode ¶
type FailureMode int
FailureMode selects how the hook bus treats a non-nil error from Handle.
const ( FailureModeUnspecified FailureMode = iota // FailOpen continues the chain after recording the error (submit/part hooks). FailOpen // FailClosed stops the chain and returns the error. FailClosed )
type RequestPartHook ¶
type RequestPartHook interface {
ID() string
Order() int
FailureMode() FailureMode
HandleRequestParts(ctx context.Context, call *lipapi.Call, meta PartMeta) error
}
RequestPartHook mutates canonical request parts before backend translation. The four-method shape matches SubmitHook so the part hook bus can reuse the same chaining model (identity, order, fail-open vs fail-closed) without a parallel metadata type.
type ResponsePartHook ¶
type ResponsePartHook interface {
ID() string
Order() int
FailureMode() FailureMode
HandleEvent(ctx context.Context, ev *lipapi.Event, meta PartMeta) error
}
ResponsePartHook mutates a single canonical stream event before frontend encoding. It mirrors RequestPartHook's four-method layout for the same bus and observability reasons.
type SubmitDecision ¶
type SubmitDecision struct {
// Reject stops the chain; Reason is surfaced via SubmitRejectError.
Reject bool
Reason string
}
SubmitDecision is the outcome of a single submit hook invocation.
type SubmitHook ¶
type SubmitHook interface {
ID() string
Order() int
FailureMode() FailureMode
Handle(ctx context.Context, call *lipapi.Call, meta *SubmitMeta) (SubmitDecision, error)
}
SubmitHook runs before route planning on the canonical call.
type SubmitMeta ¶
type SubmitMeta struct {
TraceID string
// Annotations is a small key-value bag hooks may extend for downstream diagnostics.
Annotations map[string]string
}
SubmitMeta carries core-owned metadata visible to submit hooks (no provider types).
type SubmitRejectError ¶
SubmitRejectError carries a deterministic rejection reason from a submit hook.
func (*SubmitRejectError) Error ¶
func (e *SubmitRejectError) Error() string
func (*SubmitRejectError) Unwrap ¶
func (e *SubmitRejectError) Unwrap() error
type ToolDecision ¶
type ToolDecision int
ToolDecision is the outcome of a tool reactor for one tool event.
const ( ToolDecisionUnspecified ToolDecision = iota ToolPass ToolRewrite ToolSwallow ToolReplace )
type ToolMeta ¶
type ToolMeta struct {
TraceID string
ALegID string
BLegID string
AttemptSeq int
Principal execview.PrincipalView
Scope scope.PrincipalScopeView
Session session.SessionView
Workspace workspace.WorkspaceView
}
ToolMeta carries stream and session context for tool reactors. Principal, Session, and Workspace are optional: the standard hook bus copies them from the request-scoped views attached to context when present (R9 policy context). Scope is the authoritative principal/scope attribution, carried separately from the legacy Principal projection (requirement 2.6). Internal/auxiliary origin and parent trace attribution are preserved through Scope.Origin and Scope.ParentTraceID; a zero Scope preserves local/anonymous identity semantics.
type ToolReactor ¶
type ToolReactor interface {
ID() string
Order() int
HandleToolEvent(ctx context.Context, te lipapi.ToolEvent, meta ToolMeta) (ToolDecision, lipapi.ToolEvent, error)
}
ToolReactor observes canonical tool lifecycle events and may rewrite output.
type ToolReactorErrorPolicy ¶
type ToolReactorErrorPolicy int
ToolReactorErrorPolicy selects how the hook bus treats a non-nil error from HandleToolEvent.
const ( ToolReactorErrorPolicyUnspecified ToolReactorErrorPolicy = iota // ToolReactorErrorsFailOpen preserves the current event and continues the chain (default). ToolReactorErrorsFailOpen // ToolReactorErrorsFailClosed stops the chain and surfaces the error to the stream runner. ToolReactorErrorsFailClosed // ToolReactorErrorsSwallowEvent drops the current tool event (same effect as ToolSwallow). ToolReactorErrorsSwallowEvent )
Source Files