extension

type AuthSpec ¶

type AuthSpec struct {
	// Type is the auth scheme: "none", "basic", "bearer", "api_key", "oauth2", or the
	// name of a code-port auth provider for anything custom (SigV4, a service-account
	// JWT). Empty means "none".
	Type string `json:"type,omitempty"`
	// In and Name place an api_key credential: In is "header" or "query", Name is the
	// header or parameter name. Ignored for other types.
	In   string `json:"in,omitempty"`
	Name string `json:"name,omitempty"`
	// Scheme is the bearer prefix (default "Bearer"); ignored for other types.
	Scheme string `json:"scheme,omitempty"`
	// CredentialRef names the stored credential to resolve from the vault. The
	// multi-key, role-aware credential model is fleshed out by the auth overhaul; here
	// it is the reference the spec carries instead of a value.
	CredentialRef string `json:"credentialRef,omitempty"`
	// Roles enumerates the named credential roles this extension distinguishes (e.g. a
	// read role and a deploy role backed by different keys). Empty means a single
	// default credential.
	Roles []string `json:"roles,omitempty"`
	// OAuth2 carries the static parameters of an "oauth2" scheme (the token endpoint,
	// client id, grant, and scopes). The secret it exchanges (a client secret or a
	// refresh token) is the resolved credential, never carried here. Ignored for other
	// types.
	OAuth2 *OAuth2Spec `json:"oauth2,omitempty"`
}

AuthSpec declares how a surface authenticates without ever embedding a secret. The credential value lives in the vault and is resolved by reference at call time, so the stored spec is safe to inspect, diff, and sync across a fleet.

type CodeRef ¶

type CodeRef struct {
	// Name is the registered code-port implementation to bind. Required when Code is
	// set.
	Name string `json:"name"`
}

CodeRef names a compiled implementation registered in-process under the optional-code port. It is the only way executable behaviour binds to an extension, and it binds by name: the manifest stays declarative data while the code lives in the binary (or a host plugin), resolved at load time. Resolving an unknown name fails closed, so a spec can never silently run the wrong code.

type Conn ¶ added in v0.1.3

type Conn interface {
	// Stdin is the process's standard input, for writing MCP requests.
	Stdin() io.WriteCloser
	// Stdout is the process's standard output, for reading MCP replies.
	Stdout() io.Reader
	// Stop ends the process and releases it. It is idempotent.
	Stop() error
}

Conn is a live duplex connection to a launched extension subprocess: its MCP stdio pipes and the means to stop it. The real launcher backs it with a sandbox session over anonymous pipes; a test backs it with an in-memory pair. Stop must kill the process and leave no orphan.

type DevResolver ¶ added in v0.1.3

type DevResolver struct {
	// Enabled turns dev mode on. It must be an explicit, deliberate opt-in; the zero value
	// refuses every source so a misconfiguration fails closed.
	Enabled bool
}

DevResolver resolves a dev (locally-built, unsigned) extension binary. It is the authoring inner loop: point flynn at a local build and mount it exactly like a released one, minus the download and signature. Because it runs unsigned code, it is gated by Enabled: unless dev mode is explicitly turned on, a dev source is refused, and a released source is always refused here (the signed-distribution resolver owns that path), so this resolver can never run remote or unverified code in a normal run.

func (r DevResolver) Resolve(_ context.Context, extName string, block ProcessBlock) (string, []string, error)

type DevSource ¶ added in v0.1.3

type DevSource struct {
	Path string `json:"path"`
}

DevSource is a locally-built extension binary referenced by absolute path.

type FetcherOption ¶ added in v0.1.3

type FetcherOption func(*httpFetcherConfig)

FetcherOption configures an HTTPHostFetcher.

func WithFetchContentType(s string) FetcherOption

func WithFetchTimeout(d time.Duration) FetcherOption

func WithMaxResponseBytes(n int64) FetcherOption

func WithPrivateEndpoint() FetcherOption

type HTTPHostFetcher ¶ added in v0.1.3

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

