Documentation
¶
Overview ¶
Package graphadapter defines the framework-agnostic event contract for governing external agent runtimes (LangGraph, LangChain, OpenAI SDK, etc.). External runtimes emit governance events to Talon and receive control decisions in response. LangGraph is a flagship use case but the contract is not LangGraph-specific.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrGraphRunStateLimitExceeded = errors.New("graph run state limit exceeded")
Functions ¶
This section is empty.
Types ¶
type Action ¶
type Action string
Action is the control decision Talon returns to the external runtime after evaluating a governance event.
const ( ActionAllow Action = "allow" ActionDeny Action = "deny" // Reserved for Phase 2 — not yet emitted by the adapter. ActionAbort Action = "abort" ActionOverrideModel Action = "override_model" ActionMutateArgs Action = "mutate_args" ActionRequireReview Action = "require_review" ActionRetry Action = "retry" )
type Adapter ¶
type Adapter struct {
// contains filtered or unexported fields
}
Adapter processes governance events from external agent runtimes and returns control decisions. It bridges the framework-agnostic event contract to Talon's policy engine and evidence store.
func NewAdapter ¶
NewAdapter creates a graph runtime adapter.
type Decision ¶
type Decision struct {
Action Action `json:"action"`
Allowed bool `json:"allowed"`
Reasons []string `json:"reasons,omitempty"`
OverrideModel string `json:"override_model,omitempty"`
MutatedArgs map[string]interface{} `json:"mutated_args,omitempty"`
MaxRetries int `json:"max_retries,omitempty"`
BudgetLeft float64 `json:"budget_left,omitempty"`
ReviewPlanID string `json:"review_plan_id,omitempty"`
EvidenceID string `json:"evidence_id,omitempty"`
}
Decision is the control response returned for every governance event. External runtimes MUST respect deny/abort decisions. Override and mutate decisions carry replacement values the runtime should apply.
type ErrorMeta ¶
type ErrorMeta struct {
Message string `json:"message"`
Code string `json:"code,omitempty"`
Retryable bool `json:"retryable"`
RetryCount int `json:"retry_count"`
}
ErrorMeta carries error context for retry governance.
type Event ¶
type Event struct {
Type EventType `json:"type"`
GraphRunID string `json:"graph_run_id"`
SessionID string `json:"session_id,omitempty"`
// TenantID is optional in client payloads. When tenant auth is enabled,
// the server binds tenant identity from request context and validates any
// provided tenant_id against it.
TenantID string `json:"tenant_id,omitempty"`
AgentID string `json:"agent_id"`
NodeID string `json:"node_id,omitempty"`
StepIndex int `json:"step_index"`
Attempt int `json:"attempt,omitempty"`
StateHash string `json:"state_hash,omitempty"`
Timestamp time.Time `json:"timestamp"`
RunMeta *RunMeta `json:"run_meta,omitempty"`
NodeMeta *NodeMeta `json:"node_meta,omitempty"`
ToolMeta *ToolMeta `json:"tool_meta,omitempty"`
Error *ErrorMeta `json:"error,omitempty"`
Result *ResultMeta `json:"result,omitempty"`
Cost float64 `json:"cost,omitempty"`
}
Event is the canonical governance event that any external agent runtime can emit to Talon. The same schema is used for notebook and standalone app integrations.
type EventType ¶
type EventType string
EventType identifies the lifecycle point of a governance event.
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler serves the /v1/graph/events HTTP endpoint. External runtimes POST governance events and receive control decisions synchronously.
func NewHandler ¶
NewHandler creates a graph events HTTP handler.
type NodeMeta ¶
type NodeMeta struct {
Name string `json:"name"`
Type string `json:"type,omitempty"` // "llm", "tool", "branch", "human"
Model string `json:"model,omitempty"`
InputLen int `json:"input_len,omitempty"`
}
NodeMeta carries metadata about a single graph node or step.
type ResultMeta ¶
type ResultMeta struct {
Status string `json:"status"` // "completed", "failed", "aborted"
OutputLen int `json:"output_len,omitempty"`
Cost float64 `json:"cost,omitempty"`
DurationMS int64 `json:"duration_ms,omitempty"`
InputTokens int `json:"input_tokens,omitempty"`
OutputTokens int `json:"output_tokens,omitempty"`
}
ResultMeta carries outcome information for step_end and run_end events.
type RunMeta ¶
type RunMeta struct {
Framework string `json:"framework"`
GraphName string `json:"graph_name,omitempty"`
NodeCount int `json:"node_count,omitempty"`
PlannedSteps []string `json:"planned_steps,omitempty"`
Model string `json:"model,omitempty"`
PlanID string `json:"plan_id,omitempty"`
}
RunMeta carries metadata about the overall graph execution, typically sent with run_start events.
Source Files