plugin

package
v1.18.0 Latest Latest
Warning

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

Go to latest
Published: Nov 1, 2026 License: MIT Imports: 39 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 (
	ScopeHostWhoami           = "whoami"
	ScopeHostUsersRead        = "users.read"
	ScopeHostAccountsRead     = "accounts.read"
	ScopeHostSessionsRead     = "sessions.read"
	ScopeHostSessionsNotify   = "sessions.notify"
	ScopeHostTicketsRead      = "tickets.read"
	ScopeHostTicketsWrite     = "tickets.write"
	ScopeHostConfigReadOther  = "config.read_other"
	ScopeHostConfigReadSecret = "config.read_secret"
	ScopeHostConnectorsRead   = "connectors.read"
	ScopeHostConnectorsExec   = "connectors.execute"
	ScopeHostRestRead         = "rest.read"
	ScopeHostRestWrite        = "rest.write"
	ScopeHostDBRead           = "db.read"
	ScopeHostDBWrite          = "db.write"
	ScopeHostEventsPublish    = "events.publish"
	ScopeHostDatadir          = "datadir"
	ScopeHostNetListen        = "net.listen"
)

Host API scopes a plugin declares in host_scopes. The names are part of the wire contract (wick.host.v1): add, never rename.

KEEP IN SYNC: adding or changing a scope, method/op, resource kind or admin label here MUST also update docs/plugins/host-api.md and the built-in skills internal/agents/skillsync/builtin/wick-plugin-authoring/SKILL.md and internal/agents/skillsync/builtin/wick-plugins/SKILL.md. A guard test fails when they drift.

View Source
const (
	HostResourceRest       = "rest"
	HostResourceDB         = "db"
	HostResourceConnectors = "connectors"
	HostResourceConfig     = "config"
)

Resource kinds a scope can require a host_resources declaration for.

KEEP IN SYNC: adding or changing a scope, method/op, resource kind or admin label here MUST also update docs/plugins/host-api.md and the built-in skills internal/agents/skillsync/builtin/wick-plugin-authoring/SKILL.md and internal/agents/skillsync/builtin/wick-plugins/SKILL.md. A guard test fails when they drift.

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}"
	// HeaderTokenUser* name who a webhook request authenticated as, when
	// wick could verify its credential; absent otherwise. The credential is
	// a wick PAT (Authorization: Bearer, checked first) or wick's own SSO
	// JWT in X-Wick-User (sent by a custom MCP connector with the sso
	// scheme whose server is this wick); HeaderTokenUserSource says which.
	// For the JWT wick mints for itself (tools/list at boot or reload) the
	// ID is TokenUserSystemID, the role "system" and there is no email; the
	// plugin's Host API calls for that request run without a user (plugin
	// identity / wick_pat), never as "system:wick".
	HeaderTokenUserID    = "X-Wick-Token-User-Id"
	HeaderTokenUserEmail = "X-Wick-Token-User-Email"
	HeaderTokenUserName  = "X-Wick-Token-User-Name"
	HeaderTokenUserRole  = "X-Wick-Token-User-Role" // "admin", "user" or "system"
	HeaderTokenUserTags  = "X-Wick-Token-User-Tags"
	// HeaderTokenUserSource is set with every HeaderTokenUser* injection:
	// TokenUserSourcePAT, TokenUserSourceSSO or TokenUserSourceSystem.
	// Plugins use it when PAT and SSO callers get different rights.
	HeaderTokenUserSource = "X-Wick-Token-User-Source"
	// 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 (
	TokenUserSourcePAT    = "pat"
	TokenUserSourceSSO    = "sso"
	TokenUserSourceSystem = "system"
	// TokenUserSystemID is HeaderTokenUserID for wick's own SSO identity.
	TokenUserSystemID = "system:wick"
)

HeaderTokenUserSource values (same strings as tool.TokenSource*).

View Source
const CodeNoHealthCheck = "no_health_check"

CodeNoHealthCheck is the Error code a plugin answers a health_check request with when its module registers no HealthCheck hook.

View Source
const DefaultAutoOffIdleSeconds = 15 * 60

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