HTTPHostFetcher is the default HostFetcher: it POSTs the request body to one fixed endpoint over a netguard-policed HTTP client, and returns the response body bounded.

The endpoint is fixed at construction, so it is the operator's choice and not the extension's. The client's dial control re-checks the resolved address against the policy at connect time, so a DNS answer that swings to a private or loopback address after the name passed its check is still refused (anti-rebinding).

func NewHTTPHostFetcher(endpoint string, opts ...FetcherOption) (*HTTPHostFetcher, error)

func (f *HTTPHostFetcher) Fetch(ctx context.Context, body []byte) ([]byte, error)

type HostFetcher ¶ added in v0.1.3

type HostFetcher interface {
	// Fetch sends body to the fetcher's endpoint and returns the response body.
	Fetch(ctx context.Context, body []byte) ([]byte, error)
}

HostFetcher sends a request body on behalf of a mounted extension tool and returns the response body. It is the network authority an extension borrows instead of holding: the extension process itself runs with egress fully denied, hands out opaque request bytes, and receives opaque response bytes back.

The destination is the fetcher's, never the extension's. Nothing in the request the extension hands out selects a host, a path, or a scheme, so a compromised extension cannot point the host's network at an address of its choosing (no SSRF, no exfiltration to a third party): the worst it can do is send garbage to the one endpoint the operator already granted it.

type HostSigner ¶ added in v0.1.3

type HostSigner interface {
	// Public is the public half of the signing key, as raw bytes.
	Public() []byte
	// Sign returns a detached signature over payload.
	Sign(ctx context.Context, payload []byte) ([]byte, error)
}

HostSigner produces detached signatures on behalf of a mounted extension tool, with a key the tool must not hold. The tool builds something that needs a signature; it hands out the bytes and gets a signature back. Public identifies the key so the tool can build against it; Sign returns a detached signature over the exact payload. What sits behind this port (a key held by another extension, a hardware token) is not the tool's concern, and the private key never crosses to the tool's process.

Public returns raw bytes rather than a key of any particular type: signers sit on different curves, and they all have to travel the same port. The host never interprets these bytes, so it does not need to know which curve produced them, and gains nothing by knowing.

Sign takes a context because the key need not be in this process: satisfying it may mean calling out to a signer extension, which can block and must be cancellable.

type LaunchRequest ¶ added in v0.1.3

type LaunchRequest struct {
	// Path is the trusted local binary to run. For a released extension it is the
	// cosign-verified artifact; for a dev extension it is the local build (dev mode only).
	Path string
	// Args are the fixed arguments to pass, verbatim.
	Args []string
	// EgressAllow is the effective outbound host allow-list (spec ∩ operator grant). Empty
	// means deny all egress: the extension reaches nothing.
	EgressAllow []string
}

LaunchRequest is what the handler hands the launcher to start one extension: the verified local binary path, the fixed arguments, and the already-computed effective egress allow-list. The handler has already intersected the spec's requested egress with the operator grant, so the launcher only enforces the result; it never reads egress from the spec directly.

type Launcher ¶ added in v0.1.3

type Launcher interface {
	Launch(ctx context.Context, req LaunchRequest) (Conn, error)
}

Launcher starts a verified binary as a confined, egress-locked subprocess and returns a duplex connection to its MCP stdio. It is the sandbox boundary of a process extension; the concrete SandboxLauncher enforces containment (refuse-rather-than-downgrade), deny-by-default egress, and a scrubbed environment, and a test supplies a fake so the mount and tool-bridge logic is exercised without a real process.

type Loader ¶

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

Loader turns a stored Extension resource into live surfaces by routing each declared surface block to its registered handler. It is the bridge from data to behaviour: the resource store admits and versions the spec, and the loader mounts it. A load is all-or-nothing. If any surface fails to mount, the surfaces already mounted for that extension are unloaded before the error returns, so an extension is never left half-wired.

The loader is level-triggered: Load both mounts a new extension and replaces one already loaded (it unmounts the previous surfaces first), so re-applying the same spec is idempotent and applying a changed spec reconciles to it. It is safe for concurrent use.

