Section 00 / Docs 000

Plugin Interface Reference

Complete reference for the kaged plugin system — manifest, capabilities, and JSON-RPC protocol.

Plugins are external processes that communicate with the daemon over stdin/stdout JSON-RPC 2.0.

Every plugin ships a manifest.yaml declaring its name, methods, capabilities, and lifecycle parameters.

The daemon spawns the plugin, performs a handshake (initialize → initialized), then routes method calls. Health checks run periodically. On shutdown, the daemon sends a shutdown request and waits up to shutdown_timeout_sec.

Section / Plugin Manifest plugin-manifest

Plugin Manifest

The manifest.yaml file that every kaged plugin must provide.

Field	Type	Required	Default	Description
`name`	`string (pattern)`	yes	—	Plugin name — lowercase slug (a-z, 0-9, hyphens; max 64 chars). [min length: 1, max length: 64, pattern: `^[a-z][a-z0-9-]*$`]
`version`	`string`	yes	—	Semver version string. [min length: 1]
`kaged_api`	`integer`	yes	—	Required kaged plugin API version (positive integer). [gt: 0]
`description`	`string`	yes	—	Short description (1-200 chars). [min length: 1, max length: 200]
`author`	`string`	no	—	Plugin author.
`license`	`string`	no	—	SPDX license identifier.
`homepage`	`url`	no	—	Plugin homepage URL.
`command`	`string[]`	yes	—	Command to spawn the plugin process (array of strings, min 1). [min entries: 1]
`env`	`Record<string, string>`	no	`{}`	Environment variables to set when spawning (default: {}).
`capabilities`	`string[]`	no	`[]`	Declared capabilities — see §capabilities (default: []).
`methods`	`string (pattern)[]`	no	`[]`	JSON-RPC method names this plugin exposes (default: []). Must be dot-delimited, 2-4 segments, lowercase. May be empty if `hooks` or `tools` is non-empty.
`notifications`	`string[]`	no	`[]`	Notification names this plugin can emit (default: []).
`config_schema`	`Record<string, unknown>`	no	—	JSON Schema for plugin-specific project-side configuration (committed to project repo). Carries everything except secrets.
`system_config_schema`	`Record<string, unknown>`	no	—	JSON Schema for operator-local secrets (never committed). Field names must be disjoint from config_schema. ADR-0023.
`hooks`	`"on_session_start" \| "on_session_idle" \| "pre_compact" \| "post_compact"[]`	no	`[]`	Lifecycle hook subscriptions (default: []). Allowed: on_session_start, on_session_idle (primary-only), pre_compact, post_compact (per-agent). ADR-0023.
`tools`	`object[]`	no	`[]`	Plugin-registered tools (default: []). Each entry declares `name` (single-segment, lowercase; auto-prefixed with plugin name at registration), `description`, and `parameters_schema` (JSON Schema). ADR-0023.
`roles`	`"observer" \| "compactor"[]`	no	—	Plugin roles for the compaction pipeline. Allowed: observer, compactor. Default: [observer] when `hooks` is non-empty, else []. `compactor` requires `pre_compact` in hooks. At most one compactor per agent. ADR-0024.
`knobs`	`Record<string, object>`	no	`{}`	Operator-tunable configuration declarations (default: {}). Rendered as UI controls automatically. Each knob has `type` (range / int_range / enum / boolean / text / multiline / model_alias / path), `label`, optional `description`, and `binds_to` (must reference a field in config_schema; binding to system_config is forbidden). ADR-0024.
`shutdown_timeout_sec`	`integer`	no	`5`	Seconds to wait for graceful shutdown (1-30, default: 5). [min: 1, max: 30]
`health_interval_sec`	`integer`	no	`30`	Seconds between health checks (5-300, default: 30). [min: 5, max: 300]
`hook_timeout_sec`	`integer`	no	`10`	Seconds the daemon waits for a hook response before treating it as a timeout (1-60, default: 10). ADR-0023. [min: 1, max: 60]

Section / Capabilities capabilities

Capabilities

Capability strings declare what resources a plugin needs. Declared in manifest.yaml, validated at load time.

Field	Type	Required	Default	Description
`read:fs:<path>`	`string`	yes	—	Read access to an absolute filesystem path.
`write:fs:<path>`	`string`	yes	—	Write access to an absolute filesystem path.
`exec:<binary>:<path>`	`string`	yes	—	Execute a binary at the given path.
`net:<host>:<port>`	`string`	yes	—	Network access to a specific host:port.
`net:<host>:*`	`string`	yes	—	Network access to all ports on a host.
`net:*`	`string`	yes	—	Unrestricted network access.
`net:[]`	`string`	yes	—	No network access (explicit deny).
`kaged:storage:read`	`string`	yes	—	Read access to kaged's plugin storage.
`kaged:storage:write`	`string`	yes	—	Write access to kaged's plugin storage.

Section / JSON-RPC Protocol protocol

JSON-RPC Protocol

Plugins communicate with the daemon over stdin/stdout using JSON-RPC 2.0.

Field	Type	Required	Default	Description
`initialize`	`object`	yes	—	Daemon sends initialize request with daemon_version, api_version, plugin_name, storage_available, projects. Plugin responds with name, version, api_version, methods, notifications, capabilities_used.
`initialized`	`object`	yes	—	Daemon sends initialized notification after successful handshake.
`shutdown`	`object`	yes	—	Daemon sends shutdown request. Plugin should clean up and exit within shutdown_timeout_sec.
`health.check`	`object`	yes	—	Daemon pings plugin at health_interval_sec intervals. Plugin must respond within 5 seconds.

Method names must not start with kaged.* or system.* — these prefixes are reserved.

Max message size: 4 MB. Notification rate limit: 100/sec.