View Source
const EnvDataDir = "WICK_PLUGIN_DATA_DIR"

EnvDataDir is the env var the host sets to the plugin's persistent data directory (the same <appDataDir>/plugins/<key> the install layout implies).

View Source
const EnvHostBroker = "WICK_HOST_API_BROKER"

EnvHostBroker is set ("1") on a process wick serves the Host API to over the broker; the SDK only dials when it is present, so a plugin under an older wick never waits on a dial that cannot succeed.

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 HostBrokerID uint32 = 0x77696b01

HostBrokerID is the GRPCBroker service id wick serves the Host API on. It is fixed rather than announced, so neither the handshake nor the plugin protos change: the SDK dials it right away, and on a wick that never serves it the dial times out and the SDK falls back to the HTTP door (or ErrHostAPIUnavailable).

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 HostMethods = []HostMethod{
	{Name: "Whoami", Scope: ScopeHostWhoami, Summary: "Who this plugin is and which scopes it holds."},
	{Name: "ListMethods", Scope: ScopeHostWhoami, Summary: "The Host API methods and their scopes."},
	{Name: "ListUsers", Scope: ScopeHostUsersRead, Summary: "List wick users."},
	{Name: "GetUser", Scope: ScopeHostUsersRead, Summary: "Get a user by id."},
	{Name: "GetUserByEmail", Scope: ScopeHostUsersRead, Summary: "Get a user by email."},
	{Name: "ConnectedAccounts", Scope: ScopeHostAccountsRead, Summary: "Accounts linked to a connector instance."},
	{Name: "ListSessions", Scope: ScopeHostSessionsRead, Summary: "List session metadata.", UserLevel: true},
	{Name: "GetSessionMeta", Scope: ScopeHostSessionsRead, Summary: "Get one session's metadata.", UserLevel: true},
	{Name: "SendToSession", Scope: ScopeHostSessionsNotify, Summary: "Send a message into a session.", Destructive: true, UserLevel: true},
	{Name: "GetTicket", Scope: ScopeHostTicketsRead, Summary: "Get a ticket.", UserLevel: true},
	{Name: "ListTickets", Scope: ScopeHostTicketsRead, Summary: "List a project's tickets.", UserLevel: true},
	{Name: "CreateTicket", Scope: ScopeHostTicketsWrite, Summary: "Create a ticket.", Destructive: true, UserLevel: true},
	{Name: "UpdateTicket", Scope: ScopeHostTicketsWrite, Summary: "Update a ticket.", Destructive: true, UserLevel: true},
	{Name: "AttachSession", Scope: ScopeHostTicketsWrite, Summary: "Attach a session to a ticket.", Destructive: true, UserLevel: true},
	{Name: "GetConfig", Scope: ScopeHostConfigReadOther, Summary: "Read a config value (another owner's needs config.read_other; its secrets config.read_secret)."},
	{Name: "ListConnectorInstances", Scope: ScopeHostConnectorsRead, Summary: "List connector instances.", UserLevel: true},
	{Name: "ExecuteConnector", Scope: ScopeHostConnectorsExec, Summary: "Run a declared connector operation.", UserLevel: true},
	{Name: "Invoke", Scope: "", Summary: "Call a method by name; uses that method's scope."},
	{Name: "Rest", Scope: ScopeHostRestRead, Summary: "Call wick's REST API (non-GET needs rest.write).", Destructive: true, UserLevel: true},
	{Name: "Query", Scope: ScopeHostDBRead, Summary: "Run SQL (write=true needs db.write).", Destructive: true, UserLevel: true},
}

HostMethods lists every Host RPC in contract order. Rest and Query pick their scope per call (rest.read/rest.write, db.read/db.write); the entry names the read scope and the write half is destructive.

KEEP IN SYNC: adding or changing a scope, method/op, resource kind or admin label here MUST also update docs/plugins/host-api.md and the built-in skills internal/agents/skillsync/builtin/wick-plugin-authoring/SKILL.md and internal/agents/skillsync/builtin/wick-plugins/SKILL.md. A guard test fails when they drift.

