plugin

package
v1.2.9 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 7, 2026 License: MIT Imports: 28 Imported by: 0

Documentation

Overview

Package plugin is the wick connector plugin platform: the shared transport (hashicorp/go-plugin + gRPC) used by the host to drive a connector that runs in its own process, and the SDK a connector binary uses to serve itself. See docs/proposals/connector-plugin-platform.

Index

Constants

View Source
const (
	KindConnector = "connector"
	KindTool      = "tool"
	KindJob       = "job"
	KindService   = "service"
)

Plugin kinds. connector and job have host-side adapters; tool/service are accepted by the manifest + build tooling so the layout and CLI are forward-compatible.

View Source
const (
	EnvPluginToken = "WICK_PLUGIN_TOKEN"
	EnvBaseURL     = "WICK_BASE_URL"
)

Callback env the host sets on a service plugin so it can call wick's REST API back without holding any other credential (same idea as WICK_CLI_TOKEN). The token is scoped to the plugin and revocable; a plugin must never log it.

View Source
const (
	AuthPublic  = "public"       // anyone
	AuthToken   = "token"        // Authorization: Bearer <admin-generated token>
	AuthSession = "wick-session" // a signed-in wick user
)

Route auth modes of a service plugin.

View Source
const (
	CapRemoteSource = "remote_source"
	// CapRemoteInject: the remote source also takes a message for a turn
	// still running (RemotePathInject).
	CapRemoteInject = "remote_inject"
	// CapRemoteCancel: the remote source can also stop a running turn on
	// the remote's side (RemotePathCancel).
	CapRemoteCancel = "remote_cancel"
	// CapRemoteSessionFields: the remote source declares new-session fields
	// (RemotePathSessionFields), e.g. a repository and a branch.
	CapRemoteSessionFields = "remote_session_fields"
)

Capability names a service plugin can declare.

View Source
const (
	RemotePrefix       = "/_wick/"
	RemotePathSend     = "/_wick/remote/send"     // POST RemoteTurn → {"handle":…}
	RemotePathEvents   = "/_wick/remote/events"   // GET ?handle= → SSE of RemoteEvent
	RemotePathDone     = "/_wick/remote/done"     // POST {"handle":…}
	RemotePathDescribe = "/_wick/remote/describe" // GET → {"name","detail","inject","cancel"}
	RemotePathInject   = "/_wick/remote/inject"   // POST RemoteInject → 204
	// RemotePathCancel stops the turn handle on the remote's side (Stop in
	// wick). Only sent when describe says "cancel": true.
	RemotePathCancel = "/_wick/remote/cancel" // POST {"handle":…} → 204
	// RemotePathSessionFields lists the fields a new session of an agent
	// asks for, defaults filled from that agent's config. Only asked when
	// describe says "session_fields": true.
	RemotePathSessionFields = "/_wick/remote/session-fields" // POST RemoteSessionFieldsRequest → {"fields":[…]}
)

Internal paths a remote_source service plugin serves on its socket. The host never forwards a client path under RemotePrefix, so only wick reaches them.

View Source
const (
	HeaderUserID    = "X-Wick-User-Id"
	HeaderUserEmail = "X-Wick-User-Email"
	HeaderUserName  = "X-Wick-User-Name"
	HeaderUserRole  = "X-Wick-User-Role" // "admin" or "user"; absent = no session
	HeaderUserTags  = "X-Wick-User-Tags" // comma-separated tag names
	HeaderBase      = "X-Wick-Base"      // "/tools/{key}"
	// HeaderLayout on a plugin response asks the host to wrap the body (an
	// HTML fragment) in wick's page layout; HeaderTitle names the page.
	HeaderLayout = "X-Wick-Layout"
	HeaderTitle  = "X-Wick-Title"
	// LayoutPage is the HeaderLayout value for a full wick page.
	LayoutPage = "page"
	// HeaderPrefix is the namespace the host strips from client requests.
	HeaderPrefix = "X-Wick-"
)

Headers the host sets on every proxied tool request. Any client-sent value is dropped before the host writes its own, so a plugin can trust them.

View Source
const DefaultAutoOffIdleSeconds = 15 * 60

DefaultAutoOffIdleSeconds is the idle limit of an auto-off service whose plugin sets none.

View Source
const EnvReattachOut = "WICK_PLUGIN_REATTACH_OUT"

