modproto

type Artifact struct {
	ID string `json:"id"`
	// Kind is the artifact schema ID, matching a key in the descriptor's
	// ArtifactSchemas. It selects the cockpit renderer.
	Kind string `json:"kind"`
	// Path is relative to a declared root; Root names which one, using a root
	// name the HOST supplied to the PRODUCING module. The host re-validates
	// confinement before touching the file.
	//
	// Root names are therefore scoped to one invocation and are not portable
	// between modules: a seed Midden writes under its own rw root cannot be
	// named by a root Facet was given. Cross-module handoff is resolved by the
	// host STAGING the artifact into its own artifact store and supplying that
	// as a read-only root to the consumer. Modules never learn each other's
	// layout, and the host keeps a single enforcement point.
	Path string `json:"path"`
	Root string `json:"root"`
	// Presentation names the rendering primitive the host should use, when the
	// module knows better than the media type does.
	//
	// A JSON document may be a timeline; a set of images may be a QA frame grid
	// that is useless viewed one at a time. Only the module knows that, so it
	// may say -- but it names a primitive the HOST already owns and never
	// supplies view code. An unknown value is ignored rather than honoured, so
	// a module cannot invent a renderer, and the media type decides when the
	// hint is absent.
	//
	// Values: video, audio, image, image_grid, timeline, document, diagram,
	// slides, table, markdown, text, json, download.
	Presentation string `json:"presentation,omitempty"`

	// MediaType, Bytes and Digest let the host render, budget, and verify
	// without opening the file first. Digest is "sha256:<lowercase-hex>".
	MediaType string `json:"media_type"`
	Bytes     int64  `json:"bytes"`
	Digest    string `json:"digest"`
	Title     string `json:"title,omitempty"`
}

type Capability struct {
	// ID is the capability identifier passed to `module invoke`. It is
	// namespaced by module, e.g. "creative.tools.run", "sessions.assay".
	ID string `json:"id"`

	// Title and Summary are cockpit-facing copy. Summary should be one line:
	// it is what the host folds into facet-agent's capability list, so every
	// enabled capability costs roughly one line of context.
	Title   string `json:"title"`
	Summary string `json:"summary"`

	// RequestSchema and ResultSchema are IDs into the descriptor's schema maps.
	//
	// RequestSchema describes the contents of Request.Input, NOT the whole
	// Request. The envelope fields around it -- protocol, capability,
	// request_id, roots, grants, binaries, deadline_ms -- are the host's and are
	// fixed by this package; a capability never redeclares them.
	//
	// This was under-specified in the first draft, which said only "IDs into the
	// descriptor's schema maps". Two lanes then read it differently and both
	// were reasonable: one described Input, the other described the whole
	// Request with `tool` and `input` as siblings. A host building a request
	// from the schema got rejected by a module whose own reader disagreed with
	// its own declaration -- a class invisible to schema checks and unit tests
	// alike, because each side was self-consistent.
	RequestSchema string `json:"request_schema"`
	ResultSchema  string `json:"result_schema"`

	// ArtifactSchemas lists artifact schema IDs this capability may produce.
	ArtifactSchemas []string `json:"artifact_schemas"`

	// Effects declares what invoking this capability does, before it is run.
	// The host uses it to decide whether approval is required, so it must be
	// honest even when the answer is inconvenient.
	Effects Effects `json:"effects"`

	// Skills lists skill IDs relevant to this capability, letting the host
	// load knowledge lazily and only for the capability actually in play.
	Skills []string `json:"skills"`

	// LongRunning marks a capability that may return a job handle in its
	// result rather than a completed outcome. When true, PollCapability names
	// the capability that polls it.
	LongRunning    bool   `json:"long_running"`
	PollCapability string `json:"poll_capability,omitempty"`
}