View Source
var HostScopes = []HostScope{
	{Name: ScopeHostWhoami, Label: "Identify itself", Description: "Ask wick which plugin it is and what it may call.", DefaultAllow: true},
	{Name: ScopeHostUsersRead, Label: "Read users", Description: "List wick users and look one up by id or email (name, email, approval, admin flag, tags).", DefaultAllow: true},
	{Name: ScopeHostAccountsRead, Label: "Read connected accounts", Description: "List the accounts linked to a connector instance.", DefaultAllow: true},
	{Name: ScopeHostSessionsRead, Label: "Read session details", Description: "List sessions and read their metadata (never the conversation itself), as the acting user.", DefaultAllow: true},
	{Name: ScopeHostSessionsNotify, Label: "Message sessions", Description: "Send a message into a session, as the acting user.", DefaultAllow: true, Destructive: true},
	{Name: ScopeHostTicketsRead, Label: "Read tickets", Description: "List and read tickets, as the acting user.", DefaultAllow: true},
	{Name: ScopeHostTicketsWrite, Label: "Change tickets", Description: "Create and update tickets and attach sessions to them, as the acting user.", DefaultAllow: true, Destructive: true},
	{Name: ScopeHostConfigReadOther, Label: "Read other configs", Description: "Read configuration values owned by something other than this plugin (secret values stay hidden).", DefaultAllow: true},
	{Name: ScopeHostConfigReadSecret, Label: "Read other secrets", Description: "Read the declared secret config values of other owners (needs config.read_other too).", Sensitive: true, Resource: HostResourceConfig},
	{Name: ScopeHostConnectorsRead, Label: "List connector instances", Description: "List the connector instances the acting user can see.", DefaultAllow: true},
	{Name: ScopeHostConnectorsExec, Label: "Run connector operations", Description: "Run the declared connector operations as the acting user.", DefaultAllow: true, Resource: HostResourceConnectors},
	{Name: ScopeHostRestRead, Label: "Read wick API", Description: "Call the declared GET paths of wick's REST API as the acting user.", DefaultAllow: true, Resource: HostResourceRest},
	{Name: ScopeHostRestWrite, Label: "Change via wick API", Description: "Call the declared POST/PUT/PATCH/DELETE paths of wick's REST API as the acting user.", Destructive: true, Resource: HostResourceRest},
	{Name: ScopeHostDBRead, Label: "Read wick database", Description: "Run read-only SQL against the declared tables.", Resource: HostResourceDB},
	{Name: ScopeHostDBWrite, Label: "Write wick database", Description: "Run SQL that changes the declared tables.", Destructive: true, Resource: HostResourceDB},
	{Name: ScopeHostEventsPublish, Label: "Wake watches", Description: "Publish an event under its own key; watches subscribed to it with wake_on run right away, as their owners.", DefaultAllow: true},
	{Name: ScopeHostDatadir, Label: "Keep a data folder", Description: "Store files in its own persistent data folder.", DefaultAllow: true, Declarative: true},
	{Name: ScopeHostNetListen, Label: "Open a local port", Description: "Listen on a local network port.", DefaultAllow: true, Declarative: true},
}

HostScopes is the one table of official scopes, in admin display order.

KEEP IN SYNC: adding or changing a scope, method/op, resource kind or admin label here MUST also update docs/plugins/host-api.md and the built-in skills internal/agents/skillsync/builtin/wick-plugin-authoring/SKILL.md and internal/agents/skillsync/builtin/wick-plugins/SKILL.md. A guard test fails when they drift.

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 BeginHostCall added in v1.16.0

func BeginHostCall(key, kind, userID, source, sessionID string) (string, func())

BeginHostCall records who one HTTP request about to be proxied to plugin key runs for (source: "caller" for a session, "token" for the owner of an access token) and returns the call id to send as host.HeaderCallID; end forgets it when the request is over. No bridge or no person = ("", no-op).

func ConfigItem added in v1.16.0

func ConfigItem(owner, key string) string

ConfigItem is the host_resources.config item key of owner's key.

func ConnectorItem added in v1.16.0