EnvReattachOut, when set on a plugin process, switches Serve into debug (reattach) mode: instead of the normal go-plugin stdout handshake — which only works when the host is the process that spawned it — the plugin serves in test mode and writes its ReattachConfig as JSON to the named file. A host that finds a LIVE reattach file for this key attaches to this already-running process (see Manager.spawn) so breakpoints in the plugin bind.

Run the plugin binary under a debugger (dlv) with this set, let it write the file, then start wick-lab; wick-lab attaches instead of spawning its own un-debuggable child.

View Source
const EnvToolSocket = "WICK_PLUGIN_SOCKET"

EnvToolSocket names the unix socket a tool plugin must serve HTTP on. The host picks the path (inside its 0700 run dir) and passes it at spawn; the plugin creates it 0600 before the go-plugin handshake, so a finished handshake means the socket already accepts requests.

View Source
const JobPluginName = "job"

JobPluginName is the dispense key for job plugins.

View Source
const ManifestSchemaVersion = 1

ManifestSchemaVersion is the current envelope format version.

View Source
const MaxGRPCMessageBytes = 64 << 20

MaxGRPCMessageBytes is the plugin transport's max gRPC message size (both directions, both ends). gRPC defaults to 4 MiB recv, which is too small for ops that carry file payloads — e.g. extension_install sends a browser extension as base64 (a 4 MB .crx becomes ~6 MB on the wire). 64 MiB matches the connector-side upload cap. Server + client must agree, so both read this.

View Source
const MinProtoVersion = 1

MinProtoVersion is the OLDEST proto version this host still accepts. The host supports the inclusive range [MinProtoVersion, ProtoVersion]; a plugin built against any version in that range loads, anything outside is rejected at handshake/verify with a clear error (never a crash).

This is the range-negotiation contract (§19.2): bumping ProtoVersion for a breaking change while leaving MinProtoVersion behind opens a transition window where v(old) and v(new) plugins both run; dropping support for an old version is a deliberate MinProtoVersion bump, not an accident.

View Source
const PluginName = "connector"

PluginName is the dispense key both sides agree on.

View Source
const ProtoVersion = 1

ProtoVersion is the wire-contract version a freshly built plugin stamps into its manifest (the version this build of the SDK speaks natively). It bumps ONLY on a breaking proto change.

View Source
const RemoteEventSchema = 1

RemoteEventSchema is the event schema version RemoteEvent follows.

View Source
const ToolPluginName = "tool"

ToolPluginName is the dispense key for tool plugins.

Variables

View Source
var ErrJobRun = errors.New("job run failed")

ErrJobRun wraps a run failure reported by the job itself (vs a transport error). Callers can errors.Is against it.

View Source
var ErrPluginOp = errors.New("plugin operation error")

ErrPluginOp wraps an operation-level error returned by the plugin (vs a transport error). Callers can errors.Is against it.

View Source
var Handshake = goplugin.HandshakeConfig{
	ProtocolVersion:  ProtoVersion,
	MagicCookieKey:   "WICK_CONNECTOR_PLUGIN",
	MagicCookieValue: "b3f1c2a4-wick-connector-grpc",
}

Handshake is the basic mutual sanity check go-plugin runs before any RPC: a plugin launched without the matching magic cookie exits with a human-readable error instead of hanging.

View Source
var JobVersionedPlugins = func() map[int]goplugin.PluginSet {
	out := map[int]goplugin.PluginSet{}
	for _, v := range SupportedProtoVersions() {
		out[v] = goplugin.PluginSet{JobPluginName: &JobGRPCPlugin{}}
	}
	return out
}()

JobVersionedPlugins is the host-side plugin set for job plugins.

Kinds lists every plugin kind in display order.

View Source
var RequireSignature bool

RequireSignature, when true (set via ldflags in release builds), makes the loader reject any plugin without a valid signature from a trusted key. The env var WICK_PLUGIN_REQUIRE_SIGNATURE ("1"/"0") overrides it at runtime.

View Source
var ToolVersionedPlugins = func() map[int]goplugin.PluginSet {
	out := map[int]goplugin.PluginSet{}
	for _, v := range SupportedProtoVersions() {
		out[v] = goplugin.PluginSet{ToolPluginName: &ToolGRPCPlugin{}}
	}
	return out
}()

ToolVersionedPlugins is the host-side plugin set for tool plugins.

View Source
var TrustedPubKey string

