tools

type Deps struct {

	// Flipper is the serial transport + capability bag for the
	// connected Flipper Zero. Nil only in degenerate test setups that
	// do not touch hardware; production handlers may assume non-nil.
	Flipper *flipper.Flipper

	// Marauder is the optional ESP32 Marauder devboard. Nil when the
	// operator did not start PromptZero with --wifi (or the MCP
	// NewServer was called with m==nil). WiFi handlers MUST
	// short-circuit on a nil Marauder — the agent's requireMarauder()
	// helper does this in the current code; handlers can call a
	// similar helper on Deps.
	Marauder *marauder.Marauder

	// Bruce is the optional Bruce ESP32 devboard (https://github.com/pr3y/Bruce).
	// Nil when the operator has not configured a Bruce device (bruce.port
	// absent in config, or --bruce flag not supplied). Bruce handlers MUST
	// short-circuit on a nil Bruce — call [Deps.RequireBruce] at the top
	// of every handler, mirroring the [Deps.RequireMarauder] pattern.
	Bruce *bruce.Client

	// Faultier is the optional hextreeio Faultier USB voltage-glitcher.
	// Nil when no faultier.port is configured. Glitch handlers MUST
	// short-circuit on a nil Faultier — call [Deps.RequireFaultier]
	// at the top of each handler.
	Faultier *faultier.Client

	// BusPirate is the optional Bus Pirate 5 universal-bus probe.
	// Nil when no buspirate.port is configured. BusPirate handlers
	// MUST short-circuit on nil — call [Deps.RequireBusPirate] at
	// the top of each handler.
	BusPirate *buspirate.Client

	// Audit is the session audit log. Nil means "audit disabled" —
	// handlers that write to the log should no-op in that case. The
	// audit_* tools surface this with a friendly string.
	Audit *audit.Log

	// Config is the running process's resolved configuration — used
	// by badusb_run to consult Validator.BadUSB.AllowCritical, by
	// anything that resolves paths, etc. Nil is a bug.
	Config *config.Config

	// Generator drives the generate_* tools (evil_portal, badusb,
	// subghz, ir, nfc). Nil means no generation LLM is configured;
	// the handlers return a friendly "generator not configured" error.
	Generator *generate.Generator

	// GenLLM is the underlying provider the generator uses. Some
	// workflow handlers call it directly for ad-hoc synthesis that
	// doesn't fit the generator's typed payload shape.
	GenLLM provider.Provider

	// Vision drives analyze_image. Nil means vision is not configured.
	Vision *vision.Analyzer

	// Snapshot stores pre-write copies of Flipper SD files so /rewind
	// can roll back. Nil disables snapshots (Store is skipped). Tools
	// that clobber SD content (storage_copy, storage_rename,
	// storage_write, fileformat_edit, *_build, generate_*) must call
	// [Deps.SnapshotBeforeWrite] before writing.
	Snapshot *snapshot.Manager

	// SessionID is the active session's identifier. Paired with
	// Snapshot — [Deps.SnapshotBeforeWrite] is a no-op when this is
	// empty (off-session tests, MCP mode) even if Snapshot is non-nil.
	SessionID string

	// RAG is the lexical index for docs_search. Nil falls back to the
	// embedded index on first call (the existing behaviour in
	// internal/agent/agent.go:docsSearch).
	RAG *rag.Index

	// TargetMem is the persistent target-facts store (internal/targetmem).
	// Nil means target_* tools return the "targets feature not
	// enabled" friendly message.
	TargetMem *targetmem.Store

	// WorkflowConfirm is the operator-confirmation hook for workflow
	// sub-tools. Nil means "auto-approve every sub-step" (the MCP and
	// test defaults). The returned bool indicates approval.
	WorkflowConfirm func(ctx context.Context, tool string, input any, riskLevel string) bool

	// BuildVerify runs the chain-of-verification LLM pass on freshly-built
	// file bytes and returns (summary, blockMsg). A non-empty blockMsg means
	// the caller MUST NOT persist the file — surface it as the tool result.
	// An empty blockMsg and non-empty summary means the write can proceed;
	// append the summary to the success message.
	//
	// Nil means skip verification (MCP mode, test setups without a live LLM
	// client). Handlers for *_build and generate_* tools call
	// [Deps.RunBuildVerification] which handles the nil guard, so direct
	// nil checks are not needed in individual handlers.
	BuildVerify func(ctx context.Context, payloadType string, content []byte, bypass bool) (summary, blockMsg string)
}

type Group string

type Handler func(ctx context.Context, d *Deps, args map[string]any) (string, error)

