agentcontext

package
v0.9.0 Latest Latest
Warning

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

 Go to latest Published: Oct 8, 2026 License: Apache-2.0 Imports: 28 Imported by: 0

Documentation

Overview

Package agentcontext preserves source-asserted agent records separately from kernel observations and analysis. Missing source information remains unknown.

Index

Constants

View Source 
const (
	MaxDiscoveryFiles  = 4096
	MaxDiscoveryVisits = 20000
	MaxDiscoveryBytes  = 256 << 20
)
View Source 
const (
	CurrentExecution = "current_execution"
	PriorContext     = "prior_context"
)
View Source 
const (
	ParserVersion = "context-parser/v9"
	MaxInputBytes = 128 << 20
	MaxLineBytes  = 40 << 20
	MaxRecords    = 25000
)
View Source 
const SchemaVersion = "agentprovenance.agent_context/v1"

Variables

View Source 
var ErrInvalidArgument = errors.New("invalid context argument")

Functions

func Number 

func Number(n int64) *int64

func ToolNodeID 

func ToolNodeID(e Entry) string

ToolNodeID namespaces a native call identity by run and actor. Transcript and hook channels can describe the same invocation, while separate runs cannot overwrite each other's graph nodes when a harness reuses a call ID.

Types

type Candidate 

type Candidate struct {
	Path            string       `json:"path"`
	SessionID       string       `json:"session_id"`
	ParentSessionID string       `json:"parent_session_id,omitempty"`
	AgentID         string       `json:"agent_id,omitempty"`
	Workdir         string       `json:"workdir,omitempty"`
	CreatedAt       string       `json:"created_at,omitempty"`
	ModifiedAt      time.Time    `json:"modified_at"`
	Size            int64        `json:"size"`
	Cursor          SourceCursor `json:"cursor"`
	Issue           string       `json:"issue,omitempty"`
}

type ContentRef 

type ContentRef struct {
	Ref       string `json:"ref,omitempty"`
	Bytes     *int64 `json:"bytes"`
	SHA256    string `json:"sha256,omitempty"`
	MediaType string `json:"media_type,omitempty"`
	Redacted  bool   `json:"redacted"`
	State     string `json:"state"`
	Reason    string `json:"reason,omitempty"`
}

type Counts 

type Counts struct {
	Discovered   *int64 `json:"discovered"`
	Matched      *int64 `json:"matched"`
	Read         *int64 `json:"read"`
	Parsed       *int64 `json:"parsed"`
	Stored       *int64 `json:"stored"`
	Duplicates   *int64 `json:"duplicates"`
	Truncated    *int64 `json:"truncated"`
	Failed       *int64 `json:"failed"`
	Unrecognized *int64 `json:"unrecognized"`
	Deferred     *int64 `json:"deferred"`
}

Counts are observations over one processing range, not estimates of all activity. Nil means unknown; a successful empty scan can explicitly report 0.

type Coverage 

type Coverage struct {
	SchemaVersion string      `json:"schema_version"`
	ID            string      `json:"id"`
	RunID         string      `json:"run_id"`
	Source        Source      `json:"source"`
	Status        Status      `json:"status"`
	ObservedAt    string      `json:"observed_at"`
	LastSuccessAt string      `json:"last_success_at,omitempty"`
	StartedAt     string      `json:"started_at,omitempty"`
	EndedAt       string      `json:"ended_at,omitempty"`
	FirstLine     int64       `json:"first_line,omitempty"`
	LastLine      int64       `json:"last_line,omitempty"`
	Counts        Counts      `json:"counts"`
	Issues        []Issue     `json:"issues"`
	MissingFields []string    `json:"missing_fields"`
	ObjectHash    string      `json:"object_hash,omitempty"`
	PriorContext  *PriorRange `json:"prior_context,omitempty"`
}

type DiscoverOptions 

type DiscoverOptions struct {
	Harness string
	Root    string
	// CatalogRoot optionally locates Codex state catalogs outside the scan root.
	// No ambient home directory is consulted for explicitly acquired sources.
	CatalogRoot string
	Workdir     string
	SessionID   string
	// Snapshot captures a pre-execution cursor for candidates in this workdir.
	Snapshot bool
}

type Entry 