TrustedPubKey is the publisher's base64 ed25519 public key baked into a released wick binary via -ldflags. Empty in dev builds.

View Source
var Version = "0.0.0-dev"

Version is the connector release version stamped into the manifest. It is overridden at build time via -ldflags "-X .../pkg/plugin.Version=1.2.3".

View Source
var VersionedPlugins = buildVersionedPlugins()

VersionedPlugins maps proto_version -> plugin set. The host advertises every version in [MinProtoVersion, ProtoVersion]; go-plugin negotiates the highest version common to host and plugin and rejects (clear error, no crash) a plugin whose version falls outside the host's range. Built from the supported range so adding a future v2 plugin set is the only edit needed.

Functions

func ApplyRlimits added in v1.2.9

func ApplyRlimits()

ApplyRlimits applies the plugin-process resource limits (the same ones ServeJob and the connector Serve apply) for plugin mains that live outside this package, such as toolplugin.ServeTool.

func DataDir added in v0.28.4

func DataDir(key string) string

DataDir returns the persistent per-plugin work directory for the given plugin key — the place a plugin should store downloaded assets, caches, and session state so they SURVIVE (unlike os.TempDir(), which the OS / Storage Sense wipes).

It is resolved entirely plugin-side from the running binary's own location — no env var, no host cooperation. Installed plugin binaries live at

<appDataDir>/plugins/connectors/<key>/<key>[.exe]

so the sibling data dir is two levels up from the binary's folder, alongside the connectors/ dir:

<appDataDir>/plugins/<key>/

This sits ALONGSIDE the connectors/ dir (binaries + plugin.json), never inside it, so wiping a plugin's data never touches its installed binary or catalog.

If the binary isn't laid out under a .../plugins/connectors/ tree (e.g. a bare `go run` during development, or a `go test`), it falls back to <os-temp>/wick-plugins/<key> — good enough for throwaway runs, and the only case where OS temp is acceptable.

func DumpManifest

func DumpManifest(mod connector.Module) ([]byte, error)

DumpManifest returns json.Marshal(mod) — the manifest is the module itself, so the plugin.json on disk can never drift from the binary.

func GRPCServer added in v1.2.9

func GRPCServer(opts []grpc.ServerOption) *grpc.Server

GRPCServer is the go-plugin GRPCServer factory every wick plugin kind serves with (raised message limits). Setting it is also what makes go-plugin speak gRPC instead of net/rpc.

func GenerateKeypair

func GenerateKeypair() (privB64, pubB64 string)

GenerateKeypair returns a fresh ed25519 keypair as base64 strings (private = 64-byte seed||pub, public = 32-byte).

func KindFolder added in v1.2.9

func KindFolder(kind string) string

KindFolder is the per-kind install folder under the plugins root (plugins/connectors, plugins/jobs, plugins/tools, plugins/services).

func NewJobServer added in v1.2.9

func NewJobServer(mod job.Module) pb.JobServer

NewJobServer builds the plugin-side Job service for one job module.

func NewServer

func NewServer(mod connector.Module) pb.ConnectorServer

NewServer builds the plugin-side service for one connector module.

func NormalizeKind

func NormalizeKind(k string) string

NormalizeKind returns a valid kind, defaulting empty/unknown to connector.

func ProtoVersionSupported

func ProtoVersionSupported(v int) bool

ProtoVersionSupported reports whether v is within the accepted range.

func ReadReattachConfig added in v0.33.0

func ReadReattachConfig(path string) (*goplugin.ReattachConfig, error)

ReadReattachConfig loads a reattach file and rebuilds the ReattachConfig a host needs to attach — but ONLY when the plugin is actually reachable. It dials the address (short timeout) as the real liveness signal: a stale file from a stopped/relaunched debugger fails the dial, and the caller falls back to a normal spawn instead of attaching to a dead process. This is what makes reattach robust against dlv relaunches (new pid/port each time).

func ReattachPluginSet added in v0.33.0

func ReattachPluginSet() goplugin.PluginSet

ReattachPluginSet is the plugin descriptor set a host must pass as ClientConfig.Plugins when reattaching. Reattach bypasses version negotiation, so go-plugin never copies the matching VersionedPlugins entry into config.Plugins on its own; without this the dispense fails with "unknown plugin type". The host descriptor carries no Impl (it receives a client).

func RequireSig

func RequireSig() bool

RequireSig reports the effective signature-required policy (env overrides the baked default).

func Serve