func NewLoader(reg *Registry) *Loader

func (l *Loader) Load(ctx context.Context, r resource.Resource) ([]string, error)

func (l *Loader) Mounted(id string) []string

func (l *Loader) Tools() []mission.Tool

func (l *Loader) Unload(ctx context.Context, id string) error

type Mount ¶

type Mount struct {
	// ID is the extension resource's stable id, the key OnUnload is called with.
	ID string
	// Name is the extension's natural name (its slug).
	Name string
	// Spec is the full decoded extension spec, shared context for every surface.
	Spec Spec
	// Surface is the surface key this mount is for (one of the Surface* constants or a
	// host-registered key).
	Surface string
	// Block is the raw typed block for this surface, for the handler to decode.
	Block json.RawMessage
}

Mount is what a handler receives when one surface of an extension is loaded. It carries the extension's identity and full spec (so the handler can read the base URL, auth, and safety envelope) alongside the raw block for the specific surface it handles. The handler decodes Block into its own type; nothing else does.

type OAuth2Spec ¶

type OAuth2Spec struct {
	// TokenURL is the token endpoint the access token is obtained from.
	TokenURL string `json:"tokenURL,omitempty"`
	// ClientID is the OAuth2 client identifier (semi-public, carried inline).
	ClientID string `json:"clientID,omitempty"`
	// Grant selects the flow: "client_credentials" (default) or "refresh_token".
	Grant string `json:"grant,omitempty"`
	// Scopes are requested at the token endpoint.
	Scopes []string `json:"scopes,omitempty"`
}

OAuth2Spec is the static configuration of an "oauth2" auth scheme. The access token is obtained from TokenURL and refreshed automatically; the credential the integration holds supplies the client secret (the client_credentials grant) or the refresh token (the refresh_token grant), resolved from the vault at call time.

type Origin ¶ added in v0.1.3

type Origin struct {
	// Repo is the "owner/name" whose releases are installed from.
	Repo string

	// Identity is the signature the release must carry. Note that Identity.Workflow is
	// the *reusable* release workflow, which lives in a different repository than Repo;
	// that is what Sigstore binds the signature to, and pinning Repo instead would
	// reject every genuine release.
	Identity sigstore.Identity
}

Origin describes where released extensions come from and who is trusted to have built them. It is the trust root for every extension flynn will execute: change these fields and flynn runs somebody else's code.

type Point ¶

type Point interface {
	// Capability is the surface key this handler serves (e.g. "integration").
	Capability() string
	// OnLoad wires one surface of an extension live.
	OnLoad(ctx context.Context, m Mount) error
	// OnUnload releases the surface previously loaded for the given extension id.
	OnUnload(ctx context.Context, id string) error
}

Point is the handler for one surface kind. Registering a Point under its Capability makes every spec that declares that surface loadable, which is how the engine gains new abilities without edits to the kind or the loader: a new surface is a new registration, not a new code path in the core.

OnLoad is called when an extension declaring this surface is loaded; it wires the surface live (registers tools, opens a provider) and returns an error to abort the load. OnUnload is called with the extension id when the extension is unloaded or replaced; it must release whatever OnLoad acquired and be idempotent, since a roll-back may unload a surface that never fully loaded. Implementations must be safe for concurrent use.

type ProcessBlock ¶ added in v0.1.3

type ProcessBlock struct {
	// Dev, when set, points at a locally-built binary by absolute path for the extension
	// authoring loop. It is unsigned by nature, so a launcher only honours it when dev mode
	// is explicitly enabled; in a normal run a dev source is refused.
	Dev *DevSource `json:"dev,omitempty"`
	// Release, when set, names a published, signed artifact the resolver downloads and
	// cosign-verifies against a pinned key before it is ever launched (the signed
	// distribution path). Exactly one of Dev or Release is used; Release wins if both are
	// present so a stray dev block cannot downgrade a released extension.
	Release *ReleaseSource `json:"release,omitempty"`
	// Args are fixed arguments appended to the resolved binary path, verbatim. They are
	// part of the spec, never model-influenced, so the launch command line is fully
	// determined before any model runs (closing the stdio-config injection class).
	Args []string `json:"args,omitempty"`
	// Tools, when non-empty, is an allow-list of the advertised tool names to mount; any
	// tool the server exposes that is not listed is ignored. Empty mounts every advertised
	// tool. It is a least-surface control: a spec can pin exactly the tools it vouches for.
	Tools []string `json:"tools,omitempty"`
}