type Entry struct {
	SchemaVersion string `json:"schema_version"`
	ID            string `json:"id"`
	RunID         string `json:"run_id"`
	Source        Source `json:"source"`
	SourceKey     string `json:"source_key"`
	Sequence      int64  `json:"sequence"`
	// SourceOrdinal is the normalized record's position within its physical
	// source line. Zero means older evidence did not record that position.
	SourceOrdinal  int64      `json:"source_ordinal,omitempty"`
	Kind           string     `json:"kind"`
	Role           string     `json:"role,omitempty"`
	AgentID        string     `json:"agent_id,omitempty"`
	ToolCallID     string     `json:"tool_call_id,omitempty"`
	ToolName       string     `json:"tool_name,omitempty"`
	Status         string     `json:"status,omitempty"`
	RecordedAt     string     `json:"recorded_at,omitempty"`
	Content        ContentRef `json:"content"`
	RawContent     ContentRef `json:"raw_content"`
	MissingFields  []string   `json:"missing_fields,omitempty"`
	EvidenceRefs   []string   `json:"evidence_refs,omitempty"`
	ObjectHash     string     `json:"object_hash,omitempty"`
	CreatedAt      string     `json:"created_at,omitempty"`
	ExecutionScope string     `json:"execution_scope,omitempty"`
}
type EntryLinks struct {
	SchemaVersion string      `json:"schema_version"`
	RunID         string      `json:"run_id"`
	EntryID       string      `json:"entry_id"`
	Basis         string      `json:"basis"`
	Links         []GraphLink `json:"links"`
	HasMore       bool        `json:"has_more"`
	Reason        string      `json:"reason,omitempty"`
}
type GraphLink struct {
	NodeID   string `json:"node_id"`
	Relation string `json:"relation"`
}

type Inventory 

type Inventory struct {
	Harness     string      `json:"harness"`
	Root        string      `json:"root"`
	CatalogRoot string      `json:"catalog_root,omitempty"`
	Candidates  []Candidate `json:"candidates"`
	Complete    bool        `json:"complete"`
	Issues      []Issue     `json:"issues"`
}

Inventory contains identities and resume boundaries, never conversation text. An incomplete inventory cannot establish a unique automatic binding.

func Discover 

func Discover(ctx context.Context, opts DiscoverOptions) (Inventory, error)

type Issue 

type Issue struct {
	Code  string `json:"code"`
	Line  int64  `json:"line,omitempty"`
	Field string `json:"field,omitempty"`
	Scope string `json:"scope,omitempty"`
}

type Overview 

type Overview struct {
	SchemaVersion   string                        `json:"schema_version"`
	RunID           string                        `json:"run_id"`
	Coverage        []Coverage                    `json:"coverage"`
	Messages        *int64                        `json:"messages"`
	ToolCalls       *int64                        `json:"tool_calls"`
	ToolResults     *int64                        `json:"tool_results"`
	Snapshots       *int64                        `json:"snapshots"`
	HasMoreSources  bool                          `json:"has_more_sources"`
	RuntimeCoverage observability.RuntimeCoverage `json:"runtime_coverage"`
}

type Page 

type Page struct {
	SchemaVersion string  `json:"schema_version"`
	RunID         string  `json:"run_id"`
	Entries       []Entry `json:"entries"`
	NextCursor    string  `json:"next_cursor,omitempty"`
	HasMore       bool    `json:"has_more"`
	Limit         int     `json:"limit"`
}

type PageOptions 

type PageOptions struct {
	RunID            string
	SessionID        string
	SourceID         string
	Kind             string
	ToolCallID       string
	EntryID          string
	NodeID           string
	Group            string
	Cursor           string
	Limit            int
	IncludeRevisions bool
}

type ParseBudget 

type ParseBudget struct {
	InputBytes int64
	Records    int
}

ParseBudget bounds a sequence of source imports, including decompressed input and records that are later rejected or deduplicated. It is not concurrency-safe. A nil budget keeps the normal per-source limits; zero means exhausted.

type ParseOptions 

type ParseOptions struct {
	Harness         string
	Path            string
	SessionID       string
	ParentSessionID string
	AgentID         string
	Binding         string
	BindingEvidence []string
	// AfterLine is a physical source cursor captured before a resumed execution.
	// Earlier records are retained as prior context, never current execution.
	AfterLine int64
	Cursor    *SourceCursor
	Budget    *ParseBudget
}

type Parsed 

type Parsed struct {
	Source   Source
	Records  []Record
	Coverage Coverage
}

func Parse 

func Parse(ctx context.Context, r io.Reader, opts ParseOptions) (Parsed, error)

Parse reads a bounded physical transcript without consulting current agent configuration. Diagnostics intentionally contain codes/positions, never input.

type PriorRange 

type PriorRange struct {
	FirstLine     int64    `json:"first_line"`
	LastLine      int64    `json:"last_line"`
	StartedAt     string   `json:"started_at,omitempty"`
	EndedAt       string   `json:"ended_at,omitempty"`
	Counts        Counts   `json:"counts"`
	MissingFields []string `json:"missing_fields"`
}

PriorRange describes the retained prefix separately from the current range. These records supply historical context, not evidence of execution in this run.

type Record 

type Record struct {
	Key            string
	Sequence       int64
	SourceOrdinal  int64
	Kind           string
	Role           string
	AgentID        string
	ToolCallID     string
	ToolName       string
	Status         string
	RecordedAt     string
	Body           *string
	RawBody        *string
	MediaType      string
	MissingReason  string
	MissingFields  []string
	ExecutionScope string
	// Parsed values are position-specific, including unknown values. Nil lets
	// explicit Record callers use the source defaults.
	Workdir            *string
	ApplicationVersion *string
}

Record is a parser's transient output. Body never appears in the entry index or diagnostics: it is redacted and stored as bounded content-addressed chunks.

type SaveResult 