func Serve(mod connector.Module)

Serve is the entire main() of a connector plugin binary. Call it with the module the binary wraps. When invoked with --dump-manifest it prints the manifest JSON and exits (used by `make plugins` / CI); otherwise it serves the gRPC plugin and blocks until the host disconnects.

func ServeJob added in v1.2.9

func ServeJob(mod job.Module)

ServeJob is the entire main() of a job plugin binary. With --dump-manifest it prints the kind=job manifest and exits; otherwise it serves the Job service until the host kills it (right after Run returns).

func SignSHA256

func SignSHA256(privKeyPath, sha256hex string) (string, error)

SignSHA256 reads a base64 ed25519 private key from privKeyPath and signs the sha256 hex string, returning the base64 signature.

func SupportedProtoVersions

func SupportedProtoVersions() []int

SupportedProtoVersions returns every proto version this host can speak, newest first. Used both to advertise VersionedPlugins to go-plugin and to validate a manifest's declared version.

func TrustedKeys

func TrustedKeys() []string

TrustedKeys returns every trusted base64 public key: the baked TrustedPubKey plus any in WICK_PLUGIN_PUBKEY (comma-separated).

func ValidAuth added in v1.2.9

func ValidAuth(a string) bool

ValidAuth reports whether a is a known route auth mode.

func ValidateKey

func ValidateKey(key string) error

ValidateKey enforces that a plugin's Meta.Key is a safe slug. Key is the one identity used everywhere — the source folder, the zip name, the on-disk install dir (DefaultDir/<key>), and the runtime registry key — so it must be a plain lowercase slug with no path separators or traversal (it becomes a directory name; a key like "../x" or "a/b" would escape the plugins dir). Enforced at BOTH build time and install time so a hand-written manifest can't sneak a bad key past the build.

func VerifyManifest

func VerifyManifest(m Manifest, binaryPath string) error

VerifyManifest checks a plugin envelope against the binary at binaryPath and the host's trust policy. Returns nil when the plugin is safe to load. Order: os_arch -> proto_version -> sha256 integrity -> signature.

func VerifySHA256

func VerifySHA256(trustedPubsB64 []string, sha256hex, sigB64 string) bool

VerifySHA256 reports whether sigB64 is a valid signature of sha256hex by ANY of the trusted base64 public keys. Bad inputs return false (no panic).

Types

type ConnectorGRPCPlugin

type ConnectorGRPCPlugin struct {
	goplugin.NetRPCUnsupportedPlugin
	Impl pb.ConnectorServer
}

ConnectorGRPCPlugin is the go-plugin descriptor. Impl is set only on the plugin side (it carries the server implementation); the host leaves it nil and receives a client from GRPCClient.

func (*ConnectorGRPCPlugin) GRPCClient

func (*ConnectorGRPCPlugin) GRPCServer

func (p *ConnectorGRPCPlugin) GRPCServer(_ *goplugin.GRPCBroker, s *grpc.Server) error

type ExecCall

type ExecCall struct {
	Operation string
	Input     map[string]string
	Creds     map[string]string
	RequestID string
	SessionID string
}

ExecCall is the host-side call descriptor the adapter closure fills from a *connector.Ctx (operation + plaintext input + plaintext creds).

type ExecResult added in v1.2.9

type ExecResult struct {
	JSON           []byte
	Mask           []string
	MaskIgnoreCase []string
}

ExecResult is what one plugin operation returns: the result JSON plus the values the operation passed to c.Mask / c.MaskIgnoreCase. The plugin has no encryption key, so those values arrive in the clear and the host masks them.

type GRPCConn

type GRPCConn interface {
	Execute(ctx context.Context, call ExecCall) (ExecResult, error)
	ExecuteStream(ctx context.Context, call ExecCall) (ExecResult, error)
	Schema(ctx context.Context) ([]byte, error)
	ResolveIdentity(ctx context.Context, accessToken string) (userID, displayName string, err error)
}

GRPCConn is the host-facing surface of a connector plugin client. The manager hands this to the adapter closure; *grpcClient implements it.

type JobConn added in v1.2.9

type JobConn interface {
	// Run calls the job once. onLog receives each progress line as it
	// streams; the returned string is the job's markdown result.
	Run(ctx context.Context, trigger string, cfg map[string]string, onLog func(string)) (string, error)
	Schema(ctx context.Context) ([]byte, error)
}

