intercept

Documentation

Overview

Package intercept implements the dual-protocol tool-call interception loop ratified by ADR-0008. When the upstream LLM emits a tool call that targets an Aileron-augmented action, the engine intercepts it, runs the action through an action.Executor, injects the synthetic tool result back into the conversation, and continues with a fresh upstream call until the LLM produces a final assistant message.

Tool calls for agent-declared tools pass through unchanged — the agent's host code executes them as it always has.

Index

• type Config
• type Engine
  • func New(cfg Config) (*Engine, error)
  • func (e *Engine) HandleAnthropic(w http.ResponseWriter, r *http.Request)
  • func (e *Engine) HandleOpenAI(w http.ResponseWriter, r *http.Request)

Types

type Config

type Config struct {
	OpenAIUpstream    *url.URL
	AnthropicUpstream *url.URL
	Actions           *action.Store
	Executor          action.Executor
	HTTPClient        *http.Client // optional; defaults to http.DefaultClient
	Log               *slog.Logger // optional; defaults to slog.Default()

	// Recorder writes audit events for every failure surfaced through
	// the gateway. Required — pass audit.NewRecorder(audit.NewMemStore(),
	// nil, nil) for a default in-memory recorder.
	Recorder audit.Recorder

	// RetryPolicy governs upstream retries per ADR-0010. Optional;
	// defaults to retry.DefaultPolicy().
	RetryPolicy retry.Policy

	// Clock is the time source used for retry backoff. Optional;
	// defaults to clock.System{}.
	Clock clock.Clock
}

Config groups the dependencies required to build an Engine. The constructor validates that the required fields are present so misconfiguration is caught at startup rather than on the first request.

type Engine

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

Engine runs the augmentation+interception loop for both OpenAI and Anthropic protocol shapes.

func New

func New(cfg Config) (*Engine, error)

New builds an Engine from a Config.

func (*Engine) HandleAnthropic

func (e *Engine) HandleAnthropic(w http.ResponseWriter, r *http.Request)

HandleAnthropic mirrors HandleOpenAI for the Anthropic Messages protocol. Tool calls arrive as `tool_use` content blocks on assistant messages; tool results inject as `tool_result` content blocks on a synthesized user message.

func (*Engine) HandleOpenAI

func (e *Engine) HandleOpenAI(w http.ResponseWriter, r *http.Request)

HandleOpenAI runs the augmentation + interception loop for an OpenAI Chat Completions request. The request body is read once, augmented with installed actions, and forwarded upstream. The upstream response is parsed; tool calls targeting Aileron-owned names are executed via the engine's Executor and the conversation continues with a fresh upstream call until the LLM produces a terminal assistant message. The final message is then written back to the agent — either as JSON or as a single-shot SSE stream depending on whether the original request set `stream: true`.

Note: during intercept rounds the engine forces upstream `stream: false` so the per-round response is a single JSON document. The agent still sees a streaming response (synthesized as SSE) when it asked for one. True upstream-side streaming preservation for non-intercepted text deltas is a future optimization.