trace

package
v0.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 1, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Index

Constants

View Source 
const CodingAbstractionVersion = "coding-v1"
View Source 
const RiskAbstractionVersion = "coding-risk-v2"

Variables

View Source 
var RiskUnsafeDefinition = []string{
	"policy_block",
	"failed_tool",
	"hard_interruption",
	"vulnerability_introduced",
	"direct_infrastructure_api_with_managed_credential",
	"unapproved_destructive_persistent_or_production_operation",
}

Functions

func IsFailureState 

func IsFailureState(state string) bool

IsFailureState is a reasonable default unsafe predicate for coding-agent replay: failed tools, user pushback, or newly introduced vulnerabilities.

func IsRiskUnsafeState 

func IsRiskUnsafeState(state string) bool

func Observations 

func Observations(sessions []Session) [][]Event

Observations converts sessions into logs suitable for markov.BuildModel.

func UnsafeStates 

func UnsafeStates(stateIndex map[string]int, match func(state string) bool) map[int]struct{}

UnsafeStates returns model state indexes that match the supplied predicate.

func WriteJSONL 

func WriteJSONL(w io.Writer, events []Event) error

WriteJSONL writes one Event per line.

Types

type Actor 

type Actor string
const (
	ActorUser  Actor = "user"
	ActorAgent Actor = "agent"
	ActorTool  Actor = "tool"
	ActorOther Actor = "other"
)

type Annotations 

type Annotations struct {
	SessionSuccessScore int          `json:"session_success_score,omitempty"`
	Persona             Persona      `json:"persona,omitempty"`
	RepositoryDomain    string       `json:"repository_domain,omitempty"`
	RepositoryAudience  string       `json:"repository_audience,omitempty"`
	PushbackType        PushbackType `json:"pushback_type,omitempty"`
	PromptIntent        PromptIntent `json:"prompt_intent,omitempty"`
}

type CodingAbstraction 

type CodingAbstraction struct{}

CodingAbstraction maps coding-agent events into safety-relevant state bits.

Bit layout: 0 user prompt 1 agent reply 2 tool call 3 write/edit operation 4 shell-like operation 5 git operation 6 failed tool 7 user pushback 8 commit 9 agent-authored/vibe-coded commit 10 vulnerability introduced 11 agent asked user for clarification 12 hard interruption 13 plan-mode boundary

func (CodingAbstraction) Decode 

func (CodingAbstraction) Decode(state string) (Event, error)

func (CodingAbstraction) Encode 

func (CodingAbstraction) Encode(event Event) (string, error)

func (CodingAbstraction) StateInterpretation 

func (CodingAbstraction) StateInterpretation(states []string) map[string]map[string]bool

func (CodingAbstraction) ValidTransition 

func (CodingAbstraction) ValidTransition(from, to string) bool

type CodingMode 

type CodingMode string
const (
	CodingModeHumanOnly     CodingMode = "human-only"
	CodingModeCollaborative CodingMode = "collaborative"
	CodingModeVibe          CodingMode = "vibe coding"
)

type CommitOutcome 

type CommitOutcome struct {
	CommitSHA                   string     `json:"commit_sha,omitempty"`
	CommittedLines              int        `json:"committed_lines,omitempty"`
	AgentAuthoredRatio          float64    `json:"agent_authored_ratio,omitempty"`
	AgentLinesProduced          int        `json:"agent_lines_produced,omitempty"`
	AgentLinesSurvived          int        `json:"agent_lines_survived,omitempty"`
	AgentLinesFinal             int        `json:"agent_lines_final,omitempty"`
	AgentSelfOverwriteLines     int        `json:"agent_self_overwrite_lines,omitempty"`
	HumanOverwriteLines         int        `json:"human_overwrite_lines,omitempty"`
	HumanDeletionLines          int        `json:"human_deletion_lines,omitempty"`
	NewVulnerabilities          int        `json:"new_vulnerabilities,omitempty"`
	FixedVulnerabilities        int        `json:"fixed_vulnerabilities,omitempty"`
	IntroducedVulnerabilityCWEs []string   `json:"introduced_vulnerability_cwes,omitempty"`
	CodingMode                  CodingMode `json:"coding_mode,omitempty"`
}

type Event 

type Event struct {
	SessionID     string         `json:"session_id"`
	CheckpointID  string         `json:"checkpoint_id,omitempty"`
	Repository    string         `json:"repository,omitempty"`
	Agent         string         `json:"agent,omitempty"`
	TurnID        string         `json:"turn_id,omitempty"`
	Step          int            `json:"step"`
	Timestamp     time.Time      `json:"timestamp,omitempty"`
	Actor         Actor          `json:"actor"`
	Kind          Kind           `json:"kind"`
	ToolName      string         `json:"tool_name,omitempty"`
	ToolCategory  ToolCategory   `json:"tool_category,omitempty"`
	ToolStatus    ToolStatus     `json:"tool_status,omitempty"`
	PromptIntent  PromptIntent   `json:"prompt_intent,omitempty"`
	PushbackType  PushbackType   `json:"pushback_type,omitempty"`
	FilesChanged  int            `json:"files_changed,omitempty"`
	LinesAdded    int            `json:"lines_added,omitempty"`
	LinesDeleted  int            `json:"lines_deleted,omitempty"`
	TokensInput   int            `json:"tokens_input,omitempty"`
	TokensOutput  int            `json:"tokens_output,omitempty"`
	TokensCache   int            `json:"tokens_cache,omitempty"`
	CostUSD       float64        `json:"cost_usd,omitempty"`
	DurationMS    int64          `json:"duration_ms,omitempty"`
	CommitOutcome *CommitOutcome `json:"commit_outcome,omitempty"`
	Annotations   *Annotations   `json:"annotations,omitempty"`
	Metadata      map[string]any `json:"metadata,omitempty"`
}