ProcessBlock is the typed surface block for a process extension. It never carries the binary itself or any secret: it names how to obtain the (signed, verified) binary and how to run it, and the resolver turns that into a trusted local path. A stored spec is therefore safe to inspect and sync.

type ProcessHandler ¶ added in v0.1.3

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

ProcessHandler is the surface handler for out-of-process extensions. It launches an extension's verified binary in the sandbox, speaks MCP to it, and mounts its advertised tools as governed, namespaced, default-deny flynn tools. It is safe for concurrent use and holds one running subprocess per loaded extension id.

func NewProcessHandler(launcher Launcher, resolver Resolver, opts ...ProcessOption) *ProcessHandler

func (h *ProcessHandler) Capability() string

func (h *ProcessHandler) OnLoad(ctx context.Context, m Mount) error

func (h *ProcessHandler) OnUnload(_ context.Context, id string) error

func (h *ProcessHandler) SignerChannelFor(id string) (SignerChannel, error)

func (h *ProcessHandler) Tools(id string) []mission.Tool

type ProcessOption ¶ added in v0.1.3

type ProcessOption func(*ProcessHandler)

ProcessOption configures a ProcessHandler.

func WithCallTimeout(d time.Duration) ProcessOption

func WithDialTimeout(d time.Duration) ProcessOption

func WithEgressGrant(hosts []string) ProcessOption

func WithHostFetcher(fn func(extName, toolName string) HostFetcher) ProcessOption

func WithHostSigner(fn func(extName, toolName string) HostSigner) ProcessOption

func WithMaxDescriptionBytes(n int) ProcessOption

func WithMaxFetches(n int) ProcessOption

func WithMaxResultBytes(n int) ProcessOption

func WithMaxSignatures(n int) ProcessOption

func WithReserved(fn func(name string) bool) ProcessOption

type Registry ¶

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

Registry resolves a Point by the surface key it serves. It is fail-closed: a surface with no registered handler is an error at load time, never a silent skip, so an extension is either fully wired or rejected. It is safe for concurrent use.

func NewRegistry() *Registry

func (r *Registry) Capabilities() []string

func (r *Registry) Has(capability string) bool

func (r *Registry) Register(h Point) error

func (r *Registry) Resolve(capability string) (Point, error)

type ReleaseResolver ¶ added in v0.1.3

type ReleaseResolver struct {
	// Origin is who is trusted. The zero value trusts nobody and refuses everything.
	Origin Origin

	// Dir is where verified extensions are installed, one directory per name and version.
	Dir string

	// Downloader performs the size-capped, digest-checked downloads.
	Downloader *fetch.Downloader

	// BaseURL overrides the release host (tests point this at a local server). Empty
	// means GitHub.
	BaseURL string

	// GOOS and GOARCH override the target platform. Empty means this machine's.
	GOOS, GOARCH string
	// contains filtered or unexported fields
}

ReleaseResolver resolves a released extension to a local binary it has proven the origin of, and refuses to produce a path for anything it cannot prove.

The chain of trust runs: a keyless signature over the release's checksums.txt, made by the pinned workflow identity; that file commits to every archive by SHA-256; the archive downloaded for this platform must match its digest; the binary extracted from it is hashed and the hash recorded. Nothing is executed on the strength of where it was downloaded from, only on the strength of what signed it.

func (r ReleaseResolver) Resolve(ctx context.Context, extName string, block ProcessBlock) (string, []string, error)

type ReleaseSource ¶ added in v0.1.3