type Descriptor struct {
	// Module is the stable module ID, e.g. "facet" or "midden". It is the
	// directory name under $FACET_STUDIO_HOME/modules/ and the namespace
	// prefix for every capability the module offers.
	Module string `json:"module"`

	// Name is the human-readable display name for the cockpit.
	Name string `json:"name"`

	// Version is the module's own release version, independent of the
	// protocol version.
	Version string `json:"version"`

	// ProtocolVersions lists every protocol ID this binary can speak.
	//
	// The host requires ProtocolID to appear in this list and refuses the
	// module otherwise (validate.go). That is a MEMBERSHIP TEST against one
	// frozen constant -- it is NOT negotiation. There is no ordering, no
	// selection, and no "highest common version": declaring any ID other than
	// ProtocolID has no effect at all.
	//
	// This comment previously described the host as picking the greatest
	// mutually supported version. It never did. A sibling lane inferred a
	// versioning story from that sentence and had to retract it, which is why
	// the wording here now describes the membership test and nothing more.
	//
	// Real negotiation is a successor-contract concern. It must not be added
	// to v1 to make an old comment retroactively true.
	ProtocolVersions []string `json:"protocol_versions"`

	// Capabilities are the invocable operations, keyed by capability ID.
	Capabilities []Capability `json:"capabilities"`

	// RequestSchemas and ResultSchemas map a schema ID to a JSON Schema
	// document. Capabilities reference these by ID rather than inlining them,
	// so shared shapes are declared once.
	RequestSchemas map[string]json.RawMessage `json:"request_schemas"`
	ResultSchemas  map[string]json.RawMessage `json:"result_schemas"`

	// ArtifactSchemas maps an artifact schema ID to its JSON Schema.
	//
	// The host checks that every ID a capability lists in its own
	// ArtifactSchemas is present in this map (validate.go), and nothing more.
	// PRODUCED ARTIFACTS ARE NOT VALIDATED AGAINST THESE SCHEMAS. Grep for
	// ArtifactSchemas in internal/view, internal/moduletools and web/backend:
	// there are no readers. Rendering is decided by media type and the
	// module's presentation hint (internal/view.Resolve), never by a schema.
	//
	// This comment previously described the host as checking produced
	// artifacts against these schemas before rendering a card. It does not,
	// and a sibling lane was repairing its declarations toward that guarantee
	// before being told.
	//
	// Two consequences worth stating for the successor contract rather than
	// fixing here: a declared-but-unread field is indistinguishable from an
	// enforced one to anyone reading the type, and most artifacts in practice
	// are MEDIA (mp4, mp3, pdf) which a JSON Schema cannot validate at all.
	ArtifactSchemas map[string]json.RawMessage `json:"artifact_schemas"`

	// AgentOverlays are concise module-authored instruction documents the host
	// may compose into facet-agent. The host decides which to load and when;
	// a module cannot force its overlay into every turn.
	AgentOverlays []Overlay `json:"agent_overlays"`

	// Skills are progressively loadable module knowledge. The host loads only
	// those selected for the current request.
	Skills []Skill `json:"skills"`

	// Permissions is what the module declares it may need. It is a REQUEST,
	// never a grant: installing a module grants nothing. The host intersects
	// this with its own policy and authorizes per invocation.
	Permissions Permissions `json:"permissions"`

	// Requirements are external preconditions (binaries, versions, config)
	// that the host surfaces to the user when unmet.
	Requirements []Requirement `json:"requirements"`
}

type Effects struct {
	Local          bool   `json:"local"`
	Network        bool   `json:"network"`
	ExternalWrites bool   `json:"external_writes"`
	Provider       string `json:"provider"`

	// CostKnown declares whether a NUMERIC MONETARY COST IS KNOWN for this
	// capability. That is its whole meaning: "is there a number". It does NOT
	// mean "this may spend money", and the two are independent -- a capability
	// can reach a paid provider at a price it knows exactly, and another can be
	// free with no number to give.
	//
	// The distinction was settled by the lane that owns the field, by running
	// rather than reading: one of its tools declares cost_known TRUE and
	// network TRUE and requires no consent at all.
	//
	// SEPARATELY, and as a HOST POLICY rather than a property of this field:
	// facet-studio currently refuses a capability with cost_known false unless
	// the operator approved it (internal/moduletools.NeedsApproval). That is
	// this host over-gating on the only signal v1 carries, not a guarantee the
	// protocol makes. Another host may gate differently; one sibling does.
	//
	// v1 has no way to say "may incur a monetary charge" independent of
	// whether the amount is known. That is a successor-contract concern and
	// must not be smuggled into v1.
	CostKnown bool `json:"cost_known"`
}

