text

type AgentSettings struct {
	Logger           *slog.Logger
	Level            slog.Level
	RuneLimit        int
	UsageRecorder    pub_models.CallUsageRecorder
	ToolCallRecorder pub_models.ToolCallRecorder
	// StrictMcpStartup marks the servers in Configurations.McpServers as
	// explicitly requested and load-bearing: a startup failure fails the whole
	// setup with a typed error instead of warn-and-degrade. pkg/agent sets it
	// when WithMcpServers was used; the CLI path never sets it (worklog
	// 2026-09-05-error-propagation, D13).
	StrictMcpStartup bool
}

type CallUsageRecorder = pub_models.CallUsageRecorder

type CompletedModelCall = pub_models.CompletedModelCall

type Configurations struct {
	Model        string `json:"model"`
	SystemPrompt string `json:"system-prompt"`
	Raw          bool   `json:"raw"`
	UseTools     bool   `json:"use-tools"`
	UseSkills    bool   `json:"-"`
	// CmdModePrompt is kept only for backwards compatibility with old config files.
	// It is ignored by clai as the `cmd` command has been removed.
	CmdModePrompt string `json:"cmd-mode-prompt"`
	// ToolOutputRuneLimit limits the amount of runes a tool may return
	// before clai truncates the output. Zero means no limit.
	ToolOutputRuneLimit int    `json:"tool-output-rune-limit"`
	SaveReplyAsConv     bool   `json:"save-reply-as-prompt"`
	ConfigDir           string `json:"-"`
	StdinReplace        string `json:"-"`
	Stream              bool   `json:"-"`
	ReplyMode           bool   `json:"-"`
	// DirReplyMode marks a directory-scoped reply (-dre). Unlike a plain -re (which
	// forks a fresh promoted id and must not record), -dre continues the bound
	// conversation in place, so it DOES upsert the directory history (see finalizer).
	DirReplyMode        bool            `json:"-"`
	Glob                string          `json:"-"`
	InitialChat         pub_models.Chat `json:"-"`
	UseProfile          string          `json:"-"`
	ProfilePath         string          `json:"-"`
	ProfileUseSkillsSet bool            `json:"-"`
	RequestedToolGlobs  []string        `json:"-"`
	// CmdBan is the per-run command ban list for the freetext command tools
	// (cmd, async_cmd; legacy aliases freetext_command, async_cmd_run).
	// Commands matching an entry are
	// refused before spawn (worklog 2026-08-02-cmd-ban-list). The cascade is
	// purely additive: textConfig.json + profile cmd-ban + flag -cmd-ban +
	// agent API; no source removes another source's bans.
	CmdBan []string `json:"cmd-ban"`
	// SummarizeConversations launches the in-flight conversation summarizer
	// on a conversation's first persist (worklog
	// 2026-09-09-conversation-summaries, D12).
	SummarizeConversations bool `json:"summarize-conversations"`
	// SummaryModel is the model the conversation summarizer uses; empty means
	// the resolution ladder (D22). The migrate tag surfaces the empty key in
	// upgraded files, so it must never carry omitempty.
	SummaryModel string `json:"summary-model" migrate:"true"`
	// SummaryJoinTimeout bounds the finalizer's wait for the in-flight
	// summary; zero means defaultSummaryJoinTimeout.
	SummaryJoinTimeout time.Duration `json:"-"`
	// CostWarnf receives the cost manager's and the cost enricher's
	// warnings; nil keeps ancli.Warnf. A querier whose output is discarded
	// routes them to its own trace (worklog
	// 2026-09-09-conversation-summaries, R2-03).
	CostWarnf func(format string, a ...any) `json:"-"`
	// ErrOut replaces the process stderr for the querier's MCP log sink; nil
	// keeps os.Stderr. A querier that may outlive its caller (the abandoned
	// in-flight summarizer) must never read the global stream (R2-09).
	ErrOut io.Writer `json:"-"`
	// TrustInput is the trusted input reader the composition root threads
	// through setup (the same reader skills.TrustPrompter reads from); the
	// authorization phase's printed-URL fallback reads a pasted
	// authorization code from it rather than the process standard input
	// directly (worklog 2026-10-02-mcp-connection-cost, phase 5). Nil
	// disables the paste fallback for the run.
	TrustInput io.Reader `json:"-"`
	// ShellContext is a context definition name for ASC (auto-append shell context).
	// When non-empty, clai will load <configDir>/shellContexts/<name>.json and insert
	// the rendered template block into the system prompt instead of the user prompt.
	ShellContext string `json:"-"`
	// PostProccessedPrompt which has had it\'s strings replaced etc
	PostProccessedPrompt string `json:"-"`

	// These are to allow tools to be injected via public package.
	Tools      []pub_models.LLMTool   `json:"-"`
	McpServers []pub_models.McpServer `json:"-"`
	// SkipAmbientMcpServers skips discovery of <configDir>/mcpServers/*.json;
	// servers passed in McpServers still start and keep their explicit or
	// ambient posture (worklog 2026-09-09-conversation-summaries, D18).
	SkipAmbientMcpServers bool                          `json:"-"`
	BaseTools             map[string]pub_models.LLMTool `json:"-"`
	RegisteredTools       map[string]struct{}           `json:"-"`
	MaxToolCalls          *int                          `json:"max-tool-calls,omitempty"`
	// Stoploss is the token stoploss policy for the run. Nil or
	// MaxTokens <= 0 disables the stoploss (no handover injection).
	Stoploss *Stoploss `json:"stoploss,omitempty"`

	// AgentSettings carries agent-only runtime settings (slog logger, level,
	// rune cap, recorder hooks) from pkg/agent into the querier. json:"-"
	// keeps it out of textConfig.json and the presence-based config merge
	// (worklog 2026-08-15-agent-slog-output, D7).
	AgentSettings *AgentSettings `json:"-"`

	// Out writer. Normally stdout, but may also be a file when invoked as a package
	Out io.Writer `json:"-"`

	// ResponseFormat configures structured output (json_object, json_schema).
	// When nil, no response_format is sent (defaults to text).
	ResponseFormat   *pub_models.ResponseFormat `json:"-"`
	SkillsDescriptor string                     `json:"-"`
	SkillLoader      SkillLoader                `json:"-"`

	// UseLookback gates the opt-in conversation lookback: the recent-conversations
	// descriptor plus the search/inspect/read tools. Resolved as
	// CLI (-lb/-lookback boolean) > profile (use_lookback) > default (false), and is only
	// effectively true when the CWD binding has recorded history.
	UseLookback bool `json:"use_lookback"`
	// LookbackDescriptor is the dir-scoped recent-conversations block injected into
	// the system prompt when the lookback is active.
	LookbackDescriptor string `json:"-"`
	// LookbackCWD is the canonical session working directory captured at setup,
	// used as the default search anchor for search_conversations.
	LookbackCWD string `json:"-"`
	// OutputIsTerminal decides the auth-timeout parameter's
	// terminal-dependent default: a mid-run authorization wait is bounded
	// when the session's output is a terminal, fail-fast otherwise, unless
	// a server's auth_timeout_seconds overrides it either way (worklog
	// 2026-10-02-mcp-connection-cost, phase 6, D22). nil means unset:
	// NewQuerier then derives it from the querier's own terminal check and
	// assigns it, without overwriting a caller-supplied value (R2-09). A
	// caller that cannot observe its own terminal-ness (every pkg/agent SDK
	// consumer, whose writer is always io.Discard) sets this explicitly
	// through pkg/agent.WithOutputIsTerminal instead of relying on the
	// writer-derived default.
	OutputIsTerminal *bool `json:"-"`
}

