Plugins

🌐 Language: English | 中文

Plugin Engines (SDK v3)

Since SDK v3, any external CLI agent can be registered as a KinetAios engine — zero JS code, one declarative engine field in plugin.json. The plugin's CLI gets its own entry in the engine dropdown as plugin:<name>, streaming tokens, tool events, session resume and cost tracking — everything the built-in CLI engines (Claude Code / Codex) get.

This page is for users of plugin engines. For writing plugins in general (tools / slash commands / panels), see the dev SOP at KinetAiosPlugin.md in the repo root.

Quick start

1. Drop a plugin folder into <userData>/plugins/<name>/ (Settings → Plugins shows the exact path).
2. The plugin's plugin.json declares an engine block (see below).
3. Enable "CLI engines" in Settings → Behavior (plugin engines share the same toggle).
4. Pick the engine from the session header dropdown — it appears as plugin:<name> with its label.

The engine list hot-rebuilds after install / uninstall / enable / disable — no app restart. Conversations already running on an engine keep their old reference until they finish.

The engine spec

{
  "name": "my-agent",
  "version": "1.0.0",
  "engine": {
    "bin": "my-agent",                    // CLI name, resolved from PATH + common install dirs
    "protocol": "plain",                  // ndjson | jsonl-claude | jsonl-codex | plain (default)
    "args": ["--no-color"],               // argv prefix, before the prompt
    "cwdFlags": ["-C", "{cwd}"],          // {cwd} placeholder = session working dir
    "inject": "prompt",                   // prompt (default) | system
    "resume": { "idField": "session_id", "resumeFlag": "--resume", "mode": "flag" },
    "label": "My Agent"                   // display name in dropdown / NEXUS
  }
}

Protocol presets

protocol	wire format	for
ndjson	one JSON object per line: {"type":"token","text":..}, {"type":"tool",...}, {"type":"cost",...}, {"type":"done"}, {"type":"error","message":..}	CLIs you write yourself
jsonl-claude	claude -p --output-format stream-json compatible	claude-protocol agents
jsonl-codex	codex exec --json compatible	codex-protocol agents
plain	entire stdout is the answer text	ordinary CLIs (git, ripgrep wrappers, …)

Session resume

• resume.idField names the event field carrying the session id (sessionStarted events). When the engine emits it, KinetAios stores the id in conv.engineSessionId and appends the resume args on the next turn.
• mode: "flag" (default) → --resume <id>; mode: "subcommand" → resumeFlag is split on spaces and prepended, e.g. "session resume" → my-agent session resume <id> <prompt> (codex-style).

Context injection

• inject: "prompt" (default, codex-style): persona + project rules + memory are joined with --- separators and prepended to the prompt.
• inject: "system": the block goes through systemFlag (default --append-system-prompt) as a separate argv pair — claude-style.

Behavior notes

• Windows .cmd shims are routed through shell: true (same as claude/codex); real .exe/unix bins spawn directly. Abort kills the whole process tree (taskkill /T /F).
• plain protocol: stderr is split off the answer stream; if the CLI exits non-zero, the last 8 stderr lines are appended to the error message. Exit code 0 with no terminal event = done.
• Invalid specs (bad protocol value, missing bin, broken resume) — the engine is not registered; the plugin card in Settings shows a red badge with the exact reason (hover for details).
• Name collisions: two plugins contributing the same engine name — the later one wins (same semantics as tool flattening).
• A plugin that contributes an engine ignores the manifest engines field (the engine is the entry point).

Built-in example

plugins/examples/git-agent/ in the repo wraps plain git as an engine (plain protocol, -C {cwd} working dir). It's the reference for the whole chain: manifest → engine registry → dropdown → plain-protocol token stream.

Related

• Engines — the built-in engines and the shared CliEngineAdapter skeleton
• KinetAiosPlugin.md — full plugin dev SOP (categories, tools, slash commands, panels)