type ReleaseSource struct {
	Asset   string `json:"asset"`
	Version string `json:"version"`

	// Digests pins the exact bytes this flynn will run, keyed by "<goos>_<goarch>" and
	// holding the archive's SHA-256. It is what makes the pin structural rather than
	// nominal.
	//
	// Without it, the pin is a version STRING, and a git tag is mutable. Someone with write
	// access to the extensions repo could delete "token/v1.0.0", re-cut it against different
	// code, publish it through the very same trusted release workflow, and every flynn in
	// the world would fetch the new binary and verify its signature happily: the signature
	// only ever proved "the pinned workflow built this", never "this is the artifact we
	// reviewed". With the digest, that substitution is refused by a binary that was compiled
	// before the attack existed, because the hash it demands is baked into it.
	//
	// A platform absent from the map is unpinned and falls back to signature-only trust, so
	// a spec may pin the platforms it has hashes for without breaking the others.
	Digests map[string]string `json:"digests,omitempty"`
}

ReleaseSource names a published extension artifact by its asset name and version. The per-os/arch selection, download, and cosign verification are the resolver's job.

type Resolver ¶ added in v0.1.3

type Resolver interface {
	Resolve(ctx context.Context, extName string, block ProcessBlock) (path string, args []string, err error)
}

Resolver turns a process surface into a trusted local binary path plus its arguments. It is the trust boundary for the code itself: a released source is downloaded and cosign-verified against a pinned key, and a dev source is honoured only when dev mode is enabled. A resolver that cannot establish trust returns an error, and the handler then never launches anything, so unverified code never runs.

type RoutedSigner ¶ added in v0.1.3

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

RoutedSigner is a HostSigner whose key lives in ANOTHER extension: a signer extension, holding one chain's key and that chain's transaction parser.

This is the shape that lets the host stay ignorant. A host that holds a key cannot sign safely without understanding what it signs, so a host that holds a key must carry a parser for every format it might be asked to sign, and it stops being a general engine the moment it does. Move the key out and the parser goes with it: the host is left routing opaque bytes between two processes and reading none of them.

The separation is also what makes the check honest. The worker extension BUILDS the transaction; the signer HOLDS the key and independently decides whether to sign it. They are different artifacts, published and pinned separately. A worker compromised upstream gets no signature: it would have to compromise the signer too, and the signer is small enough to audit line by line and does nothing but parse, decide, and sign.

What must never happen is a worker that carries its own parser and vouches for its own payload. That is self-policing, and it buys exactly nothing.

The signer is reached over a SignerChannel, which is the host's private line to it, NOT the agent's tool surface. Its tools are never mounted, so the model can neither unlock the key nor ask for a signature behind the worker's back.

func NewRoutedSigner(ctx context.Context, ch SignerChannel, passphrase secret.Text, keyPath string) (*RoutedSigner, error)

func (s *RoutedSigner) PolicesPayloads() bool

func (s *RoutedSigner) Public() []byte

func (s *RoutedSigner) Sign(ctx context.Context, payload []byte) ([]byte, error)

type SafetySpec ¶

type SafetySpec struct {
	// EgressAllow lists additional hostnames the extension may reach beyond the
	// BaseURL host. Empty confines it to the BaseURL host alone.
	EgressAllow []string `json:"egressAllow,omitempty"`
	// ReadOnly marks an extension whose surfaces never mutate upstream state, so a
	// run granted only read authority may still use it.
	ReadOnly bool `json:"readOnly,omitempty"`
	// RateLimitPerMinute caps requests per minute across the extension's surfaces. 0
	// means the shared transport's default.
	RateLimitPerMinute int `json:"rateLimitPerMinute,omitempty"`
}

SafetySpec is the declared safety envelope for an extension. It is intent the runtime enforces: the egress waist confines network reach to EgressAllow (plus the BaseURL host), the capability gate refuses ungranted surfaces, and the transport honours the rate limit. A spec cannot weaken these by omission; an empty envelope is the most restrictive reading (base-URL host only).

type SandboxLauncher ¶ added in v0.1.3

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

