tools

type ActivationStore ¶

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

ActivationStore is the per-(org,project,tool) activation plane: the durable toggle hanzo.chat / hanzo.app read to decide which skills/plugins/connectors an org has turned on. It is the tool-plane twin of the entitlements (org,product) enablement store — a row exists iff the tool is EXPLICITLY activated for that scope, and dispatch fails closed (403) on any tool without one.

Isolation is the (org, project, tool) composite key plus a mandatory `WHERE org=? AND project=?` on every statement. org/project are the VALIDATED principal values, never client input. One SQLite file (all orgs, org column), MaxOpenConns(1), WAL — the shared cloud store discipline.

func OpenActivationStore(path string) (*ActivationStore, error)

func (s *ActivationStore) Activate(ctx context.Context, org, project, tool string, source Source, byUser string) error

func (s *ActivationStore) Close() error

func (s *ActivationStore) Deactivate(ctx context.Context, org, project, tool string) error

func (s *ActivationStore) IsActivated(ctx context.Context, org, project, tool string) bool

func (s *ActivationStore) List(ctx context.Context, org, project string) ([]string, error)

type Charge ¶

type Charge struct {
	Payer     string // paying org's billing ledger (principal Owner/Org).
	Project   string
	Tool      string
	Recipient string // seller payout wallet (Tool.Price.Recipient).
	Currency  string
	Cents     int64
	RequestID string
}

Charge is one settlement request for a monetized tool call. It is the whole contract the registry hands the x402 seam: who pays, who is paid, how much.

type Charger ¶

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

Charger settles a monetized tool call over the x402 payment rail (LP-3028, clients/commerce/payment/x402). A SEPARATE team owns the concrete implementation backed by x402.Facilitator.Settle (Payee = the recipient wallet address); the registry codes to THIS narrow interface and keeps the seam explicit so it never pulls the processor/MPC/chain graph into the tool plane. A nil Charger makes every priced tool fail closed (ErrChargerUnset) — a paid tool is never free.

Charge returns nil on a settled payment, ErrPaymentRequired when the payer cannot pay, or another error (fail-closed) on an unavailable rail.

type MCPServer ¶

type MCPServer struct {
	ID         string `json:"id"`
	Org        string `json:"org"`
	Name       string `json:"name"`
	URL        string `json:"url"`
	AuthHeader string `json:"authHeader,omitempty"` // header to inject the KMS secret into (e.g. "Authorization").
	HasSecret  bool   `json:"hasSecret"`
	CreatedAt  int64  `json:"createdAt"`
}

MCPServer is one org-registered external MCP server. AuthHeader/HasSecret record how to authenticate; the secret itself is in KMS at authRef(org, id).

type MCPServerStore ¶

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

MCPServerStore is the per-org registry of external MCP servers (one SQLite file, org column, the shared cloud store discipline). Isolation is a mandatory `WHERE org=?` on every statement; org is the validated principal value.

func OpenMCPServerStore(path string) (*MCPServerStore, error)

func (s *MCPServerStore) Close() error

func (s *MCPServerStore) Create(ctx context.Context, srv MCPServer) (MCPServer, error)

func (s *MCPServerStore) Delete(ctx context.Context, org, id string) (bool, error)

func (s *MCPServerStore) Get(ctx context.Context, org, id string) (MCPServer, error)

func (s *MCPServerStore) List(ctx context.Context, org string) ([]MCPServer, error)

type Price ¶

type Price struct {
	AmountCents int64  `json:"amountCents"`
	Currency    string `json:"currency"`  // ISO 4217, e.g. "USD"; empty ⇒ "USD".
	Recipient   string `json:"recipient"` // payout wallet ref for the marketplace seller.
}

Price declares what a monetized tool call costs and who is paid. Enforcement is the x402 Charger seam (registry.go) — this is only the DECLARATION a marketplace listing carries. A nil Price means the tool is free (no x402 settlement).

type Pricer ¶

type Pricer interface {
	PriceFor(ctx context.Context, scope Scope, tool string) *Price
}

Pricer resolves the marketplace price of a tool at dispatch time. It is the seam the marketplace fills so a monetized listing's price + recipient wallet reach the per-call enforcement path WITHOUT the tool plane importing the marketplace. A tool whose provider already set an intrinsic Price does not consult the Pricer.

