agentsession

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

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

type Config struct {
	// Root is the repository the run reads, absolute. No session reads
	// outside it, whatever a caller's options say.
	Root string
	// Work is what every session is one agent of, as a noun phrase, said in its
	// system prompt ([SessionOrder.Work]): sec's "a security audit".
	Work string
	// SessionModel answers the agent sessions — the hunters, tracers and
	// provers that read the code — and AIModel the single structured calls:
	// the duplicate checks, the exploit reasoning, the compliance mapping.
	// Empty leaves the choice to the model API, which answers on the run's
	// work seat.
	SessionModel, AIModel string
	// Sessions is how many agent sessions run at once across the whole run,
	// and Calls how many single calls. sec-af's own fan-outs multiply — four
	// hunters each enriching five locations — and the old harness capped its
	// processes at eight for the same reason.
	Sessions, Calls int
	// MaxTurns bounds one session's turns; sec-af's own default was fifty.
	MaxTurns int
	// SessionWall bounds one session's time; sec-af's harness waited thirty
	// minutes.
	SessionWall time.Duration
	// Policy is how every session reads and answers ([Policy]).
	Policy Policy
	// Limits is each agent's own turns and time, by the options its session
	// was started with; a zero field falls back to MaxTurns or SessionWall.
	// Nil gives every agent those two.
	//
	// EACH AGENT IS BOUNDED BY WHAT ITS OWN WORK TAKES. One cap for every agent
	// was too short for a scanner that walks the repository and far too long
	// for a profiler that reads three files: /review's reviewers spent fifty turns
	// at twenty seconds each where a dozen would have done, and sec's
	// scanners were the ones cut at fifty. The program knows its agents, so the
	// figures are its own.
	Limits func(appx.HarnessOptions) Limits
	// Watch hears every session, call and note as it ends, for the task's
	// page. Nil hears nothing.
	Watch *Watch
}

type Limits struct {
	Turns int
	Wall  time.Duration
	// AnswerReserve is part of Wall, not extra time. Zero preserves the
	// program's existing reading policy.
	AnswerReserve time.Duration
}

type Policy struct {
	// StructuredAnswers opts schema-bound final turns into native formatting
	// only when the profile's catalog publishes support. False keeps the
	// program's existing prompt-only behavior.
	StructuredAnswers bool
	// FollowUps is how many times an answer that does not meet its schema is
	// asked for again.
	FollowUps int
	// ContextChars is how much a session's transcript may hold before it is
	// told to stop reading and answer.
	ContextChars int
	// AnswerNow is what a session is told when its turns or its room run out:
	// to stop reading and answer with what it has.
	AnswerNow string
	// Tools is what one call of each read-only tool may answer.
	Tools ToolLimits
}

type RefusedError struct {
	// Ceiling is the run's dollar ceiling; otherwise the key was refused.
	Ceiling bool
	Code    int
	Message string
}

type Request struct {
	Model    string
	Thread   string
	Messages []ai.Message
	Tools    []ai.ToolDefinition
	// ResponseFormat asks for a JSON answer of one schema; nil is free text.
	ResponseFormat *ai.ResponseFormat
}

type SessionOrder struct {
	Model  string
	Thread string
	// Root is the repository, absolute; every tool reads only below it.
	Root string
	// Work is what the session is one agent of, as a noun phrase: sec's
	// "a security audit". Empty says only that it works on the repository.
	Work   string
	Prompt string
	// Schema is the JSON Schema the answer must meet; nil is a free-text
	// answer, which sec-af's chain correlation asks for.
	Schema   map[string]any
	MaxTurns int
	// Wall is the session's own time bound; zero is none past the context's.
	Wall time.Duration
	// AnswerReserve stops reading this long before the existing deadline, so
	// the session can answer from completed observations. Zero reserves none.
	AnswerReserve time.Duration
	// Policy is how the session reads and answers; every limit is required.
	Policy Policy
	// contains filtered or unexported fields
}

type SessionResult struct {
	// Text is the answer as the model wrote it.
	Text string
	// JSON is the answer's object when a schema was asked for and met.
	JSON json.RawMessage
	// Failed is why a session that ran did not give an answer of the shape
	// asked for; empty for one that did.
	Failed   string
	Turns    int
	Tools    int
	CostUSD  float64
	Duration time.Duration
}

type ToolLimits struct {
	// ReadLines and ReadBytes are the most lines and bytes one read_file
	// answers; ReadLineRunes the most of one line it shows.
	ReadLines, ReadBytes, ReadLineRunes int
	// ListEntries is the most entries one list_dir answers, and GlobMatches
	// the most paths one glob answers.
	ListEntries, GlobMatches int
	// GrepMatches is the most lines one grep answers, GrepFileBytes the
	// largest file it reads, and GrepLineRunes how much of a matching line it
	// quotes.
	GrepMatches, GrepFileBytes, GrepLineRunes int
}

type Watch struct {
	// Session is one agent session that ended: its label (the agent that ran
	// it, such as `hunt-scan`), how it went, and the error that stopped it
	// before it could answer.
	Session func(label string, result SessionResult, err error)
	// Note is one of sec-af's progress notes, with its tags.
	Note func(message string, tags []string)
	// Call is one single structured call that ended: the title of the schema
	// its answer took (`VerdictDecision`), and the error that stopped it.
	Call func(schema string, err error)
}