SandboxLauncher is the production Launcher. It runs an extension binary inside a fresh sandbox at the kernel-confined tier: a read-only host, the syscall filter, a scrubbed deny-by-default environment (no secret ever reaches the process), memory and process-count caps, and deny-by-default egress restricted to exactly the effective allow-list. It requires confinement: on a host or platform that cannot contain the process, the launch is refused rather than downgraded, so an extension that cannot be contained never runs.

func NewSandboxLauncher(workRoot string) *SandboxLauncher

func (l *SandboxLauncher) Launch(ctx context.Context, req LaunchRequest) (Conn, error)

type SelfPolicing ¶ added in v0.1.3

type SelfPolicing interface {
	// PolicesPayloads reports that this signer applies its own policy before signing.
	PolicesPayloads() bool
}

SelfPolicing is implemented by a HostSigner that decides for itself whether a payload may be signed, because it holds the key AND understands the payload's format. A signer extension is the case that matters: it parses the transaction and refuses an unsafe one at the point the key is used, which is the only point where the question can honestly be asked.

The host REQUIRES this of any signer it uses (see serviceSign). It is not a convenience. The host holds no parser for any format, so a signer that does not judge its own payloads leaves nobody judging them, and signing bytes nobody has read is how the largest theft in this industry happened: a published, correctly-signed component was compromised upstream, and everyone who trusted its output signed what it asked them to.

Verifying an extension's signature proves which binary is running. It proves nothing about what that binary asks to be signed. Those are different questions, and only the second one is asked at the moment the key is used, by whoever holds the key.

type SignerChannel ¶ added in v0.1.3

type SignerChannel interface {
	// Unlock opens the signer's key and returns its public half and the curve it sits on. keyPath
	// names the sealed key for a signer that was not launched with its own --key (a released one);
	// it is empty for a signer that carries its own key, and the signer prefers its flag over it.
	Unlock(ctx context.Context, passphrase secret.Text, keyPath string) (pub []byte, curve string, err error)
	// SignPayload asks the signer to sign payload. The signer parses it and may refuse.
	SignPayload(ctx context.Context, payload []byte) ([]byte, error)
}

SignerChannel is the host's private line to a signer extension. It is deliberately NOT the agent's tool surface.

A mounted tool is a tool the MODEL can call. If a signer's tools were mounted, the model could unlock the key itself, or call the signing tool directly and skip the worker that was supposed to build the transaction. Neither is a thing an agent should be able to do, and neither is stopped by a capability grant on the worker, because the model would not be going through the worker at all.

So the signer's tools are never mounted (see reservedSignerTool). The host reaches them over this channel, which nothing model-facing can get at, and the only thing that ever crosses it is a passphrase the operator granted and a payload the worker built.

type SourceResolver ¶ added in v0.1.3

type SourceResolver struct {
	Release ReleaseResolver
	Dev     DevResolver
}

SourceResolver routes an extension to the resolver its source kind demands: a published release goes through signature verification, a dev binary through the explicit dev-mode opt-in.

A release wins whenever both are declared. That is the point of the ordering: a spec carrying a stray dev block, whether from an author's machine or from an attacker who managed to edit a stored spec, must not be able to substitute an unsigned local binary for the signed release the operator asked for. Downgrade is the attack; refusing to downgrade is the defence.

func (s SourceResolver) Resolve(ctx context.Context, extName string, block ProcessBlock) (string, []string, error)

type Spec ¶