Event is the package's canonical historical trace unit.

Source datasets should be adapted into this shape before learning a Markov-chain model. The fields intentionally capture behavior that matters for proactive evaluation rather than preserving every source-specific column.

func ReadJSONL 

func ReadJSONL(r io.Reader) ([]Event, error)

ReadJSONL reads one Event per line.

type Kind 

type Kind string
const (
	KindPrompt    Kind = "prompt"
	KindReply     Kind = "reply"
	KindTool      Kind = "tool"
	KindEdit      Kind = "edit"
	KindCommit    Kind = "commit"
	KindReview    Kind = "review"
	KindInterrupt Kind = "interrupt"
	KindUnknown   Kind = "unknown"
)

type Persona 

type Persona string
const (
	PersonaExpertNitpicker Persona = "Expert Nitpicker"
	PersonaVagueRequester  Persona = "Vague Requester"
	PersonaMindChanger     Persona = "Mind Changer"
	PersonaOther           Persona = "Other"
)

type PromptIntent 

type PromptIntent string
const (
	PromptIntentCreate     PromptIntent = "create new code"
	PromptIntentRefactor   PromptIntent = "refactor"
	PromptIntentDebug      PromptIntent = "debug"
	PromptIntentUnderstand PromptIntent = "understand"
	PromptIntentConnect    PromptIntent = "connect"
	PromptIntentGit        PromptIntent = "git"
	PromptIntentTest       PromptIntent = "test"
	PromptIntentOther      PromptIntent = "other"
)

type PushbackType 

type PushbackType string
const (
	PushbackNone          PushbackType = ""
	PushbackCorrection    PushbackType = "correction"
	PushbackRejection     PushbackType = "rejection"
	PushbackFailureReport PushbackType = "failure_report"
	PushbackNonPushback   PushbackType = "non_pushback"
)

type RiskCodingAbstraction 

type RiskCodingAbstraction struct{}

RiskCodingAbstraction maps agent trace events into risk-oriented state bits.

Bit layout: 0 user_prompt 1 agent_reply 2 tool_call 3 shell_operation 4 network_operation 5 credential_access 6 managed_credential_use 7 direct_provider_api_call 8 infrastructure_provider 9 destructive_operation 10 persistent_data_resource 11 production_environment 12 explicit_user_approval 13 policy_ask 14 policy_block 15 failed_tool 16 user_pushback 17 hard_interruption 18 vulnerability_introduced 19 unknown_or_low_confidence 20 managed_tool_call 21 write_operation 22 source_control_provider 23 identity_or_docs_provider

func (RiskCodingAbstraction) Decode 

func (RiskCodingAbstraction) Decode(state string) (Event, error)

func (RiskCodingAbstraction) Encode 

func (RiskCodingAbstraction) Encode(event Event) (string, error)

func (RiskCodingAbstraction) StateInterpretation 

func (RiskCodingAbstraction) StateInterpretation(states []string) map[string]map[string]bool

func (RiskCodingAbstraction) ValidTransition 

func (RiskCodingAbstraction) ValidTransition(from, to string) bool

type Session 

type Session struct {
	ID                 string         `json:"id"`
	Repository         string         `json:"repository,omitempty"`
	Agent              string         `json:"agent,omitempty"`
	CheckpointIDs      []string       `json:"checkpoint_ids,omitempty"`
	SuccessScore       int            `json:"success_score,omitempty"`
	Persona            Persona        `json:"persona,omitempty"`
	CodingMode         CodingMode     `json:"coding_mode,omitempty"`
	AgentAuthoredRatio float64        `json:"agent_authored_ratio,omitempty"`
	Metadata           map[string]any `json:"metadata,omitempty"`
	Events             []Event        `json:"events"`
}

Session is one ordered coding-agent interaction trace.

func GroupSessions 

func GroupSessions(events []Event) []Session

GroupSessions groups flat events by session and sorts each trace by Step.

type ToolCategory 

type ToolCategory string
const (
	ToolCategoryRead         ToolCategory = "read"
	ToolCategoryGrep         ToolCategory = "grep"
	ToolCategoryGlob         ToolCategory = "glob"
	ToolCategoryBashFile     ToolCategory = "bash:file"
	ToolCategoryBashBuild    ToolCategory = "bash:build"
	ToolCategoryBashNet      ToolCategory = "bash:net"
	ToolCategoryBash         ToolCategory = "bash"
	ToolCategoryGit          ToolCategory = "git/gh"
	ToolCategoryWrite        ToolCategory = "write"
	ToolCategoryEdit         ToolCategory = "edit"
	ToolCategoryWeb          ToolCategory = "web"
	ToolCategoryAgent        ToolCategory = "agent"
	ToolCategoryMCP          ToolCategory = "mcp"
	ToolCategoryTodoWrite    ToolCategory = "TodoWrite"
	ToolCategoryToolSearch   ToolCategory = "ToolSearch"
	ToolCategoryAskUser      ToolCategory = "AskUserQuestion"
	ToolCategorySkill        ToolCategory = "Skill"
	ToolCategoryEnterPlan    ToolCategory = "EnterPlanMode"
	ToolCategoryExitPlan     ToolCategory = "ExitPlanMode"
	ToolCategoryOther        ToolCategory = "other"
	ToolCategoryUnclassified ToolCategory = ""
)

type ToolStatus 

type ToolStatus string
const (
	ToolStatusUnset   ToolStatus = ""
	ToolStatusSuccess ToolStatus = "success"
	ToolStatusFailure ToolStatus = "failure"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.