type SaveResult struct {
	Stored     int      `json:"stored"`
	Duplicates int      `json:"duplicates"`
	Coverage   Coverage `json:"coverage"`
}

type SelectOptions 

type SelectOptions struct {
	Workdir   string
	SessionID string // explicit native identity, including resume
	Path      string // explicit transcript; no directory heuristic
	StartedAt time.Time
	EndedAt   time.Time
}

type SelectedSource 

type SelectedSource struct {
	Candidate
	AfterLine       int64         `json:"after_line"`
	Binding         string        `json:"binding"`
	BindingEvidence []string      `json:"binding_evidence"`
	ResumeCursor    *SourceCursor `json:"resume_cursor,omitempty"`
}

func (SelectedSource) ParseOptions 

func (s SelectedSource) ParseOptions(harness string) ParseOptions

type Selection 

type Selection struct {
	Sources []SelectedSource `json:"sources"`
	Status  Status           `json:"status"`
	Issues  []Issue          `json:"issues"`
}

func SelectSources 

func SelectSources(ctx context.Context, before, after Inventory, opts SelectOptions) Selection

SelectSources never chooses by mtime. Without a native identity, only one new root session with matching cwd and a source timestamp in the run window can match. A resumed session requires an explicit identity and a verified prefix.

type Service 

type Service struct {
	DB    *sql.DB
	Paths store.Paths
}

func (Service) CompareSnapshots 

func (s Service) CompareSnapshots(ctx context.Context, runID, leftID, rightRunID, rightID string) (SnapshotComparison, error)

func (Service) Entries 

func (s Service) Entries(ctx context.Context, opts PageOptions) (Page, error)

func (Service) ImportFile 

func (s Service) ImportFile(ctx context.Context, runID string, opts ParseOptions) (SaveResult, error)
func (s Service) Links(ctx context.Context, runID, entryID string) (EntryLinks, error)

Links exposes existing graph relationships, never a new matching inference. A result without a projected call deliberately has no execution destination.

func (Service) Overview 

func (s Service) Overview(ctx context.Context, runID string) (Overview, error)

func (Service) ReadHandler 

func (s Service) ReadHandler() http.Handler

ReadHandler is shared by the local dashboard and daemon. It only resolves registered objects within the requested run; it never accepts disk paths.

func (Service) Save 

func (s Service) Save(ctx context.Context, runID string, src Source, records []Record, report Coverage) (SaveResult, error)

Save atomically appends immutable record revisions and a processing report. Re-reading unchanged records is a no-op; a late result or changed snapshot is a new revision. Neither a retry nor a parse failure deletes earlier evidence.

type SnapshotChange 

type SnapshotChange struct {
	Path   string        `json:"path"`
	Before SnapshotValue `json:"before"`
	After  SnapshotValue `json:"after"`
}

type SnapshotComparison 

type SnapshotComparison struct {
	SchemaVersion string           `json:"schema_version"`
	Scope         string           `json:"scope"`
	Status        string           `json:"status"`
	Left          Entry            `json:"left"`
	Right         Entry            `json:"right"`
	Changes       []SnapshotChange `json:"changes"`
	HasMore       bool             `json:"has_more"`
	Reason        string           `json:"reason,omitempty"`
}

SnapshotComparison compares recorded values, not effective permissions. An absent field means "not recorded here", never allowed, denied, or revoked.

type SnapshotValue 

type SnapshotValue struct {
	Present   bool   `json:"present"`
	Preview   string `json:"preview,omitempty"`
	Truncated bool   `json:"truncated"`
	SHA256    string `json:"sha256,omitempty"`
}

type Source 

type Source struct {
	ID                 string   `json:"id"`
	Harness            string   `json:"harness"`
	Channel            string   `json:"channel,omitempty"`
	SessionID          string   `json:"session_id"`
	ParentSessionID    string   `json:"parent_session_id,omitempty"`
	AgentID            string   `json:"agent_id,omitempty"`
	Path               string   `json:"path,omitempty"`
	ParserVersion      string   `json:"parser_version"`
	ApplicationVersion string   `json:"application_version,omitempty"`
	FormatVersion      string   `json:"format_version,omitempty"`
	Binding            string   `json:"binding"`
	BindingEvidence    []string `json:"binding_evidence,omitempty"`
	Workdir            string   `json:"workdir,omitempty"`
}

type SourceCursor 

type SourceCursor struct {
	Lines  int64  `json:"lines"`
	Bytes  int64  `json:"bytes"`
	SHA256 string `json:"sha256"`
	Valid  bool   `json:"valid"`
}

A cursor hashes complete decompressed physical lines. A growing final line stays outside the prefix and is retried, including in concatenated zstd files.

type Status 

type Status string
const (
	Disabled          Status = "disabled"
	NoInput           Status = "no_input"
	Empty             Status = "empty"
	OK                Status = "ok"
	Partial           Status = "partial"
	Failed            Status = "failed"
	Ambiguous         Status = "ambiguous"
	LegacyNotRecorded Status = "legacy_not_recorded"
)

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.