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
- Variables
- func ApplyRlimits()
- func DataDir(key string) string
- func DumpManifest(mod connector.Module) ([]byte, error)
- func GRPCServer(opts []grpc.ServerOption) *grpc.Server
- func GenerateKeypair() (privB64, pubB64 string)
- func KindFolder(kind string) string
- func NewJobServer(mod job.Module) pb.JobServer
- func NewServer(mod connector.Module) pb.ConnectorServer
- func NormalizeKind(k string) string
- func ProtoVersionSupported(v int) bool
- func ReadReattachConfig(path string) (*goplugin.ReattachConfig, error)
- func ReattachPluginSet() goplugin.PluginSet
- func RequireSig() bool
- func Serve(mod connector.Module)
- func ServeJob(mod job.Module)
- func SignSHA256(privKeyPath, sha256hex string) (string, error)
- func SupportedProtoVersions() []int
- func TrustedKeys() []string
- func ValidAuth(a string) bool
- func ValidateKey(key string) error
- func VerifyManifest(m Manifest, binaryPath string) error
- func VerifySHA256(trustedPubsB64 []string, sha256hex, sigB64 string) bool
- type ConnectorGRPCPlugin
- type ExecCall
- type ExecResult
- type GRPCConn
- type JobConn
- type JobGRPCPlugin
- type JobModule
- type Manifest
- func BuildSelfJobManifest(mod job.Module, signKeyPath string) (Manifest, error)
- func BuildSelfManifest(mod connector.Module, signKeyPath string) (Manifest, error)
- func BuildSelfServiceManifest(sm ServiceModule, signKeyPath string) (Manifest, error)
- func BuildSelfToolManifest(tm ToolModule, signKeyPath string) (Manifest, error)
- type RemoteEvent
- type RemoteInject
- type RemoteSendResult
- type RemoteSessionFieldsRequest
- type RemoteTurn
- type ServiceAutoOff
- type ServiceModule
- type ServiceRoute
- type SessionField
- type ToolConn
- type ToolGRPCPlugin
- type ToolMeta
- type ToolModule
- type ToolWebhook
Constants ¶
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.
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.
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.
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.
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.
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.
const DefaultAutoOffIdleSeconds = 15 * 60
DefaultAutoOffIdleSeconds is the idle limit of an auto-off service whose plugin sets none.
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.
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.
const JobPluginName = "job"
JobPluginName is the dispense key for job plugins.
const ManifestSchemaVersion = 1
ManifestSchemaVersion is the current envelope format version.
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.
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.
const PluginName = "connector"
PluginName is the dispense key both sides agree on.
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.
const RemoteEventSchema = 1
RemoteEventSchema is the event schema version RemoteEvent follows.
const ToolPluginName = "tool"
ToolPluginName is the dispense key for tool plugins.
Variables ¶
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.
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.
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.
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.
var Kinds = []string{KindConnector, KindTool, KindJob, KindService}
Kinds lists every plugin kind in display order.
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.
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.
var TrustedPubKey string
TrustedPubKey is the publisher's base64 ed25519 public key baked into a released wick binary via -ldflags. Empty in dev builds.
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".
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
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 ¶
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
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
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 ¶
NormalizeKind returns a valid kind, defaulting empty/unknown to connector.
func ProtoVersionSupported ¶
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
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 ¶
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
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 ¶
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 ValidateKey ¶
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 ¶
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 ¶
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 (p *ConnectorGRPCPlugin) GRPCClient(_ context.Context, _ *goplugin.GRPCBroker, c *grpc.ClientConn) (any, error)
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
// InstanceID / CallerUserID mirror the host Ctx so the plugin-side Ctx
// answers c.InstanceID() and c.CallerUserID() the same way.
InstanceID string
CallerUserID 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
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
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 ¶
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
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
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
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
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 (p *ToolGRPCPlugin) GRPCClient(_ context.Context, _ *goplugin.GRPCBroker, c *grpc.ClientConn) (any, error)
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.
Source Files
¶
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. |