From 0d16fec22930ff8d1660df7ca97f6f0213fccf7d Mon Sep 17 00:00:00 2001 From: Joaquin Terrasa Date: Tue, 30 Jun 2026 14:21:23 +0200 Subject: [PATCH 1/2] docs: typo fixes, tools[] clarification, add setup field to manifest --- docs/guide/capability-matrix.md | 2 +- docs/guide/hooks.md | 4 ++-- docs/guide/introduction.md | 2 +- docs/guide/manifest.md | 20 +++++++++++++++++++- docs/reference/adapters.md | 4 ++-- 5 files changed, 25 insertions(+), 7 deletions(-) diff --git a/docs/guide/capability-matrix.md b/docs/guide/capability-matrix.md index 38203dd..56dabb3 100644 --- a/docs/guide/capability-matrix.md +++ b/docs/guide/capability-matrix.md @@ -42,7 +42,7 @@ Legend: | `skills` | ✅ | ✅ | ✅ | — | Universal. | | `hooks` (lifecycle) | ⚠️ | ⚠️ | ❌ | Copilot/Gemini: use HTTP or `command` handlers (see [Hooks](/guide/hooks)). | Kimi supports a subset (see below). | | `subagentStart` / `subagentStop` | ❌ | ❌ | ❌ | TUI fidelity only — implement per-harness via native plugin config if you really need it. | No universal primitive planned. | -| `tools[]` | ✅ | ✅ | ❌ | — | First-class tool emission. | +| `tools[]` | ⚠️ | ⚠️ | ❌ | Use `mcpServers` instead (not emitted on these Tier-2 harnesses). | No first-class tool emission; emit WARN. | | `mcpServers` | ❌ | ❌ | ❌ | Wire the MCP server directly into the harness's native config — no agentplugins path needed. | Not on the manifest path; harness-level wiring only. | Kimi supported hooks: `preToolUse`, `userPromptSubmit`, `sessionStart`, `notification`, `permissionRequest`. Inline handlers auto-wrapped as Node.js command scripts (v0.5.0). diff --git a/docs/guide/hooks.md b/docs/guide/hooks.md index 2e43349..d7afb27 100644 --- a/docs/guide/hooks.md +++ b/docs/guide/hooks.md @@ -228,7 +228,7 @@ interface HookContext { toolInput?: unknown // for tool hooks prompt?: string // for prompt hooks agentName?: string // for subagent hooks - error?: string // for onError + error?: string // for postToolUseFailure, stopFailure } ``` @@ -240,7 +240,7 @@ Returning an object lets you influence the agent's behavior: interface HookResult { block?: boolean // stop the action reason?: string // explanation (shown to the agent) - additionalContext?: string// inject context into the turn + additionalContext?: string // inject context into the turn modifiedInput?: unknown // rewrite the tool input } ``` diff --git a/docs/guide/introduction.md b/docs/guide/introduction.md index dcc9c49..2a331d5 100644 --- a/docs/guide/introduction.md +++ b/docs/guide/introduction.md @@ -22,7 +22,7 @@ Every AI agent framework ships its own plugin system with its own manifest forma | Pi Mono | TypeScript extensions | inline only | -**Seven frameworks, seven different APIs.** A plugin author who wants reach across the ecosystem maintains seven forks of the same logic. Users who switch harnesses lose every plugin they configured. +**Seven frameworks, seven different APIs.** A plugin author who wants to reach across the ecosystem maintains seven forks of the same logic. Users who switch harnesses lose every plugin they configured. ## The solution diff --git a/docs/guide/manifest.md b/docs/guide/manifest.md index c3a32f3..74da28f 100644 --- a/docs/guide/manifest.md +++ b/docs/guide/manifest.md @@ -55,7 +55,8 @@ The `hooks` object maps universal lifecycle event names to handlers. There are * | Category | Hooks | |---|---| -| Session | `sessionStart`, `sessionEnd`, `setup` | +| Session | `sessionStart`, `sessionEnd` | +| Setup | `setup` | | Prompt | `userPromptSubmit`, `userPromptExpansion` | | Tool | `preToolUse`, `postToolUse`, `postToolUseFailure` | | Permission | `permissionRequest`, `permissionDenied` | @@ -215,6 +216,23 @@ sidecar: { | `health` | `string` | Health check URL. | | `restart` | `'always' \| 'on-failure' \| 'no'` | Restart policy. | +## Install setup + +The optional top-level `setup` field declares a one-shot install command. After `agentplugins add`, the CLI prompts for trust and runs it once. It is distinct from the `hooks.setup` lifecycle hook. + +```typescript +setup: { + command: './scripts/install.sh', +} +``` + +| Field | Type | Required | Notes | +|---|---|---|---| +| `command` | `string` | yes | Shell command to run after install. | +| `args` | `string[]` | no | Arguments passed to the command. | + +If `setup` is omitted, the CLI auto-detects `install.sh` → `setup.sh` → `postinstall.mjs` → `postinstall.js` (first hit). See [Linting](/guide/linting) and [Porting](/guide/porting#security--setup-on-install) for details. + ## Rules The `rules` array declares behavioral rules — allow/deny/warn patterns applied to tool calls. diff --git a/docs/reference/adapters.md b/docs/reference/adapters.md index bd93aa9..431a45b 100644 --- a/docs/reference/adapters.md +++ b/docs/reference/adapters.md @@ -12,9 +12,9 @@ An adapter compiles the universal manifest into one target platform's native for | `gemini` | JSON manifest | command | subset | ⚠️ | ❌ | | `kimi` | JSON manifest | command | subset | ⚠️ | ❌ | | `opencode` | TypeScript plugin + `opencode.json` | inline (reference) | subset | ✅ | ✅ | -| `pimono` | TypeScript extension + `package.json` | inline (reference) | subset | ✅ | ✅ | +| `pimono` | TypeScript extension + `package.json` | inline (reference) | subset | ✅ | ⚠️ | -⚠️ = WARN emitted; `tools[]` is not natively emitted — use `mcpServers` for Claude/Codex (Tier-1 universal tool path). +⚠️ = WARN emitted; `tools[]` is not natively emitted — use `mcpServers` for Claude/Codex (Tier-1 universal tool path). Pi Mono has no built-in MCP; `tools[]` is the native tool path. Two families: **JSON-emitting** adapters (claude, codex, copilot, gemini, kimi) produce static manifest files the host reads at startup. **Code-emitting** adapters (opencode, pimono) produce real TypeScript modules the host imports and calls. From 483ba091f595568bd8dc1373e5a712b3c3fff0cc Mon Sep 17 00:00:00 2001 From: Joaquin Terrasa Date: Tue, 30 Jun 2026 14:43:58 +0200 Subject: [PATCH 2/2] =?UTF-8?q?fix(ci):=20scope=20typecheck=20to=20package?= =?UTF-8?q?s/**=20=E2=80=94=20docs=20and=20example-profiler=20lack=20tsc?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index cf502c9..e7fdac0 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -40,7 +40,7 @@ jobs: run: pnpm --filter './packages/**' build - name: Typecheck - run: pnpm -r exec tsc --noEmit + run: pnpm --filter './packages/**' exec tsc --noEmit - name: Test run: pnpm test