type Envelope struct {
	Protocol string `json:"protocol"`
	Module   string `json:"module"`
	// Operation is the VERB: exactly OperationDescribe or OperationInvoke.
	// It is not the capability ID.
	Operation string `json:"operation"`

	// RequestID is host-generated and echoed back VERBATIM, so the host can
	// correlate without trusting the module to be unique. For describe, it is
	// empty.
	RequestID string `json:"request_id"`

	OK bool `json:"ok"`

	// Result is present when OK; Error is present when not. Exactly one of the
	// two appears.
	Result json.RawMessage `json:"result,omitempty"`
	Error  *Error          `json:"error,omitempty"`

	// Warnings is always an array, never null.
	Warnings []string `json:"warnings"`

	// Execution reports what the invocation ACTUALLY did, and is present even
	// on failure, because a failed paid call may still have cost money.
	Execution Execution `json:"execution"`
}

type Error struct {
	// Code is stable and machine-readable; the host routes on it and never on
	// Message text.
	Code string `json:"code"`
	// Message is human-readable and safe to show in the cockpit.
	Message string `json:"message"`
	// Retryable tells the host whether retrying unchanged could succeed.
	Retryable bool `json:"retryable"`
	// Details is bounded structured context. It must never carry credentials,
	// raw private transcripts, or internal database paths.
	Details map[string]any `json:"details"`
}

type Execution struct {
	Local          bool   `json:"local"`
	Network        bool   `json:"network"`
	ExternalWrites bool   `json:"external_writes"`
	Provider       string `json:"provider"`

	// EstimatedCost and ActualCost are POINTERS on purpose.
	//
	// null means genuinely unknown. 0 means genuinely free. Collapsing the two
	// would let an unpriced provider call render as free in the cockpit and
	// slip past cost approval, so the host treats null as "requires approval"
	// and never as zero.
	EstimatedCost *float64 `json:"estimated_cost"`
	ActualCost    *float64 `json:"actual_cost"`

	// Artifacts are pointers to produced files, never inline payloads. Large
	// results belong here so the envelope stays bounded.
	Artifacts []Artifact `json:"artifacts"`
}

type Grants struct {
	Network       []string `json:"network"`
	Credentials   []string `json:"credentials"`
	PaidProviders []string `json:"paid_providers"`
	Publish       bool     `json:"publish"`
	Subprocess    []string `json:"subprocess"`
}

type Normalizer interface {
	Normalize()
}

type Overlay struct {
	ID    string `json:"id"`
	Title string `json:"title"`
	// Path is relative to the module root and is resolved and confined by the
	// host. A module never hands the host an absolute path.
	Path string `json:"path"`
	// Digest is "sha256:<lowercase-hex>" over the file contents. The host
	// records it as provenance for anything folded into agent context and
	// refuses content whose digest does not match.
	Digest string `json:"digest"`
	// Tokens is the module's estimate of the overlay's context cost, so the
	// host can budget before loading it.
	Tokens int `json:"tokens"`
}

type Permissions struct {
	// FilesystemRead and FilesystemWrite are logical root NAMES the module
	// expects the host to supply, not paths. The module never resolves a root
	// itself; the host passes canonicalized absolute paths per invocation.
	FilesystemRead  []string `json:"filesystem_read"`
	FilesystemWrite []string `json:"filesystem_write"`

	// Network, Credentials, PaidProviders, Publish and Subprocess each require
	// explicit host policy plus, where configured, human approval.
	//
	// Subprocess is deliberately distinct from Network: a module that shells
	// out to an already-authenticated CLI needs subprocess authority, not
	// network or credential authority. Modelling that as "network" would be
	// both wrong and insufficient.
	Network       []string `json:"network"`
	Credentials   []string `json:"credentials"`
	PaidProviders []string `json:"paid_providers"`
	Publish       bool     `json:"publish"`
	Subprocess    []string `json:"subprocess"`
}