func ConnectorItem(connector, op string) string

ConnectorItem is the host_resources.connectors item key of connector's op.

func DBItem added in v1.16.0

func DBItem(table, mode string) string

DBItem is the host_resources.db item key of table under mode.

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).

When the host sets EnvDataDir (wick does for every connector it spawns, the pool and a development-mode candidate alike), that value is used as-is: it is already the full directory for this key. This is what lets a candidate binary run from a build folder find the assets the installed plugin already downloaded.

Otherwise it is resolved plugin-side from the running binary's own location. 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 DeclareHostAccess added in v1.16.0

func DeclareHostAccess(scopes []string, resources *HostResources)

DeclareHostAccess records the Host API scopes (and, for rest.*, db.*, connectors.execute and config.read_secret, the host_resources) this plugin binary uses. Call it in main before Serve / ServeJob / ServeTool / service.ServeService: the self-built manifest (--dump-manifest, so `wick plugin build`) then carries them as host_scopes and host_resources, and an invalid declaration fails the dump instead of the install. A later call replaces an earlier one. See docs/plugins/host-api.md.

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. A module connector.ValidateModule rejects never makes it into a manifest.

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 Host added in v1.16.0

func Host(ctx context.Context) (host.Host, error)

Host returns wick's Host API for this plugin process: the broker connection for connector/tool/job plugins, else the HTTP door from the env. It probes Whoami once; a wick without a Host API (no transport, or the callback door's version 0) yields host.ErrHostAPIUnavailable, and the plugin should degrade.

func HostProcessEnv added in v1.16.0

func HostProcessEnv(key, kind string) ([]string, func())

HostProcessEnv returns the Host API env for a new process of key (nil when wick runs no Host API) and the release that revokes its token once the process is gone (never nil).

func JobVersionedPluginsFor added in v1.16.0

func JobVersionedPluginsFor(key string) map[int]goplugin.PluginSet

JobVersionedPluginsFor is JobVersionedPlugins for the plugin key: the host also serves the Host API to the process over the broker.

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 MatchRestPattern added in v1.16.0

func MatchRestPattern(pattern, path string) bool

MatchRestPattern reports whether a wick REST path (no query string) matches a declared pattern: "*" matches exactly one non-empty segment, a final "**" one or more remaining segments; every other segment must be equal byte for byte (no unescaping, no normalisation).

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 RestItem added in v1.16.0

func RestItem(method, pattern string) string

RestItem is the host_resources.rest item key of a declared pattern.

func RestPathReserved added in v1.16.0

func RestPathReserved(p string) bool

RestPathReserved reports a wick REST path no plugin may reach through the Host API whatever it declares and whoever it acts for: plugin management (/manager/api/plugins..., plugin-sources, plugin-audit, service-plugins and the host access pages under them). A plugin must not install, replace or re-permission plugins, itself included.

func RunOpMain added in v1.16.0

func RunOpMain(mod connector.Module, args []string, stdout, stderr io.Writer) int

RunOpMain runs run-op mode and returns the process exit code.

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 SetHostBridge added in v1.16.0

func SetHostBridge(b HostBridge)

SetHostBridge installs wick's Host API bridge (nil removes it).

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 ToolVersionedPluginsFor added in v1.16.0

func ToolVersionedPluginsFor(key, kind string) map[int]goplugin.PluginSet

ToolVersionedPluginsFor is ToolVersionedPlugins for one plugin of kind (tool or service): the host also serves it the Host API over the broker.

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 -> host access -> 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).

func VersionedPluginsFor added in v1.16.0

func VersionedPluginsFor(key string) map[int]goplugin.PluginSet

VersionedPluginsFor is VersionedPlugins for the plugin key: the host also serves the Host API to the process over the broker.

Types

type ConnectorGRPCPlugin

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

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.

HostKey (host side) is the plugin key the Host API is served for over the connection's broker; "" serves none.

func (*ConnectorGRPCPlugin) GRPCClient

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

func (*ConnectorGRPCPlugin) GRPCServer