type Spec struct {
	// DisplayName is a human label; empty falls back to the resource name.
	DisplayName string `json:"displayName,omitempty"`
	// Version is the extension's own published version, used for upgrade ordering and
	// provenance. It is distinct from the resource revision the store assigns: one
	// tracks what the author shipped, the other tracks how many times this record was
	// written.
	Version string `json:"version,omitempty"`
	// Provider groups extensions that share an upstream (e.g. "cloudflare"), so
	// several surfaces and credential roles can be reasoned about as one provider.
	Provider string `json:"provider,omitempty"`

	// BaseURL is the root the surfaces address. Surface blocks carry paths relative to
	// it so the host is declared once.
	BaseURL string `json:"baseURL,omitempty"`
	// Protocol names how the surfaces talk to the upstream. Empty means "https". A
	// protocol the declarative interpreter does not understand (a binary or streaming
	// protocol) is served through the optional-code port; see Code.
	Protocol string `json:"protocol,omitempty"`

	// Auth describes how a request authenticates. It never carries a secret value:
	// the credential is referenced by name and resolved from the vault at call time,
	// so a stored spec is safe to sync and inspect.
	Auth AuthSpec `json:"auth,omitempty"`

	// Capabilities are the tags that gate this extension. A surface is mounted and
	// surfaced as a tool only when its capability is granted to the run and the
	// referenced credential is configured, the same gating every other context is
	// retrieved under.
	Capabilities []string `json:"capabilities,omitempty"`

	// Safety bounds what the extension may do at runtime (egress allow-list, read-only
	// marking, rate limit). The egress waist and capability gate enforce it; the spec
	// only declares the intent.
	Safety SafetySpec `json:"safety,omitempty"`

	// Surfaces are the capability blocks this extension exposes, keyed by surface
	// (see the Surface* constants). Each value is the typed block for that surface,
	// left as raw JSON here because only the surface's handler knows its shape. This
	// is the open extension point: registering a handler under a new key makes specs
	// that declare it loadable, with no change to this kind.
	Surfaces map[string]json.RawMessage `json:"surfaces,omitempty"`

	// Code, when set, routes this extension's surfaces through a compiled
	// implementation registered in-process under the named code port, instead of the
	// declarative interpreter. The manifest carries only the name, never Go, so the
	// spec stays pure data the store can admit, version, and sync. This is the
	// single, explicit boundary at which compiled code enters; pure-spec is the
	// default.
	Code *CodeRef `json:"code,omitempty"`
}

Spec is an Extension's desired shape: everything needed to reach and use an external system, as pure data. Every field is optional so a minimal Extension is just a name and one surface; the zero Spec is an inert extension that exposes nothing. The extension's natural name (its slug) is the resource Name, so the spec carries no separate id.

func DecodeSpec(r resource.Resource) (Spec, error)

func (s Spec) Encode() (json.RawMessage, error)

func (s Spec) Surface(key string) (json.RawMessage, bool)

type Status ¶

type Status struct {
	// ObservedGeneration is the spec generation the status reflects.
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
	// Grade is how far the spec has been validated: GradeUnvalidated, GradeSchemaValid
	// (admitted by the kind schema), or GradeProbed (a live probe call succeeded in the
	// sandbox). Acquisition and runtime authoring promote the grade.
	Grade string `json:"grade,omitempty"`
	// LastProbe is the RFC3339 timestamp of the last probe, supplied by the caller's
	// clock (never read from the wall clock here so status stays replay-equivalent).
	// Empty means never probed.
	LastProbe string `json:"lastProbe,omitempty"`
	// Enabled reports whether the extension is currently loaded and its surfaces
	// mounted.
	Enabled bool `json:"enabled,omitempty"`
	// MountedSurfaces lists the surface keys the loader has mounted, in sorted order.
	MountedSurfaces []string `json:"mountedSurfaces,omitempty"`
}

Status is an Extension's observed state, set by the loader and reconcilers rather than admitted against the spec schema. It records how far the extension has been validated, whether it is enabled, and which surfaces are currently mounted.

func DecodeStatus(r resource.Resource) (Status, error)

func (s Status) Encode() (json.RawMessage, error)

type ToolSource ¶

type ToolSource interface {
	Tools(id string) []mission.Tool
}

ToolSource is the optional interface a Point implements when its surface contributes callable tools to the agent. Not every surface does (an auth provider contributes credentials, not tools), so it is separate from Point: the loader type-asserts for it and collects tools only from handlers that expose them. This is the tool-bridge boundary. The actual tools a surface builds (an API call per endpoint, a deploy action) are the surface handler's concern; the keystone only defines how they reach the agent.

Tools returns the live tools mounted for one extension id, or nil if that extension contributes none. It is called after OnLoad has mounted the surface.