JobConn is the host-facing surface of a job plugin client.

type JobGRPCPlugin added in v1.2.9

type JobGRPCPlugin struct {
	goplugin.NetRPCUnsupportedPlugin
	Impl pb.JobServer
}

JobGRPCPlugin is the go-plugin descriptor for the Job service. Impl is set only on the plugin side.

func (*JobGRPCPlugin) GRPCClient added in v1.2.9

func (p *JobGRPCPlugin) GRPCClient(_ context.Context, _ *goplugin.GRPCBroker, c *grpc.ClientConn) (any, error)

func (*JobGRPCPlugin) GRPCServer added in v1.2.9

func (p *JobGRPCPlugin) GRPCServer(_ *goplugin.GRPCBroker, s *grpc.Server) error

type JobModule added in v1.2.9

type JobModule struct {
	Meta    job.Meta        `json:"meta"`
	Configs []entity.Config `json:"configs,omitempty"`
}

JobModule is the job half of a kind=job manifest: the job's static meta and its config fields (the RunFunc stays in the binary).

type Manifest

type Manifest struct {
	SchemaVersion int `json:"schema_version"`
	// Kind is the plugin kind: "connector" (default), "tool", or "job". The
	// platform routes installed plugins by kind into the matching registry;
	// all kinds share the same gRPC service (Execute(op,args)→result is generic
	// enough for a tool's Run(input) and a job's Run(trigger)). Empty = the
	// pre-kind default "connector" for backward compatibility.
	Kind         string           `json:"kind,omitempty"`
	Version      string           `json:"version"`
	ProtoVersion int              `json:"proto_version"`
	Entry        string           `json:"entry"`
	OSArch       []string         `json:"os_arch"`
	SHA256       string           `json:"sha256"`
	Signature    string           `json:"signature"`
	Module       connector.Module `json:"module"`
	// Job carries the job meta + configs for kind=job (Module.Meta mirrors its
	// key/name so key-based install/scan code stays kind-agnostic).
	Job *JobModule `json:"job,omitempty"`
	// Tool carries the tool meta, configs, webhook routes, and keep_warm for
	// kind=tool (Module.Meta mirrors key/name the same way as for jobs).
	Tool *ToolModule `json:"tool,omitempty"`
	// Service carries the routes, auth modes, capabilities, and callback
	// scopes for kind=service.
	Service *ServiceModule `json:"service,omitempty"`
}

Manifest is the on-disk plugin.json envelope: the connector module plus the distribution metadata the host needs to verify and load it. The connector module marshals with its func fields excluded (json:"-"), so the envelope is fully round-trippable.

func BuildSelfJobManifest added in v1.2.9

func BuildSelfJobManifest(mod job.Module, signKeyPath string) (Manifest, error)

BuildSelfJobManifest is BuildSelfManifest for a job binary: kind=job, the job meta in Job, and Module.Meta mirroring key/name/description/icon so the shared install/scan code (keyed by Module.Meta.Key) works unchanged.

func BuildSelfManifest

func BuildSelfManifest(mod connector.Module, signKeyPath string) (Manifest, error)

BuildSelfManifest builds the envelope for a connector plugin binary from the binary itself (self-pack): it hashes os.Executable() and, when signKeyPath is non-empty, signs that hash. mod is the connector's module.

func BuildSelfServiceManifest added in v1.2.9

func BuildSelfServiceManifest(sm ServiceModule, signKeyPath string) (Manifest, error)

BuildSelfServiceManifest is BuildSelfManifest for a service binary.

func BuildSelfToolManifest added in v1.2.9

func BuildSelfToolManifest(tm ToolModule, signKeyPath string) (Manifest, error)

BuildSelfToolManifest is BuildSelfManifest for a tool binary: kind=tool, the tool half in Tool, and Module.Meta mirroring key/name/description/icon so the shared install/scan code keeps working unchanged.

func (Manifest) MarshalJSON added in v1.2.9

func (m Manifest) MarshalJSON() ([]byte, error)

MarshalJSON leaves the legacy "module" block out of a kind=service manifest: its identity and configs live in "service", and the module there only ever carried a mirrored meta with null configs. Other kinds keep it.

func (*Manifest) UnmarshalJSON added in v1.2.9

func (m *Manifest) UnmarshalJSON(b []byte) error

UnmarshalJSON reads both shapes. A service manifest without "module" gets Module.Meta mirrored from Service.Meta so key-based install/scan code stays kind-agnostic; an older one that still carries the block loads unchanged.