func (p *ConnectorGRPCPlugin) GRPCServer(broker *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
	// InstanceID / CallerUserID mirror the host Ctx so the plugin-side Ctx
	// answers c.InstanceID() and c.CallerUserID() the same way.
	InstanceID   string
	CallerUserID string
	// AccountID / OwnerBotID mirror c.AccountID() and c.OwnerBotID().
	AccountID  string
	OwnerBotID string
	// RawInput mirrors c.RawInput() (the untyped arguments); nil = none.
	RawInput map[string]any
	// HealthCheck runs the module's HealthCheck hook instead of Operation;
	// the result JSON is the []connector.OpHealth report.
	HealthCheck bool
	// Progress receives the op's c.ReportProgress calls. Only ExecuteStream
	// delivers them; the unary Execute has no channel back and drops them.
	Progress func(progress, total int, message 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. On an operation error (ErrPluginOp) the mask lists are still filled, so the host can scrub the error message as well.

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 HostBridge added in v1.16.0

type HostBridge interface {
	// GRPCServer builds the Host API server the broker serves to one process
	// of pluginKey.
	GRPCServer(pluginKey, kind string) func([]grpc.ServerOption) *grpc.Server
	// BeginCall records who one request to pluginKey runs for and returns
	// the call id the plugin echoes back on its Host API calls; end forgets
	// it once the request is over.
	BeginCall(pluginKey, kind, userID, sessionID string) (callID string, end func())
	// ProcessEnv is the Host API env of a new process of pluginKey: the
	// private HTTP door address and a fresh plugin token. release revokes
	// that token; call it once the process is gone.
	ProcessEnv(pluginKey, kind string) (env []string, release func())
}

HostBridge is wick's side of the Host API for go-plugin processes. wick sets one at start (SetHostBridge); with none, plugins run without a Host API exactly as before.

type HostConfigResource added in v1.16.0

type HostConfigResource struct {
	Owner string `json:"owner"`
	Key   string `json:"key"`
}

HostConfigResource is one config value of another owner whose secret the plugin may read under config.read_secret.

type HostConnectorResource added in v1.16.0

type HostConnectorResource struct {
	Connector string   `json:"connector"`
	Ops       []string `json:"ops"`
}

HostConnectorResource is one connector module key and the ops it may run.

type HostDBResource added in v1.16.0

type HostDBResource struct {
	Table string `json:"table"`
	Mode  string `json:"mode"`
}

HostDBResource is one table and the access mode ("read" or "write").

type HostMethod added in v1.16.0

type HostMethod struct {
	Name        string
	Scope       string
	Summary     string
	Destructive bool
	// UserLevel RPCs touch data owned by a person and always run as one
	// (the caller, else the plugin's wick_pat); plugin-level ones need none.
	UserLevel bool
}

HostMethod is one Host RPC as ListMethods reports it.

func LookupHostMethod added in v1.16.0

func LookupHostMethod(name string) (HostMethod, bool)

LookupHostMethod returns the Host RPC named name.

type HostResources added in v1.16.0

type HostResources struct {
	Rest       []HostRestResource      `json:"rest,omitempty"`
	DB         []HostDBResource        `json:"db,omitempty"`
	Connectors []HostConnectorResource `json:"connectors,omitempty"`
	Config     []HostConfigResource    `json:"config,omitempty"`
}

HostResources is what a plugin names in detail for the scopes that need it (rest.*, db.*, connectors.execute, config.read_secret): no declaration, no access.

KEEP IN SYNC: adding or changing a scope, method/op, resource kind or admin label here MUST also update docs/plugins/host-api.md and the built-in skills internal/agents/skillsync/builtin/wick-plugin-authoring/SKILL.md and internal/agents/skillsync/builtin/wick-plugins/SKILL.md. A guard test fails when they drift.

func (*HostResources) Empty added in v1.16.0

func (r *HostResources) Empty() bool

Empty reports whether nothing is declared.

func (*HostResources) Items added in v1.16.0

func (r *HostResources) Items(kind string) []string

Admin overlay items: the one place their shape is defined. A call is allowed only when its item is in Items(kind) (no declaration, no access) and no overlay row (scope, item, allowed=false) blocks it. Shapes:

  • rest: "<METHOD> <declared pattern>", e.g. "POST /api/tickets" or "GET /api/tickets/*". The pattern as declared, not the concrete path: the first declared pattern matching a call is its item, so blocking one pattern blocks every path it matches.
  • db: "<table>:<mode>", e.g. "tickets:read", "tickets:write". A "write" declaration yields both items (write implies read), so an admin can keep reads and block writes of one table.
  • connectors: "<connector>.<op>", e.g. "slack.send_message".
  • config: "<owner>/<key>", e.g. "notion-ticket-sync/token".

Items lists the declared items of resource kind in those shapes.

type HostRestResource added in v1.16.0

type HostRestResource struct {
	Method string `json:"method"`
	Path   string `json:"path"`
}

HostRestResource is one wick REST pattern: "*" matches one path segment, a final "**" the rest of the path (MatchRestPattern). HEAD counts as a read like GET.

type HostScope added in v1.16.0

type HostScope struct {
	Name string
	// Label and Description are the admin card text ("what this plugin can
	// do"); every scope must have both (TestHostScopesHaveAdminLabel).
	Label       string
	Description string
	// DefaultAllow is the decision when no admin overlay row exists.
	DefaultAllow bool
	// Destructive marks scopes whose calls change data or reach people.
	Destructive bool
	// Sensitive scopes read data an admin should look at twice (secrets);
	// the admin page highlights them even when they are not destructive.
	Sensitive bool
	// Declarative scopes have no RPC; they only describe the plugin.
	Declarative bool
	// Resource names the host_resources block every call must match ("" =
	// none). A plugin without that declaration gets no access at all.
	Resource string
}

HostScope describes one Host API scope: what the admin page shows for it and how wick decides a call under it.

func LookupHostScope added in v1.16.0

func LookupHostScope(name string) (HostScope, bool)

LookupHostScope returns the official scope named name.

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
	HostKey string
}

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

HostKey (host side) is the plugin key the Host API is served for over the broker; "" serves none. A job run has no person behind it, so its Host API calls carry no call id and user-level ones run as the plugin's wick_pat.

func (*JobGRPCPlugin) GRPCClient added in v1.2.9

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

func (*JobGRPCPlugin) GRPCServer added in v1.2.9

func (p *JobGRPCPlugin) GRPCServer(broker *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"`
	// HostScopes are the Host API scopes the plugin uses (see HostScopes);
	// HostResources names what rest.*, db.* and connectors.execute reach.
	// Both are optional: a plugin built before the Host API has neither.
	HostScopes    []string       `json:"host_scopes,omitempty"`
	HostResources *HostResources `json:"host_resources,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) UnknownHostScopes added in v1.16.0

func (m Manifest) UnknownHostScopes() []string

UnknownHostScopes lists host_scopes this wick does not know. They do not fail the manifest (a plugin built for a newer wick must still load, §8): the loader logs them and every call under them is denied.

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.

func (Manifest) ValidateHostAccess added in v1.16.0

func (m Manifest) ValidateHostAccess() error

ValidateHostAccess checks host_scopes and host_resources: every scope is listed once, every rest/db/connectors/config scope comes with a matching declaration, and every declaration is well formed (REST paths only under /api/ or /manager/api/, no dot segments). Unknown scopes are not an error (see UnknownHostScopes).

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
	HostKey  string
	HostKind string
}

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

HostKey/HostKind (host side) name the plugin the Host API is served for over the broker; HostKey "" serves none. Service plugins share this descriptor, hence the kind.

func (*ToolGRPCPlugin) GRPCClient added in v1.2.9

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

func (*ToolGRPCPlugin) GRPCServer added in v1.2.9

func (p *ToolGRPCPlugin) GRPCServer(broker *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 host is the plugin-side client of wick's Host API (wick.host.v1): the calls a plugin makes back into wick (users, sessions, tickets, connector instances, ...).
Package host is the plugin-side client of wick's Host API (wick.host.v1): the calls a plugin makes back into wick (users, sessions, tickets, connector instances, ...).
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