type Request struct {
	Protocol   string `json:"protocol"`
	Capability string `json:"capability"`
	RequestID  string `json:"request_id"`
	// Input is the capability-specific payload, and is the ONLY part of the
	// request a capability's declared RequestSchema describes. Everything
	// around it belongs to the host.
	Input json.RawMessage `json:"input"`

	// Roots maps logical root names declared in Permissions to canonicalized
	// absolute paths, each with an explicit access mode.
	Roots map[string]Root `json:"roots"`

	// Grants are the permissions actually authorized for THIS invocation.
	// A module must assume it has nothing that is not listed here.
	Grants Grants `json:"grants"`

	// Binaries maps a declared subprocess name to the ABSOLUTE path the host
	// resolved for it, keyed by the same names used in Permissions.Subprocess.
	//
	// Modules run with no inherited environment, so there is no PATH to search.
	// The host resolves and supplies paths instead, which is stronger than
	// supplying a minimal PATH: a search can find something that was never
	// declared -- a shadowing entry, or a second binary of the same name -- so
	// a path is an identity while a PATH is a query. It also makes
	// Permissions.Subprocess load-bearing rather than documentary: a binary the
	// module did not declare is never supplied, so it cannot be run.
	//
	// A declared binary the host could not resolve is ABSENT from this map
	// rather than present-and-empty, so "not supplied" and "supplied as
	// nothing" cannot be confused. Modules must fail closed with
	// ErrMissingRequirement rather than falling back to a lookup of their own.
	Binaries map[string]string `json:"binaries"`

	// DeadlineMS is the host's wall-clock budget. The module should aim to
	// return a bounded envelope before it elapses; the host enforces it by
	// killing the process tree regardless.
	DeadlineMS int `json:"deadline_ms"`

	// MaxOutputBytes is the stdout ceiling. Output beyond it is truncated and
	// the invocation fails as a protocol violation, so large results belong in
	// an artifact pointer rather than inline in the envelope.
	MaxOutputBytes int `json:"max_output_bytes"`

	// Extra carries additional root-level fields for modules that read some of
	// their arguments beside Input rather than inside it.
	//
	// Input remains the contract that RequestSchema describes. Extra exists
	// because real modules were already built the other way and a v1 that
	// cannot drive them is not a working v1. It is marshalled INLINE at the
	// request root, and host-owned fields always win, so a module cannot
	// capture protocol, roots, grants, or the bounds by naming them here.
	Extra map[string]json.RawMessage `json:"-"`
}

type Requirement struct {
	// Kind is "binary", "version", "config", or "env".
	Kind string `json:"kind"`
	Name string `json:"name"`
	// Available is the module's own probe result. The host displays it and
	// does not re-probe.
	Available bool `json:"available"`
	// Detail explains what is missing and how to satisfy it. This is the field
	// that makes "Needs setup" actionable, so it should name the dependency.
	Detail string `json:"detail,omitempty"`
}

type Root struct {
	Path string `json:"path"`
	// Mode is "ro" or "rw". A read-only root is the host's guarantee that a
	// source store cannot be mutated, independent of module behaviour.
	Mode string `json:"mode"`
}

type Skill struct {
	ID      string `json:"id"`
	Title   string `json:"title"`
	Summary string `json:"summary"`
	Path    string `json:"path"`
	// Digest is "sha256:<lowercase-hex>" over the file contents.
	Digest string `json:"digest"`
	// Tokens is the module's estimate of the skill's context cost.
	Tokens int `json:"tokens"`
}

type ValidationError struct {
	Path   string
	Detail string
}

type ValidationErrors []ValidationError