type RemoteEvent added in v1.2.9

type RemoteEvent struct {
	Kind   string `json:"kind"`
	Text   string `json:"text,omitempty"`
	Status string `json:"status,omitempty"`
	Detail string `json:"detail,omitempty"`
	Name   string `json:"name,omitempty"`
	URL    string `json:"url,omitempty"`
	MIME   string `json:"mime,omitempty"`
	Note   string `json:"note,omitempty"`
}

RemoteEvent mirrors wick's remote event schema v1 field for field (kind is text_delta | text | status | attachment | done | error).

type RemoteInject added in v1.2.9

type RemoteInject struct {
	Handle string `json:"handle"`
	Text   string `json:"text"`
}

RemoteInject is a message for the turn handle while it still runs: the plugin hands it to the remote and the running turn's stream carries the answer. Only sent when describe says "inject": true.

type RemoteSendResult added in v1.2.9

type RemoteSendResult struct {
	Handle    string `json:"handle"`
	ContextID string `json:"context_id,omitempty"`
	// Options are the SessionField values the remote session actually uses
	// (defaults resolved), shown read-only on the session afterwards.
	Options map[string]string `json:"options,omitempty"`
}

RemoteSendResult is what RemotePathSend answers.

type RemoteSessionFieldsRequest added in v1.2.9

type RemoteSessionFieldsRequest struct {
	AgentID string            `json:"agent_id,omitempty"`
	Config  map[string]string `json:"config,omitempty"`
}

RemoteSessionFieldsRequest asks for an agent's new-session fields.

type RemoteTurn added in v1.2.9

type RemoteTurn struct {
	Text      string `json:"text"`
	SessionID string `json:"session_id,omitempty"`
	// ContextID is the conversation the plugin handed back on a previous
	// turn of the same session ("" on the first).
	ContextID string `json:"context_id,omitempty"`
	// AgentID is the wick remote agent the turn belongs to.
	AgentID string `json:"agent_id,omitempty"`
	// Config is that agent's RemoteConfigs values in plaintext (secrets
	// decrypted; only ever sent over the plugin's local socket). An unset
	// key means the agent left it empty.
	Config map[string]string `json:"config,omitempty"`
	// Options are the session's SessionField answers by key, as chosen when
	// the session was created (an unset key = use the field's default).
	Options map[string]string `json:"options,omitempty"`
}

RemoteTurn is one user message a Team remote agent sends to the plugin.

type ServiceAutoOff added in v1.2.9

type ServiceAutoOff struct {
	Supported bool `json:"supported"`
	// Reason says why the plugin cannot auto-off (shown on the dashboard).
	Reason string `json:"reason,omitempty"`
	// DefaultIdleSeconds is the idle limit; 0 = DefaultAutoOffIdleSeconds.
	DefaultIdleSeconds int `json:"default_idle_seconds,omitempty"`
}

ServiceAutoOff is the wire form of service.AutoOff: whether the host may stop the process after it has been idle (no request in flight, no remote turn open) and start it again on the next request. It only sets the default; the wick admin can force auto-off on or off per service.

type ServiceModule added in v1.2.9

type ServiceModule struct {
	Meta    ToolMeta        `json:"meta"`
	Routes  []ServiceRoute  `json:"routes"`
	Configs []entity.Config `json:"configs,omitempty"`
	// RemoteConfigs are the per-agent fields of a remote_source plugin:
	// filled when a remote agent is created or edited, stored per agent and
	// sent on every RemoteTurn.Config.
	RemoteConfigs []entity.Config `json:"remote_configs,omitempty"`
	// Capabilities lists extras the plugin implements, e.g. remote_source
	// (a Team remote agent source served on RemotePath*).
	Capabilities []string `json:"capabilities,omitempty"`
	// CallbackScopes are the wick REST scopes the plugin's WICK_PLUGIN_TOKEN
	// may use.
	CallbackScopes []string `json:"callback_scopes,omitempty"`
	// AutoOff is the plugin's own say on being stopped while idle; nil is
	// the same as Supported=false with no reason.
	AutoOff *ServiceAutoOff `json:"auto_off,omitempty"`
}

ServiceModule is the service half of a kind=service manifest.

func (ServiceModule) Has added in v1.2.9

func (m ServiceModule) Has(c string) bool

Has reports whether the module declares capability c.

