tools

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

type AuthoredPlugin struct {
	// ID is the plugin's id within the org, and the id a delete addresses.
	ID string `json:"id"`
	// Org is the org that built the plugin — the validated caller's.
	Org string `json:"org"`
	// Name is the plugin's name: one lowercase path segment, the id it runs by.
	Name string `json:"name"`
	// Provider is the connectors provider whose credential this plugin uses at
	// run time. Absent for a plugin that needs none. The credential itself is
	// never here — it stays under KMS custody in the connectors plane.
	Provider string `json:"provider,omitempty"`
	// Source is the TypeScript as authored (or as generated from a spec).
	Source string `json:"source"`
	// Bundled is the CommonJS the bundler produced, which the runtime executes.
	// Never rendered to a client.
	Bundled string `json:"-"`
	// CreatedAt is when the plugin was last built, Unix seconds.
	CreatedAt int64 `json:"createdAt"`
}

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

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

type Charger interface {
	Charge(ctx context.Context, tool string) error
}

type Curation struct {
	Hidden   *bool
	Featured *bool
	Official *bool
	Logo     *string
}

type MCPListing struct {
	// ID addresses the listing in a URL. It is the reverse-DNS NAME with its one
	// slash written as an underscore — reversible, because a namespace never
	// contains an underscore — so the id is readable and stable rather than a
	// hash that means nothing to whoever reads a link.
	ID string `json:"id"`
	// Name is the publisher's reverse-DNS name, e.g. "com.stripe/mcp".
	Name string `json:"name"`
	// Vendor is the namespace half of Name — the publisher, e.g. "com.stripe".
	Vendor string `json:"vendor"`
	// Title is the human-readable display name, when the entry carries one.
	Title string `json:"title,omitempty"`
	// Description is the publisher's one-line summary.
	Description string `json:"description"`
	// Repo is the source repository URL, when the entry names one.
	Repo string `json:"repo,omitempty"`
	// Site is the project's homepage, when the entry names one.
	Site string `json:"site,omitempty"`
	// Version is the published version of this listing.
	Version string `json:"version"`
	// Transports are the distinct transports this server can be reached over,
	// sorted: some of "stdio", "streamable-http", "sse". A listing with
	// "streamable-http" is one an org can enable here and now; a listing that is
	// only "stdio" needs a process to run it.
	Transports []string `json:"transports"`
	// Packages are the runnable package forms — npm, pypi, oci — each with the
	// runtime that launches it and the transport it then speaks.
	Packages []MCPPackage `json:"packages,omitempty"`
	// Remotes are the hosted endpoints the publisher serves the server at.
	Remotes []MCPRemote `json:"remotes,omitempty"`
	// Registry is the upstream this row was synced from.
	Registry string `json:"registry"`
	// Synced is when this row was last confirmed against upstream, Unix seconds.
	Synced int64 `json:"synced"`
	// Hidden keeps the listing out of the org-visible catalog. Curation: a sync
	// never changes it. Only a SuperAdmin sets it, and only a SuperAdmin sees a
	// hidden entry listed.
	Hidden bool `json:"hidden"`
	// Featured puts the listing on the front of the shelf. Curation.
	Featured bool `json:"featured"`
	// Official is whether this is the vendor's OWN server rather than someone
	// else's copy of it. Derived on every sync (see isOfficial) until a
	// SuperAdmin sets it explicitly, after which the admin's answer stands.
	Official bool `json:"official"`
	// Logo is the brand mark to render for the listing — the publisher's icon when
	// the entry carries one, or the one an admin set. Curation.
	Logo string `json:"logo,omitempty"`
}

type MCPPackage struct {
	// Registry is where the package is fetched from: npm, pypi, oci, nuget, mcpb.
	Registry string `json:"registry"`
	// Identifier is the package name or download URL.
	Identifier string `json:"identifier"`
	// Version is the exact published package version.
	Version string `json:"version,omitempty"`
	// Runtime is the publisher's hint for what launches it: npx, uvx, docker.
	Runtime string `json:"runtime,omitempty"`
	// Transport is what the launched process speaks: usually "stdio".
	Transport string `json:"transport"`
}

type MCPRemote struct {
	// Transport is "streamable-http" or "sse".
	Transport string `json:"transport"`
	// URL is the endpoint.
	URL string `json:"url"`
}