type Principal ¶

type Principal struct {
	Org     string
	Project string
	User    string
	Owner   string
	IsAdmin bool
	// contains filtered or unexported fields
}

Principal is the VALIDATED caller a dispatch runs as — resolved once from the request and threaded to every source. Org/Project/User/Owner/IsAdmin are the IAM-native identity; credential is the caller's OWN credential headers, replayed by a builtin tool so a /v1 route runs under the SAME IAM check as a direct HTTP call (cloud's SanitizeIdentity strips minted headers on ingress and re-mints them ONLY from a re-validated credential, so replaying the credential — never the minted headers — is the one way an in-process call carries the caller's identity; this is exactly the zapface in-process-dispatch contract).

func PrincipalFrom(c *zip.Ctx) (Principal, bool)

type Provider ¶

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; builtin lists routes.
	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)
}

Provider is one tool SOURCE. It lists the tools it offers to a (org,project) and dispatches a call to one of them bound to the principal. The registry composes providers; it never learns how any single source lists or runs its tools. A source implements this once and calls Register — that is the whole contract.

type Registry ¶

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

Registry is THE tool plane: the set of registered source Providers, the shared per-(org,project) activation store, and the x402 Charger seam. It composes providers and enforces the ONE dispatch policy (activation gate → price gate → dispatch); it knows nothing about how any source lists or runs a tool.

func Default() *Registry

func NewRegistry() *Registry

func (r *Registry) Activate(ctx context.Context, org, project, tool, byUser string) error

func (r *Registry) Activated(ctx context.Context, org, project string) ([]string, error)

func (r *Registry) Deactivate(ctx context.Context, org, project, tool string) error

func (r *Registry) Dispatch(ctx context.Context, p Principal, name string, args map[string]any) (any, error)

func (r *Registry) Exists(ctx context.Context, scope Scope, name string) bool

func (r *Registry) List(ctx context.Context, scope Scope) []Tool

func (r *Registry) Register(p Provider)

func (r *Registry) SetActivation(a *ActivationStore)

func (r *Registry) SetCharger(c Charger)

func (r *Registry) SetPricer(p Pricer)

type Scope ¶

type Scope struct {
	Org     string
	Project string
}

Scope is the (org, project) a listing is resolved for. project == "" or the literal default project both denote the org's default scope.

type Source ¶

type Source string

Source names WHERE a tool comes from. It is the ONE dimension precedence and activation-default policy key on, so it is a closed set of values, not free text.

const (
	// SourceBuiltin is a cloud /v1 route exposed as a tool ("full-cloud-control"):
	// a per-user token does over MCP exactly what that user may do over HTTP, gated
	// by the SAME IAM check because dispatch replays the request in-process.
	SourceBuiltin Source = "builtin"
	// SourceConnector is a connector action from clients/automations.
	SourceConnector Source = "connector"
	// SourceFunction is a user-defined function from clients/functions.
	SourceFunction Source = "function"
	// SourceZAPService is a zap-proto service route (tunneled over /zap).
	SourceZAPService Source = "zap-service"
	// SourceAgent is an org agent from clients/agents, callable as a tool.
	SourceAgent Source = "agent"
	// SourceSkill is an agent skill (clients/agentskills): discovery + activation
	// metadata, attached to agents rather than called directly.
	SourceSkill Source = "skill"
	// SourceMCP is a tool on an org's own registered EXTERNAL MCP server.
	SourceMCP Source = "mcp"
)

type Tool ¶

type Tool struct {
	Name         string          `json:"name"`
	Source       Source          `json:"source"`
	Description  string          `json:"description"`
	Schema       json.RawMessage `json:"inputSchema,omitempty"`
	Price        *Price          `json:"price,omitempty"`
	Dispatchable bool            `json:"dispatchable"`
	// Activated is filled by the registry from the activation store for the
	// requesting (org,project); providers leave it zero.
	Activated bool `json:"activated"`
}

Tool is the ONE description of a callable capability, uniform across sources. Schema is the JSON-Schema of the call arguments (MCP inputSchema); Dispatchable is false for a listing-only entry (a skill is activated + attached, not called).