tools

type Capability struct {
	Class          ExecutionClass
	ResourceKey    string
	Timeout        time.Duration
	MaxResultBytes int
}

type CapableTool interface {
	Tool
	Capability(args json.RawMessage) Capability
}

type DefaultOptions struct {
	Workspace                                                                                    *workspace.Root
	RunAllowlist, RunAllowlistOnly, RunBlocklist, DisableTools                                   []string
	RunTimeoutSec, MaxReadBytes, MaxEditFileBytes, MaxOutputBytes, MaxWriteKB, MaxListDirEntries int
	// MaxToolResultBytes is the agent-loop tool-result ceiling
	// ([tools] max_tool_result_bytes). 0 = uncapped. When set, tools whose
	// honest output framing depends on not being tail-cut by the loop
	// (read_file's window header, find_references' JSON envelope) pre-clamp
	// their own budgets below it.
	MaxToolResultBytes int
	// MaxTavilyResponseBytes is the byte bound the Tavily-backed tools
	// (`search`'s provider path and `extract`) enforce on the response body
	// AND on their composed result, and declare as their result budget
	// ([tools] max_tavily_response_bytes). It is not a truncation cap: nothing
	// is ever cut, an over-bound response is refused with an explicit error.
	// 0 uses the built-in default. See web_response_budget.go.
	MaxTavilyResponseBytes int
	// MaxFetchKB bounds the body read by fetch_url (KiB, [tools]
	// max_fetch_kb). 0 (from config) means unlimited; <=0 at tool construction
	// means unlimited. When the registry constructs the tool, this value is
	// already resolved by the config layer (unset-or-0 becomes the built-in
	// 4096 KiB default; an operator's positive value passes through), so it is
	// passed through as-is - the registry applies no default of its own.
	MaxFetchKB int
	// MemoryBackstopBytes is the OOM guard when MaxReadBytes is uncapped (0).
	// 0 means the built-in 256 MiB default ([tools] memory_backstop_mb). Not a
	// context-cost cap; cannot be disabled by setting 0.
	MemoryBackstopBytes                          int
	TavilyAPIKey                                 string
	EnvAllowlist, EnvAllowlistOnly, EnvBlocklist []string
	EnvAllowKeywordBlocklist                     []string
	SecretPathPatterns, SecretPathExceptions     []string
	// WritePathDenylist blocks writes to workspace-relative files or directories.
	// It does not affect read tools.
	WritePathDenylist    []string
	SearchIgnorePatterns []string
	// MaxInspectRepositoryBytes bounds inspect_repository's output envelope
	// ([tools] max_inspect_repository_bytes). 0 at construction resolves to
	// the built-in 64 KiB default; the config layer already resolves an
	// unset-or-0 knob to that same default before this struct is built.
	MaxInspectRepositoryBytes int

	// DiagnosticsCommands maps a command name to the argv of a project
	// diagnostics command the get_diagnostics tool runs ([tools]
	// diagnostics_commands, wired by the config layer; the deprecated
	// [tools] diagnostics_command alias is folded into the "default" entry
	// there). Empty means the tool is not registered. "default" is the
	// reserved default entry; with no "default" and exactly one configured
	// command, that sole command is the default. The tool is advertised only
	// when the default command resolves against the run_command allowlist
	// (see registerDiagnosticsTool).
	DiagnosticsCommands map[string][]string

	// WorkflowTools are pre-built Phase 7 workflow tools. They register only
	// when the workspace has .mivia/workflows/ and no WorkflowToolsBuilder is
	// installed. Prefer tools.SetWorkflowToolsBuilder for production wiring so
	// this package does not import workflow/ledger (storage test import cycle).
	WorkflowTools []Tool

	// Memory is the durable agent memory backend. When nil, the memory tools
	// (memory_save, memory_search) are not registered. Wired by the CLI from
	// the resolved [memory] config; never constructed by a workspace file.
	Memory memory.Store
}

type EphemeralResultTool interface {
	Tool
	EphemeralResultMarker(args json.RawMessage) string
}

type ExecutionClass uint8

type PrivilegedTool interface {
	Tool
	Privileged()
}

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

type ResultBudgetTool interface {
	ResultBudgetBytes() int
}

type ScopeMode int

type ScopeOptions struct {
	// Mode selects root vs spawned policy.
	Mode ScopeMode
	// Allowlist, when non-nil, is the set of tool names the agent may use.
	// Nil means "no allowlist filter" (all non-denied tools pass). An empty
	// non-nil map means deny-all (after denylist/privileged rules).
	Allowlist map[string]struct{}
	// ExtraDenylist adds operator denylist names on top of the compiled set.
	// Only applied in ScopeSpawned (and always as name denials for non-privileged
	// tools in ScopeRoot when listed in Allowlist intersection paths).
	ExtraDenylist []string
}

type SkillResourceReader func(context.Context, string) (text, marker string, err error)

type TierCandidate struct {
	Name        string
	Description string
}

type Tiers struct {
	Core     []string
	Deferred []string
}

type Tool interface {
	Name() string
	Description() string
	Parameters() map[string]any
	Execute(ctx context.Context, args json.RawMessage) (string, error)
}

type WorkflowToolsBuilder func(opts DefaultOptions) []Tool