type CostManager interface {
	// Start the cost manager. Will return with errors on errCh and close readyCh once there is
	// a token price for the model
	Start(ctx context.Context) (readyCh <-chan struct{}, errCh <-chan error)

	// Enrich the chat with cost for the chat
	Enrich(chat pub_models.Chat) (pub_models.Chat, error)
}

type LoadedSkillRuntime struct {
	Name            string
	SourceClass     string
	RenderedBody    string
	UserVisibleBody string
	Description     string
	Warnings        []string
	EnabledTools    []string
	ActiveTools     map[string]pub_models.LLMTool
	ActivationErr   string
	RawArgs         string
}

type ModelNamer interface {
	ModelName() string
}

type ModelStepResult struct {
	AssistantText string
	ToolCalls     []pub_models.Call
	Usage         *pub_models.Usage
	StopRequested bool
	EndedNormally bool
}

type Profile struct {
	Name      string   `json:"name"`
	Model     string   `json:"model"`
	UseTools  bool     `json:"use_tools"`
	UseSkills *bool    `json:"use_skills,omitempty"`
	Tools     []string `json:"tools"`
	// CmdBan merges onto the file base in ProfileOverrides. An omitted or
	// explicitly empty list contributes nothing (purely additive cascade,
	// worklog 2026-08-02-cmd-ban-list R1-04 revision).
	CmdBan          []string                        `json:"cmd-ban,omitempty"`
	Prompt          string                          `json:"prompt"`
	SaveReplyAsConv *bool                           `json:"save-reply-as-conv,omitempty"`
	McpServers      map[string]pub_models.McpServer `json:"mcp_servers,omitempty"`
	ShellContext    string                          `json:"shell_context,omitempty"`
	UseLookback     *bool                           `json:"use_lookback,omitempty"`
}