type MCPServer struct {
	// ID is the server's id within the org. It also PREFIXES every tool name the
	// server contributes, which is what keeps two servers' "search" apart.
	ID string `json:"id"`
	// Org is the org that registered the server — the validated caller's.
	Org string `json:"org"`
	// Name is the org's label for the server.
	Name string `json:"name"`
	// URL is the server's JSON-RPC endpoint. Always a public http(s) host: the
	// registration boundary and the dialer both refuse anything else.
	URL string `json:"url"`
	// AuthHeader is the request header the KMS-held credential is injected into,
	// e.g. "Authorization". Absent when the server needs no credential.
	AuthHeader string `json:"authHeader,omitempty"`
	// HasSecret is whether a credential is sealed in KMS for this server. The
	// VALUE is never returned by any route.
	HasSecret bool `json:"hasSecret"`
	// Listing is the catalog entry this server was enabled from, when it was.
	// Empty means the org typed the URL in itself.
	Listing string `json:"listing,omitempty"`
	// Source is where the registration came from: "catalog" when it was enabled
	// off the shelf, "org" when the org registered the URL itself. It is DERIVED
	// from Listing rather than stored, because two columns for one fact is two
	// chances to disagree.
	Source string `json:"source"`
	// CreatedAt is when the server was registered, Unix seconds.
	CreatedAt int64 `json:"createdAt"`
}

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

type Price struct {
	// Amount is what ONE call costs, EXACTLY: an 18-decimal USD value, so a
	// per-call price of $0.0025 is $0.0025 and not a cent-floored zero. Cents
	// cannot hold a per-token price, and a tool plane is where per-token prices
	// live.
	Amount money.Amount `json:"amount"`
	// Currency is the ISO 4217 code, e.g. "USD". Empty means USD.
	Currency string `json:"currency"`
	// Recipient is the payout wallet ref the marketplace seller is paid at.
	Recipient string `json:"recipient"`
}

type Principal struct {
	Org     string
	Project string
	User    string
	Owner   string
	IsAdmin bool
}

type Provider interface {
	// Source is the provider's source tag (a provider serves exactly one source).
	Source() Source
	// List returns the tools this source offers for scope. It is scope-aware:
	// a connector source lists an org's connected connectors; the external-MCP
	// source lists tools from the org's registered servers.
	List(ctx context.Context, scope Scope) ([]Tool, error)
	// Dispatch invokes the named tool with JSON args, bound to the principal, and
	// returns the JSON-encodable result. A source that only lists (skills) returns
	// ErrNotDispatchable.
	Dispatch(ctx context.Context, p Principal, name string, args map[string]any) (any, error)
}

type Query struct {
	// Text matches the name, title or description, case-insensitively.
	Text string
	// Featured, Official keep only listings with that flag when true.
	Featured, Official bool
	// Hidden includes the hidden listings. Only a SuperAdmin ever passes true —
	// the org-visible view is the same query with it false, so "what an org sees"
	// and "what an admin sees" are ONE query and cannot drift apart.
	Hidden bool
	// Limit bounds the page. Zero or less means catalogPage; more than catalogMax
	// is clamped to it.
	Limit int
	// Offset skips that many rows.
	Offset int
}

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

type Scope struct {
	Org     string
	Project string
}

type Skill struct {
	// ID is the skill's id within the org. It is DERIVED from Name, so writing
	// the same name again revises that skill rather than adding another.
	ID string `json:"id"`
	// Org is the org that authored the skill — the validated caller's, never a
	// value the body supplied.
	Org string `json:"org"`
	// Name is the skill's name: one lowercase path segment (a-z0-9, _ or -).
	Name string `json:"name"`
	// Description is the one-line summary discovery shows for the skill.
	Description string `json:"description"`
	// Content is the SKILL.md body, markdown.
	Content string `json:"content"`
	// CreatedAt is when the skill was last written, Unix seconds.
	CreatedAt int64 `json:"createdAt"`
}

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

type Source string

type Tool struct {
	// Name is the tool's id in the flat, fleet-wide tool namespace — the value a
	// tools/call passes. Unique across sources: a collision is resolved by source
	// precedence before the caller ever sees it.
	Name string `json:"name"`
	// Source is where the tool comes from: connector, function, zap-service,
	// agent, skill or mcp.
	Source Source `json:"source"`
	// Description is the prose a model reads to decide whether to call the tool.
	Description string `json:"description"`
	// Schema is the JSON Schema of the call arguments — the MCP inputSchema.
	// Absent for a tool that takes none.
	Schema json.RawMessage `json:"inputSchema,omitempty"`
	// Price is what a call costs and who is paid, absent for a free tool.
	// Enforcement is the x402 settlement seam; this is the declaration.
	Price *Price `json:"price,omitempty"`
	// Dispatchable is whether the tool can be CALLED. False for a listing-only
	// entry: a skill is activated and attached to an agent, never called.
	Dispatchable bool `json:"dispatchable"`
	// Activated is filled by the registry from the activation store for the
	// requesting (org,project); providers leave it zero. An unactivated tool is
	// discoverable but refused 403 at dispatch.
	Activated bool `json:"activated"`
}