tools

type ArtifactConfig struct {
	// Workspace reads the artifact bytes the agent names. Required.
	Workspace *localtools.Workspace
	// Uploader stores large images + non-image files and returns a vfs_ref. nil →
	// inline images only; non-image files error.
	Uploader ArtifactUploader
	// InlineMaxBytes is the image inline-vs-upload threshold (<=0 → 128 KiB).
	InlineMaxBytes int
	// MaxBytes hard-caps a single artifact read (<=0 → 32 MiB).
	MaxBytes int
	// SessionDir, when set, returns the per-(thread,context) working directory a
	// code session writes relative files into (e.g. sahara's
	// /sahara/sessions/<key>). A RELATIVE artifact path is resolved against it
	// first — so a file a kernel saved with a bare name (plt.savefig('p.png')) is
	// found — falling back to the workspace root. nil (or "" result) → paths
	// resolve against the workspace root only (the prior behavior). The harness
	// stays scheme-agnostic; the distribution owns the path derivation.
	SessionDir func(threadID, context string) string
}

type ArtifactUploader interface {
	Upload(ctx context.Context, addr protocol.MessageAddress, name, mimeType string, data []byte) (vfsRef string, err error)
}

type AuditRecord struct {
	CallID        string       `json:"call_id"`
	ToolName      string       `json:"tool_name"`
	Decision      DecisionCode `json:"decision"`
	Reason        string       `json:"reason"`
	AuditCode     string       `json:"audit_code"`
	ArgumentsHash string       `json:"arguments_hash"`
}

type AuditSink interface {
	Record(ctx context.Context, record AuditRecord) error
}

type CommandDecider interface {
	DecideCommand(req CommandRequest) CommandDecision
}

type CommandDecision struct {
	Decision
	MatchedRuleID    string
	MatchedPrefix    []string
	MatchedRules     []CommandRuleMatch
	ReadOnly         bool
	HostExecutable   string
	ResolvedProgram  string
	WorkspaceRoot    string
	WorkingDirectory string
	EnvKeys          []string
}

type CommandDelegate interface {
	RunCommand(ctx context.Context, spec localtools.CommandSpec) (localtools.CommandResult, error)
}

type CommandPattern struct {
	Tokens []CommandToken
}

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

type CommandPolicyConfig struct {
	Rules                  []CommandRule
	HostExecutables        []HostExecutable
	ResolveHostExecutables bool
	DefaultDecision        DecisionCode
}

type CommandRequest struct {
	Argv          []string
	WorkspaceRoot string
	CWD           string
	Env           []string
}

type CommandRule struct {
	ID             string
	Decision       DecisionCode
	Reason         string
	AuditCode      string
	Pattern        CommandPattern
	HostExecutable string
	ReadOnly       bool
	Match          [][]string
	NotMatch       [][]string
	EnvAllowlist   []string
}

type CommandRuleMatch struct {
	RuleID          string       `json:"rule_id"`
	MatchedPrefix   []string     `json:"matched_prefix"`
	Decision        DecisionCode `json:"decision"`
	Reason          string       `json:"reason"`
	AuditCode       string       `json:"audit_code"`
	ReadOnly        bool         `json:"read_only"`
	HostExecutable  string       `json:"host_executable,omitempty"`
	ResolvedProgram string       `json:"resolved_program,omitempty"`
}

type CommandToken struct {
	Literal      string
	Alternatives []string
}

type ConcurrencyClass int

type Decision struct {
	Code      DecisionCode `json:"code"`
	Reason    string       `json:"reason"`
	AuditCode string       `json:"audit_code"`
}

type DecisionCode string

type Descriptor struct {
	Name        string
	Description string
	Parameters  json.RawMessage // JSON-schema object; empty => {"type":"object"}
	// CatalogKind is the portable descriptor kind for dynamically published
	// tools. Empty defaults to "remote" in the ToolProvider compatibility
	// adapter.
	CatalogKind string
	// CatalogMeta is provider-owned metadata that is admitted as part of the
	// immutable catalog entry and returned to that same provider at invocation.
	// It is never exposed as model arguments. Transport adapters use it to carry
	// an upstream exact reference through a wrapper catalog without trusting
	// caller-supplied routing fields.
	CatalogMeta map[string]json.RawMessage
	// Effect is the highest admitted portable side-effect class. Empty defaults
	// conservatively to execute; providers should set it when they can classify
	// the tool more precisely.
	Effect spec.ToolEffect
	// Trust is the authorization hint for the tool. Zero value (TrustDefault)
	// leaves authorization to the runtime policy; a provider may stamp a stronger
	// hint (a later stage — no local descriptor sets it today).
	Trust TrustLevel
	// Concurrency is the tool's neutral runtime concurrency contract. It is not
	// part of the model-facing function schema. Unspecified is sequential.
	Concurrency ConcurrencyClass
}

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

type EffectLookup func(tool string) (spec.ToolEffect, bool)

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

type FileChange struct {
	Path string `json:"path"`
	Kind string `json:"kind"`
}

type FileDelegate interface {
	ReadFile(ctx context.Context, path string, maxBytes int64) (string, error)
	WriteFile(ctx context.Context, path, content string) error
	EditFile(ctx context.Context, path, oldText, newText string) error
}

type GrantStore interface {
	// ListGranted returns the tools durably authorized for a workspace.
	ListGranted(ctx context.Context, workspaceID string) ([]string, error)
	// Grant durably authorizes tool for workspaceID.
	Grant(ctx context.Context, workspaceID, tool string) error
	// IsGranted reports whether tool is durably authorized for workspaceID.
	// Used by the approval slow-path to short-circuit a prompt when a prior
	// "always" grant already exists in durable storage.
	IsGranted(ctx context.Context, workspaceID, tool string) (bool, error)
}

type Handler interface {
	Invoke(ctx context.Context, req Request) (Result, error)
}

type HandlerFunc func(ctx context.Context, req Request) (Result, error)

type HostExecutable struct {
	Name  string
	Paths []string
}

type InjectImageConfig struct {
	// Workspace reads the image bytes the agent names. Required.
	Workspace *localtools.Workspace
	// SessionDir, when set, returns the per-(thread,context) working directory a
	// code session writes relative files into (sahara's /sahara/sessions/<key>).
	// A RELATIVE image path resolves against it first, falling back to the
	// workspace root. nil → workspace-root only. Shares the artifact tool's
	// derivation; the distribution owns it.
	SessionDir func(threadID, context string) string
	// MaxBytes hard-caps a single injected image read (<=0 → 5 MiB).
	MaxBytes int
	// MaxImageEdge, when > 0, downscales an injected image so its longest edge is
	// <= MaxImageEdge before it's inlined as a data_uri — bounding the vision-token
	// cost of a high-resolution screenshot / PDF-page render. Only the model-bound
	// copy is scaled; the on-disk artifact is untouched. <=0 → no downscale.
	MaxImageEdge int
}

type LocalConfig struct {
	Workspace     *localtools.Workspace
	Python        string
	Exa           *localtools.ExaClient
	Timeout       time.Duration
	MaxOutput     int
	CommandPolicy CommandDecider
	// OutputArchiveLimit bounds the bytes one truncated command retains in the
	// recovery archive. 0 uses DefaultOutputArchiveLimit; negative disables
	// archiving (the truncation marker is still emitted — a silent cut is the
	// bug, the archive is the remedy).
	OutputArchiveLimit int
	// OutputArchiveDir is the workspace-relative directory archives are written
	// to. Empty uses DefaultOutputArchiveDir.
	OutputArchiveDir string
}

type MCPCaller interface {
	CallTool(ctx context.Context, server string, tool string, args json.RawMessage) (mcp.CallToolResult, error)
}

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

type MCPProviderConfig struct {
	Caller  MCPCaller
	Servers []string
}

type MCPResourceConfig struct {
	RegistryName string
	ServerName   string
	Client       mcp.ResourceClient
}

type MCPToolConfig struct {
	RegistryName string
	ServerName   string
	ToolName     string
	Caller       MCPCaller
}

type MemoryAuthority struct {
	GrantID     string
	SubjectType string
	SubjectID   string
}

type MemoryHit struct {
	ID      string  `json:"id"`
	Content string  `json:"content"`
	Score   float64 `json:"score"`

	// Detail fields — populated by memory_get (fetch-by-id) to give the model
	// full context + provenance; memory_search leaves them empty so scan results
	// stay lean (omitempty drops them). Document provenance (source filename,
	// document id, page) lives in Metadata/Tags for ingested memories.
	Type           string         `json:"type,omitempty"`
	Subtype        string         `json:"subtype,omitempty"`
	Tags           []string       `json:"tags,omitempty"`
	Metadata       map[string]any `json:"metadata,omitempty"`
	Abstract       string         `json:"abstract,omitempty"`
	SourceMemoryID string         `json:"source_memory_id,omitempty"`
	CreatedAt      string         `json:"created_at,omitempty"`
}

type MemoryRecaller interface {
	Recall(ctx context.Context, auth MemoryAuthority, workspace, query string, limit int) ([]MemoryHit, error)
	GetMemory(ctx context.Context, auth MemoryAuthority, id string) (MemoryHit, error)
}

type ModelPreferenceFunc func(name string) bool

type PartEmitter interface {
	// UpsertPart streams part: appended the first time its id is seen, or merged
	// in place (part_updated) on subsequent calls with the same id. A part with
	// no id is appended each call. The latest version of each id-bearing part is
	// folded into the finalized assistant message.
	UpsertPart(ctx context.Context, part protocol.ContentPart) error
}

type PatchFileDelegate interface {
	ApplyPatch(ctx context.Context, operations []localtools.PatchOperation) ([]localtools.PatchChange, error)
}

type Policy interface {
	Decide(req Request) Decision
}

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

type ReadOnlyAutoApprove struct {
	Base   Policy
	Effect EffectLookup
}

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

type RemoteConfig struct {
	Invoker RemoteInvoker
	Policy  Policy
	Audit   AuditSink
}

type RemoteInvoker interface {
	InvokeTool(ctx context.Context, envelope protocol.ToolInvokeEnvelope) (Result, error)
}

type Request struct {
	CallID string
	// MessageID is the id of the assistant message that carries this tool call.
	// Tools that create cross-thread back-refs (spawn_subagent) record it as the
	// parent MESSAGE id; the tool CallID alone doesn't identify the enclosing
	// message. Empty when the caller doesn't supply it.
	MessageID string
	Name      string
	Arguments json.RawMessage
	Addr      protocol.MessageAddress
	// Authority is the turn's OBO grant, injected by the session so tools (e.g.
	// memory_search) act on behalf of the turn's user with a fresh grant.
	Authority MemoryAuthority
	// Approved marks a call the user just authorized via the approval flow, so
	// the registry bypasses the policy gate for this single invocation. (Durable
	// session/always grants are recorded separately in the policy.)
	Approved bool
	// ToolRef is the exact provider-qualified catalog entry selected for a
	// dynamically surfaced tool. It is nil for the standalone static-registry
	// path and older bare-name callers.
	ToolRef *protocol.ToolReference
	// CatalogMeta is copied from the exact catalog entry after the independent
	// invocation-time resolution succeeds. It is trusted admitted metadata, not
	// model input. Providers may use it to validate an upstream exact reference.
	CatalogMeta map[string]json.RawMessage
}

type Result struct {
	CallID   string          `json:"call_id"`
	Name     string          `json:"name"`
	Payload  json.RawMessage `json:"payload"`
	IsError  bool            `json:"is_error"`
	Metadata ResultMetadata  `json:"metadata,omitempty"`
	// Parts holds optional extra content parts the tool loop records alongside
	// the tool_result part (e.g. a subagent reference part). Runtime-only (not a
	// wire field); nil = today's single tool_result behavior.
	Parts []protocol.ContentPart `json:"-"`
	// InjectUserParts holds content parts the tool loop records as a NEW
	// user-role message (distinct from Parts, which co-locate on the tool-result
	// message). Used by inject_image to put a locally-produced image into the
	// model's OWN context: an image must ride on a user-role message (a tool-role
	// message is text-only), so it cannot go on the tool_result. Runtime-only;
	// nil = no-op. An image part here also triggers mid-loop vision escalation.
	InjectUserParts []protocol.ContentPart `json:"-"`
}

type ResultMetadata struct {
	PayloadBytes    int          `json:"payload_bytes,omitempty"`
	ExitCode        int          `json:"exit_code,omitempty"`
	OutputBytes     int          `json:"output_bytes,omitempty"`
	OutputTruncated bool         `json:"output_truncated,omitempty"`
	PID             int          `json:"pid,omitempty"`
	FileChanges     []FileChange `json:"file_changes,omitempty"`
	// References are stable pointers returned by a tool to an authoritative
	// record. They let execution observers retain provenance without copying the
	// record payload into an operational ledger.
	References []ResultReference `json:"references,omitempty"`
}

type ResultReference struct {
	System string `json:"system"`
	Kind   string `json:"kind"`
	ID     string `json:"id"`
}

type SkillRealizerFunc func(ctx context.Context, names []string) (int, error)

type StaticPolicy struct {
	Allowed map[string]string
}

type SubagentConfig struct {
	Runner   subagent.Runner
	MaxDepth int
	Catalog  subagent.Catalog
	// AllowBackground advertises + enables the `background` spawn argument. Set it
	// only when the Runner supports detached execution (implements
	// subagent.BackgroundRunner with a Notifier wired); off → the tool is
	// synchronous-only and the schema omits `background`.
	AllowBackground bool
}

type ToolDelegate interface {
	HandlesTool(name string) bool
	InvokeTool(ctx context.Context, req Request) (Result, error)
}

type ToolEvent struct {
	Status           ToolEventStatus         `json:"status"`
	CallID           string                  `json:"call_id"`
	ToolName         string                  `json:"tool_name"`
	Addr             protocol.MessageAddress `json:"addr"`
	ArgumentsHash    string                  `json:"arguments_hash"`
	ArgumentsBytes   int                     `json:"arguments_bytes"`
	DurationMS       int64                   `json:"duration_ms,omitempty"`
	ApprovalDecision string                  `json:"approval_decision,omitempty"`
	PolicyDecision   string                  `json:"policy_decision,omitempty"`
	Reason           string                  `json:"reason,omitempty"`
	IsError          bool                    `json:"is_error,omitempty"`
	ErrorCode        string                  `json:"error_code,omitempty"`
	ErrorMessage     string                  `json:"error,omitempty"`
	Result           ResultMetadata          `json:"result,omitempty"`
}

type ToolEventSink interface {
	// EmitToolEvent may be called concurrently for explicitly parallel-safe tool
	// bodies. Implementations must synchronize shared state or serialize events.
	EmitToolEvent(ctx context.Context, event ToolEvent) error
}

type ToolEventStatus string

type TrustLevel int

type WorldStateSink interface {
	// RecordInvokedSkill notes that the model loaded a skill this turn (its name
	// and origin). The sink stamps the current turn as the skill's LastTurn.
	RecordInvokedSkill(name, source string)
	// RecordFile notes a file the agent wrote or edited this turn (kind is
	// "write" or "edit"). Aged in WorldState.RecentFiles.
	RecordFile(path, kind string)
	// RecordTodos records the current todo board (the model rewrites the whole
	// list via todo_write). Items are merged by id, keeping the latest touch, so
	// the board survives compaction.
	RecordTodos(items []spec.TodoItem)
	// RecordSubagent notes a sub-agent the model spawned/resumed this turn: its
	// thread_id handle (id, the re-addressable key), display name, status, and
	// short summary. Aged in WorldState.ActiveSubagents so the orchestrator sees
	// its live specialists and can route follow-ups back to them. Primitives only
	// (no compaction import from this package).
	RecordSubagent(id, name, status, summary string)
}