type Querier[C models.StreamCompleter] struct {
	Raw bool

	Model C
	// contains filtered or unexported fields
}

type QueryCommandDeps struct {
	ConfigPrep func() (confDir string, err error)
	TrustInput func() io.Reader
	// ApplyMediaOverrides hands the media-tool flags to the domains owning
	// those tools (internal/audio today), which text must not import.
	ApplyMediaOverrides func(internal.MediaToolFlags) error
	// NewSummarizer builds the in-flight conversation summarizer; nil or a
	// constructor error attaches nothing (worklog
	// 2026-09-09-conversation-summaries, D26).
	NewSummarizer func(confDir string) (models.Summarizer, error)
}

type QuerySession struct {
	Chat               pub_models.Chat
	StartedAt          time.Time
	FinishedAt         time.Time
	PendingText        strings.Builder
	PendingReasoning   strings.Builder
	FinalAssistantText string
	FinalReasoningText string
	FinalUsage         *pub_models.Usage
	CompletedCalls     []CompletedModelCall
	ToolCallsUsed      int
	// PostHandoverToolCallsUsed counts tool calls made after the token
	// stoploss handover fired. It is the phase counter for the
	// max-tool-calls-after-handover wrap-up budget: the handover starts a
	// fresh allowance that pre-handover consumption never eats into.
	PostHandoverToolCallsUsed int
	// HandoverRequested is set once the token stoploss has injected the
	// handover user message. It switches the tool-budget phase: the
	// wrap-up allowance (max-tool-calls-after-handover) replaces the
	// pre-handover max-tool-calls budget.
	HandoverRequested   bool
	ShouldSaveReply     bool
	Raw                 bool
	Finalized           bool
	Failed              bool
	SawAnyText          bool
	SawStopEvent        bool
	LikelyGeminiPreview bool
	Line                string
	LineCount           int
}

type ShellContextDefinition struct {
	Shell         string            `json:"shell"`
	TimeoutMS     int               `json:"timeout_ms"`
	TimedOutValue string            `json:"timed_out_value"`
	ErrorValue    string            `json:"error_value"`
	Template      string            `json:"template"`
	Vars          map[string]string `json:"vars"`
}

type ShellContextRenderer struct {
	RunVar func(ctx context.Context, shell, cmd string, timeout time.Duration) (string, error)
	Warnf  func(format string, args ...any)
}

type SkillLoader interface {
	LoadSkill(context.Context, string, string, map[string]pub_models.LLMTool) (LoadedSkillRuntime, error)
}

type Stoploss struct {
	MaxTokens                 int    `json:"max-tokens"`
	MaxTokensHandoverMsg      string `json:"max-tokens-handover-instructions"`
	MaxToolCallsAfterHandover int    `json:"max-tool-calls-after-handover" migrate:"true"`
}

type ToolCall = pub_models.ToolCall

type ToolCallRecorder = pub_models.ToolCallRecorder

type ToolDecision struct {
	PatchedCall         pub_models.Call
	SkipExecution       bool
	TreatAsReturnToUser bool
}