type Spec struct {
	// Name is the canonical tool identifier. Must be unique across the
	// entire registry — [Register] panics on a duplicate (an init-time
	// loud failure is the right shape for a programming error that
	// would silently corrupt dispatch otherwise).
	Name string

	// Aliases are additional names that resolve to the same Handler.
	// Used for legacy synonyms — e.g. system_info was the agent-side
	// name and device_info is the MCP / firmware name. Both resolve
	// via [Get]. Aliases MUST NOT collide with another Spec's Name.
	Aliases []string

	// Description is the user-visible tool documentation. Must be
	// self-contained — the MCP client, the agent's Anthropic schema,
	// and /tools all read this same string. Keep it under ~1 KB so
	// the prompt-cache breakpoint stays reasonable.
	Description string

	// Schema is the canonical JSON Schema for the tool's parameters
	// (an object with "properties" and optionally "required"). Both
	// mode adapters decode arguments into map[string]any, so the
	// schema's job is catalog advertisement, not runtime validation.
	Schema json.RawMessage

	// Required lists parameters the caller MUST supply. The MCP mode
	// adapter validates this explicitly (missingRequired in the old
	// s.add()); the agent mode advertises it via InputSchema.Required.
	Required []string

	// Risk is the confirmation-gate classification. Drives
	// internal/risk.Classify, the MCP annotation hints
	// (readOnlyHint/destructiveHint/openWorldHint), and the interactive
	// ConfirmFunc prompt in REPL mode.
	Risk risk.Level

	// Group is the router bucket. Defaults to GroupMetaUtil when the
	// zero value is registered. See internal/agent/router.go for the
	// narrowing logic.
	Group Group

	// AgentOnly excludes this tool from the MCP adapter. Reserved for
	// LLM-composition tools that require facilities MCP does not have
	// (generator LLM, vision analyzer, snapshot manager, workflow
	// confirmation hook). An AgentOnly handler may safely dereference
	// any field on Deps; a non-AgentOnly handler must degrade when
	// those fields are nil.
	AgentOnly bool

	// Handler is the dispatch body. Wave engineers paste the
	// corresponding `case "<name>":` body from internal/agent/agent.go's
	// dispatch switch into this function, substituting `a.flipper` →
	// `d.Flipper`, `a.marauder` → `d.Marauder`, etc.
	Handler Handler

	// Streams declares whether the tool can emit partial output via
	// a streaming.Sink during dispatch (roadmap P3-28 first half).
	// Operator-facing UIs (CLI status line, web UI, SSE forwarder)
	// subscribe to the per-call sink to surface live progress;
	// the LLM-facing tool_result is unchanged — it remains the
	// final return string. Default false; non-streaming dispatch is
	// the historical behaviour.
	Streams bool

	// StreamHandler is the streaming-handler variant. Optional —
	// when nil, the dispatcher uses Handler. When set AND the host
	// has installed a stream callback, the dispatcher invokes
	// StreamHandler with a fresh sink and forwards frames to the
	// callback in real time. The callback ALSO receives a final
	// frame on close so consumers can flush any per-tool buffer.
	//
	// StreamHandler still returns the final tool_result string so
	// the LLM contract is unchanged: the agent serialises the
	// return value into the tool_result block exactly as for the
	// non-streaming Handler. Streaming is an addition to the side
	// channel, never a replacement for the model-facing answer.
	StreamHandler streamHandler

	// WriteIntent, when non-nil, is invoked by the confirmation flow
	// to extract the (path, content) the tool would write. The flow
	// uses these to fetch the existing file and show a unified diff
	// in the confirmation prompt before the operator approves a
	// medium-risk overwrite. nil means "this tool isn't a file write"
	// — the vast majority of Specs.
	//
	// The function MUST be cheap and side-effect-free: it runs at
	// confirmation time, on the args the model proposed, before any
	// risk gate has cleared. Returning ok=false signals "args don't
	// describe a write right now" and the framework skips the diff
	// preview without erroring (e.g. a deploy=false flag).
	WriteIntent func(args map[string]any) (path string, content string, ok bool)
}

type StreamHandler = streamHandler

type WiegandResult struct {
	Format          string `json:"format"`
	BitCount        int    `json:"bit_count"`
	FacilityCode    uint64 `json:"facility_code"`
	FacilityCodeHex string `json:"facility_code_hex"`
	CardNumber      uint64 `json:"card_number"`
	CardNumberHex   string `json:"card_number_hex"`
	ParityValid     bool   `json:"parity_valid"`
	LeadingParity   bool   `json:"leading_parity"`
	TrailingParity  bool   `json:"trailing_parity"`
	RawBits         string `json:"raw_bits"`
}