func (ServiceModule) MatchRoute added in v1.2.9

func (m ServiceModule) MatchRoute(path string) (ServiceRoute, bool)

MatchRoute returns the route of the longest prefix matching path (relative to /x/{key}, always starting with "/").

type ServiceRoute added in v1.2.9

type ServiceRoute struct {
	Prefix string `json:"prefix"`
	Auth   string `json:"auth"`
}

ServiceRoute is one path prefix (relative to /x/{key}) and its auth mode. The longest matching prefix wins; a path no route matches answers 404.

type SessionField added in v1.2.9

type SessionField struct {
	Key         string `json:"key"`
	Label       string `json:"label"`
	Placeholder string `json:"placeholder,omitempty"`
	// Default is used when the user leaves the field empty, usually
	// resolved from the agent's config and then the plugin's.
	Default  string `json:"default,omitempty"`
	Required bool   `json:"required,omitempty"`
}

SessionField is one value a remote agent's new session asks for before its first message (e.g. a repository and a branch). wick renders whatever the plugin declares as editable chips in the new chat's composer, keeps the answers on the session and sends them on RemoteTurn.Options; once the remote session exists they are read-only.

type ToolConn added in v1.2.9

type ToolConn interface {
	Configure(ctx context.Context, cfg map[string]string) error
	Health(ctx context.Context) error
}

ToolConn is the host-facing control surface of a running tool plugin.

type ToolGRPCPlugin added in v1.2.9

type ToolGRPCPlugin struct {
	goplugin.NetRPCUnsupportedPlugin
	Impl pb.ToolServer
}

ToolGRPCPlugin is the go-plugin descriptor for the Tool control service. Impl is set only on the plugin side.

func (*ToolGRPCPlugin) GRPCClient added in v1.2.9

func (*ToolGRPCPlugin) GRPCServer added in v1.2.9

func (p *ToolGRPCPlugin) GRPCServer(_ *goplugin.GRPCBroker, s *grpc.Server) error

type ToolMeta added in v1.2.9

type ToolMeta struct {
	Key         string              `json:"key"`
	Name        string              `json:"name"`
	Description string              `json:"description,omitempty"`
	Icon        string              `json:"icon,omitempty"`
	Category    string              `json:"category,omitempty"`
	ExternalURL string              `json:"external_url,omitempty"`
	Visibility  string              `json:"visibility,omitempty"` // entity.ToolVisibility; "" = private
	FullScreen  bool                `json:"full_screen,omitempty"`
	DefaultTags []entity.DefaultTag `json:"default_tags,omitempty"`
	// Replaces lists keys of tools this plugin takes over (tool.Tool.Replaces).
	Replaces []string `json:"replaces,omitempty"`
}

ToolMeta is the manifest form of tool.Tool. It is a plain copy (not tool.Tool itself) so pkg/plugin — linked into every connector binary — does not pull in pkg/tool and its templ render stack.

type ToolModule added in v1.2.9

type ToolModule struct {
	Meta     ToolMeta        `json:"meta"`
	Configs  []entity.Config `json:"configs,omitempty"`
	Webhooks []ToolWebhook   `json:"webhooks,omitempty"`
	// KeepWarm keeps the process running instead of idle-killing it — for
	// tools whose webhook must answer fast (Slack's 3 s trigger_id window).
	KeepWarm bool `json:"keep_warm,omitempty"`
}

ToolModule is the tool half of a kind=tool manifest.

type ToolWebhook added in v1.2.9

type ToolWebhook struct {
	Method string `json:"method"`
	Path   string `json:"path"`
	Group  string `json:"group"`
}

ToolWebhook is one route a tool plugin opened with Router.WebhookGroup. Paths are relative to /tools/{key}. Only these exact METHOD+path pairs are reachable without a wick session; anything else under Group stays 404.

Directories

Path Synopsis
Package toolplugin is the plugin side of tool plugins: ServeTool turns an ordinary tool.Module (the same Register func a built-in tool uses) into a binary that serves HTTP on the unix socket the host names, while the host reverse-proxies /tools/{key}/* to it and wraps page fragments in wick's layout.
Package toolplugin is the plugin side of tool plugins: ServeTool turns an ordinary tool.Module (the same Register func a built-in tool uses) into a binary that serves HTTP on the unix socket the host names, while the host reverse-proxies /tools/{key}/* to it and wraps page fragments in wick's layout.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL