builtin

type ArtifactFetchArgs struct {
	// Ref is the artifact identifier surfaced by a prior tool result's
	// fetch footer.
	Ref string `json:"ref"`
	// MaxBytes bounds the returned window. Zero or negative applies the
	// deployment's configured default; a value above its configured
	// ceiling is SERVED AT THE CEILING and reported through the same
	// Truncated / TotalSizeBytes / ReturnedBytes fields as any other
	// bound — never refused, never silently shortened.
	MaxBytes int `json:"max_bytes,omitempty"`
	// Offset is the zero-based BYTE index the returned window starts at.
	// It is how a model pages a large artifact: read at 0, then re-call
	// with Offset set to the previous Offset + ReturnedBytes while
	// Truncated is true.
	//
	// The window is a byte range and is MIME-agnostic — it knows nothing
	// about lines, rows or records, so a window may begin and end
	// mid-line and the caller splits the text itself. That is deliberate:
	// a stored MIME is not revisable on a content-addressed store, so
	// keying read behaviour on one would turn a wrong stamp into a
	// permanent refusal.
	//
	// An offset at or beyond the artifact's size is not an error — the
	// content is empty and Truncated is false, because nothing follows
	// the window. A negative offset is a soft error rather than a guess.
	Offset int `json:"offset,omitempty"`
}

type ArtifactFetchOut struct {
	Ref       string `json:"ref"`
	MIME      string `json:"mime,omitempty"`
	SizeBytes int64  `json:"size_bytes"`
	// Content is the admitted window as text. It is exactly
	// `blob[Offset : Offset+ReturnedBytes]` — the requested range trimmed
	// to whole runes at both ends — so a model paging by the documented
	// rule reassembles the artifact with no gaps and no duplicates.
	//
	// A window that is not valid UTF-8 after that trimming is REFUSED
	// rather than delivered: `Content` is empty and `Error` names the
	// stored MIME, the failing byte offset and the by-reference route
	// those bytes can travel. The refusal exists because this field is a
	// string on its way through `encoding/json`, which rewrites every
	// invalid byte to U+FFFD — so a binary artifact would arrive
	// corrupted, at a different length than `ReturnedBytes` reported.
	Content string `json:"content,omitempty"`
	// Offset is the byte index the returned window ACTUALLY starts at.
	// When the requested offset landed mid-rune it is the requested
	// offset advanced past the continuation bytes that were trimmed, not
	// the requested offset echoed back — a paging model computes its next
	// call as `Offset + ReturnedBytes`, and echoing a stale offset would
	// drop the trimmed bytes with no signal.
	Offset int64 `json:"offset"`
	// ReturnedBytes is the length of `Content` in bytes.
	ReturnedBytes int64 `json:"returned_bytes"`
	// TotalSizeBytes is the artifact's full stored size — the
	// denominator a bounded read is bounded against. It duplicates
	// SizeBytes, which predates this field and is kept because shipped
	// prompts and transcripts name it; both are the same number.
	TotalSizeBytes int64 `json:"total_size_bytes"`
	// Truncated reports whether bytes remain AFTER the returned window
	// (`offset + returned_bytes < total_size_bytes`). It is true
	// whichever bound applied — the caller's `max_bytes`, the
	// deployment's default, or the deployment's ceiling — so the model
	// never has to know WHICH bound applied to know that one did. Re-call
	// with `offset` advanced to read on.
	Truncated bool `json:"truncated,omitempty"`
	// Error carries soft failures. When set, `Content` is empty and
	// the LLM sees the error message as the observation text.
	Error string `json:"error,omitempty"`
}

type ClockNowArgs struct{}

type ClockNowOut struct {
	RFC3339  string `json:"rfc3339"`
	EpochMS  int64  `json:"epoch_ms"`
	Timezone string `json:"timezone"`
}

type DeclarativeActionArgs struct {
	// Tool is the catalog name to dispatch. Reserved names (`_finish`,
	// `_spawn_task`, `_await_task`) return ErrDeclarativeActionReservedName
	// — they are planner-level, not catalog entries.
	Tool string `json:"tool,omitempty"`
	// Args is the JSON arguments to pass to Tool. Validated against
	// the tool's args schema before dispatch; an invalid shape returns
	// a structured `repair_outcome.args_repaired=true` observation so
	// the next planner step's prompt escalates ArgsRepair guidance.
	Args json.RawMessage `json:"args,omitempty"`
	// Body is the alternate salvage input: a raw JSON envelope (or
	// array of envelopes) that the `repair.ActionParser` parses. A
	// multi-action array trips MultiAction; a parse failure trips
	// ArgsRepair.
	Body json.RawMessage `json:"body,omitempty"`
}

type DeclarativeActionOut struct {
	// Dispatched is true when the inner tool's Invoke returned without
	// error. The planner / LLM treat this as a successful dispatch.
	Dispatched bool `json:"dispatched"`
	// Tool is the resolved inner-tool name (echoed for observability —
	// the trajectory step's Action carries declarative_action, not the
	// inner name, so this field surfaces the actual call target).
	Tool string `json:"tool,omitempty"`
	// Observation is the inner tool's typed result, JSON-encoded. The
	// LLM consumes this as the next turn's tool-result content.
	Observation json.RawMessage `json:"observation,omitempty"`
	// Error is the human-readable error message when Dispatched=false.
	Error string `json:"error,omitempty"`
	// RepairOutcome carries the across-step repair classification the
	// React planner reads on the next step.
	// Nil means "no repair signal" (a clean dispatch resets counters
	// the same way a clean native step does).
	RepairOutcome *DeclarativeRepairOutcome `json:"repair_outcome,omitempty"`
}

type DeclarativeRepairOutcome struct {
	// ArgsRepaired is true when the inner tool's args failed schema
	// validation OR when the salvage parser could not extract an
	// envelope. Drives planner.RepairCounters.ArgsRepair.
	ArgsRepaired bool `json:"args_repaired,omitempty"`
	// MultiAction is true when the salvage parser returned more than
	// one envelope in a single body. Drives
	// planner.RepairCounters.MultiAction.
	MultiAction bool `json:"multi_action,omitempty"`
	// FinishRepair is true when the LLM tried to invoke a planner-
	// reserved finish marker (`_finish`) through declarative_action.
	// Drives planner.RepairCounters.FinishRepair so the next turn's
	// prompt nudges the LLM toward issuing a content-only terminal.
	FinishRepair bool `json:"finish_repair,omitempty"`
}

type RegistryContext struct {
	Catalog tools.ToolCatalog
	// SkillReader optionally supplies a read-only skill projection for
	// skill_search, skill_get, and skill_list. When nil those readers retain
	// source compatibility by falling back to SkillStore. Mutating built-ins
	// such as skill_propose always require SkillStore.
	SkillReader   skills.SkillReader
	SkillStore    skills.SkillStore
	ArtifactStore artifacts.ArtifactStore
	Bus           events.EventBus
	Redactor      audit.Redactor
	GrantedScopes []string
	// ArtifactFetchDefaultMaxBytes and ArtifactFetchHardMaxBytes are the
	// operator's artifact read-back bound: the window `artifact_fetch`
	// serves when the model names none, and the ceiling the model's own
	// bound is clamped to. Optional — a non-positive value takes the
	// built-in default, which is what keeps a catalog assembled without
	// a configuration working.
	//
	// They are the SAME operator policy the Protocol's byte read serves
	// under, so the tool and the wire surface cannot drift into two
	// different ceilings.
	ArtifactFetchDefaultMaxBytes int
	ArtifactFetchHardMaxBytes    int
}

type SkillGetArgs struct {
	// Names are the skill names to fetch. Missing names are skipped
	// (a partial response beats a hard error for stale model state).
	Names []string `json:"names"`
	// MaxTokens caps the combined estimated token count of the
	// returned skills via the tiered budgeter ladder. 0 → the
	// handler default (1024).
	MaxTokens int `json:"max_tokens,omitempty"`
}

type SkillListArgs struct {
	Scope    skills.Scope `json:"scope,omitempty"`
	TaskType string       `json:"task_type,omitempty"`
	Tags     []string     `json:"tags,omitempty"`
	Limit    int          `json:"limit,omitempty"`
	Offset   int          `json:"offset,omitempty"`
}

type SkillSearchArgs struct {
	Query string `json:"query"`
	Limit int    `json:"limit,omitempty"`
}

type TextEchoArgs struct {
	Text string `json:"text"`
	Tag  string `json:"tag,omitempty"`
}

type TextEchoOut struct {
	Echoed string `json:"echoed"`
	Tag    string `json:"tag,omitempty"`
}

type ToolGetArgs struct {
	Name string `json:"name"`
}

type ToolGetOut struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	ArgsSchema  string `json:"args_schema,omitempty"`
	Found       bool   `json:"found"`
	Error       string `json:"error,omitempty"`
}

type ToolSearchArgs struct {
	Query string   `json:"query"`
	Tags  []string `json:"tags,omitempty"`
	Limit int      `json:"limit,omitempty"`
}

type ToolSearchOut struct {
	Tools []ToolSearchResult `json:"tools"`
	Count int                `json:"count"`
}

type ToolSearchResult struct {
	Name        string   `json:"name"`
	Description string   `json:"description"`
	Tags        []string `json:"tags"`
}