@expert-council/pi-package 0.4.0 → 0.5.1

package/README.md

@@ -4,8 +4,6 @@
 
 Expert Council is a local, multi-model, cost-aware expert orchestration system for Pi and MCP hosts such as Codex. It discovers the models connected through Pi's registered LLM APIs and coding plans, combines runtime metadata with user-defined billing policy, capability profiles, and local reliability data, dynamically assembles a small semantic expert team, executes bounded tasks through Pi, and returns compact structured results to the Main Agent.
 
-> ⚠️ **Codex plugin not yet released**: the Codex plugin has not completed functional testing. Its installation and usage documentation is temporarily withheld from this version and is expected to ship with the next official release. For now, use Expert Council through the native Pi Package, the CLI, or the generic MCP Server.
-
 Key advantages:
 
 | Advantage | Description |
@@ -19,7 +17,7 @@ In practice, the theoretically strongest model is not automatically the best exe
 
 ## Current status
 
-The current release (0.4.0) includes:
+The current release (0.5.1) includes:
 
 - A host-independent Core: configuration validation, model normalization, billing policy, profile layering, role scoring, task classification, dynamic team sizing, retry/escalation, and telemetry aggregation.
 - An execution runtime built on Pi's current `ModelRuntime` and `createAgentSession` APIs.
@@ -31,7 +29,7 @@ The current release (0.4.0) includes:
 - Runtime availability markers: when a call fails with dead-model evidence, the model is recorded into the persisted assessment and hard-rejected by later council building, delegation, and escalation; markers expire and are retried automatically after 24 hours.
 - Provider session error surfacing: upstream denials such as `403 AccessDenied` are no longer swallowed; they return to the Main Agent with the real diagnostic and the correct failure class.
 - Cross-process shared model assessment: with multiple instances running in parallel, availability markers become visible to each other without a restart.
-- A Codex plugin with the shared Skill and a bundled stdio MCP Server (functional testing incomplete; not yet officially released).
+- A Codex plugin with the shared Skill and a bundled stdio MCP Server, using Codex's host-owned `codex/sandbox-state-meta` capability for workspace discovery (no hooks).
 - Deterministic automated tests that never consume model quota.
 
 ## Architecture
@@ -81,16 +79,27 @@ Requirements:
 - Pi installed and configured with at least one usable model.
 - When writable experts need worktree isolation, the Git repository must have at least one commit.
 
-### Install the Pi Package (available after the npm release)
+### Install the Pi Package
 
-<!-- Placeholder: complete install/upgrade instructions will be added once @expert-council/pi-package is published to npm. -->
+Install from npm (recommended):
 
 ```bash
 pi install npm:@expert-council/pi-package
+pi list
+pi --verbose
+```
+
+`pi list` should show `npm:@expert-council/pi-package` and its resolved directory; a newly started verbose Pi session should load `dist/extension.js`, the `expert-council` Skill, and the eight semantic tools. To upgrade later:
+
+```bash
 pi update npm:@expert-council/pi-package
 ```
 
-The current version is not yet published to npm; build from source and install locally for now (see "Native Pi Package" below):
+### Install the Codex plugin (optional)
+
+To run Codex as the Main Agent, build the repository and install the bundled plugin through a Codex plugin marketplace — see [Codex plugin](#codex-plugin) for the full walkthrough.
+
+### Build from source (development)
 
 ```bash
 npm install
@@ -414,6 +423,8 @@ Environment overrides and CLI path flags are trusted operator inputs. In particu
 
 ## Native Pi Package
 
+For daily use, install from npm (see [Quick start](#install-the-pi-package)); this section covers source development and local candidate validation.
+
 Build and install the local candidate from the repository root. Even on Windows, use forward slashes whenever a command may pass through Pi's Bash-compatible shell; an unquoted `.\packages\pi-package` loses its backslashes before reaching Pi.
 
 ```bash
@@ -454,6 +465,105 @@ Pi loads `dist/extension.js` and the synchronized `expert-council` Skill through
 
 Pi delegation is non-blocking; a single call can start up to eight independent background assignments before returning. When an expert finishes, the extension sends compact JSON containing the completed `executionId` and, only when supplied at dispatch, the `taskDescription`; it never carries feedback directly. Notifications use `steer` while the Main Agent is working and a `triggerTurn` `followUp` when it is idle. The Main Agent then calls `expert_result` for the structured feedback. Dispatch the entire ready batch before ending the turn, and avoid polling or silently waiting afterwards.
 
+## Codex plugin
+
+The Codex plugin turns Codex into the Main Agent: it bundles the shared `expert-council` Skill and a stdio MCP Server, while experts execute through Pi. It ships no hooks — the server uses MCP client roots when available, otherwise derives the task workspace from Codex's host-owned `codex/sandbox-state-meta` capability, then falls back to the `EXPERT_COUNCIL_WORKSPACE` override, and refuses to use the plugin installation directory as a workspace.
+
+The built plugin root is:
+
+```text
+packages/codex-integration/plugin/expert-council/
+  .codex-plugin/plugin.json
+  .mcp.json
+  skills/expert-council/SKILL.md
+  dist/server.mjs
+  dist/roles/*.md
+```
+
+### Installation
+
+Release `v0.5.1` includes the prebuilt MCP server, so Codex can install the plugin directly from the repository as a pinned Git marketplace. Node.js 22.19 or newer and a working Pi installation are required at runtime; cloning and building this repository is not required.
+
+```bash
+codex plugin marketplace add Labiey/expert-council-router --ref v0.5.1 --json
+codex plugin marketplace list --json
+codex plugin list --marketplace expert-council-router --available --json
+codex plugin add expert-council@expert-council-router --json
+codex plugin list --json
+```
+
+`marketplace add` is needed only once for this release. If the marketplace name is already registered from an older or local source, remove that source first or follow the upgrade procedure below. `plugin list --json` should show `expert-council` as installed from `expert-council-router`.
+
+Codex Desktop on Windows includes the CLI, but it may not be on `PATH`. In PowerShell, resolve the running Desktop binary and use it for the same remote installation:
+
+```powershell
+$ecCodex = (Get-Command codex.exe -ErrorAction SilentlyContinue).Source
+if (-not $ecCodex) {
+    $ecCodex = Get-Process codex -ErrorAction SilentlyContinue |
+        Where-Object Path |
+        Select-Object -First 1 -ExpandProperty Path
+}
+if (-not $ecCodex) {
+    $ecCodex = Get-ChildItem (Join-Path $env:LOCALAPPDATA "OpenAI/Codex/bin") `
+        -Filter codex.exe -File -Recurse -ErrorAction SilentlyContinue |
+        Sort-Object LastWriteTime -Descending |
+        Select-Object -First 1 -ExpandProperty FullName
+}
+if (-not $ecCodex) { throw "Codex Desktop CLI was not found." }
+
+& $ecCodex plugin marketplace add Labiey/expert-council-router --ref v0.5.1 --json
+& $ecCodex plugin marketplace list --json
+& $ecCodex plugin list --marketplace expert-council-router --available --json
+& $ecCodex plugin add "expert-council@expert-council-router" --json
+& $ecCodex plugin list --json
+```
+
+Fully quit Codex Desktop, wait for its backend process to exit, reopen it, and start a new task. Merely opening another task is not a reliable MCP reload boundary in every Desktop build.
+
+For local plugin development, clone the repository, run `npm ci && npm run build`, and pass its absolute root to `codex plugin marketplace add` instead of the GitHub repository name. The pinned remote release is recommended for normal use.
+
+A correct load exposes the `expert-council` Skill and all nine `expert_*` MCP tools. If the Skill is present but the tools are absent, treat the installation as failed: restart or reinstall the plugin instead of launching `dist/server.mjs` manually or sending hand-written JSON-RPC.
+
+To verify the installed workflow, use a new Codex task and ask:
+
+```text
+Use Expert Council to inspect the currently available Pi models, providers, billing classification, and model-assessment status. Return only a compact summary; do not build a council or delegate experts.
+```
+
+The task should invoke `expert_inspect`. It should not ask for hook trust, manually launch the MCP server, or treat the plugin cache as the project workspace.
+
+### Upgrade
+
+A marketplace pinned with `--ref` intentionally stays on that release. To upgrade, remove the installed plugin and old marketplace registration, then add the new tag and reinstall:
+
+```bash
+codex plugin remove expert-council@expert-council-router --json
+codex plugin marketplace remove expert-council-router --json
+codex plugin marketplace add Labiey/expert-council-router --ref vX.Y.Z --json
+codex plugin add expert-council@expert-council-router --json
+```
+
+Replace `vX.Y.Z` with the intended release. Users who deliberately track the default branch can omit `--ref` and later run `codex plugin marketplace upgrade expert-council-router --json`, but pinned tags are safer for normal use. After reinstalling, fully restart Codex Desktop and test in a new task. Avoid installing multiple copies that all declare the `expert_council` MCP server.
+
+### Behavior highlights
+
+- The bundled `.mcp.json` raises the host tool-call ceiling to 3660 seconds so a single bounded `expert_wait` can block until completion; the Skill still requires explicit per-operation deadlines rather than treating that ceiling as a default budget.
+- On the first council of a conversation the Main Agent establishes exactly one cost policy with you (economy, balanced, or speed); until then `expert_build` and `expert_delegate` responses carry reminders to ask.
+- Writable experts mutate inside a detached Git worktree under the trusted workspace; changes come back for Main Agent review and are never auto-merged.
+
+### Removal
+
+Remove the plugin and its marketplace registration:
+
+```bash
+codex plugin remove expert-council@expert-council-router --json
+codex plugin marketplace remove expert-council-router --json
+codex plugin list --json
+codex plugin marketplace list --json
+```
+
+On Windows, replace `codex` with `& $ecCodex` when using the PowerShell variable above. Fully quit Codex Desktop before starting new tasks.
+
 ## Testing
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expert-council/pi-package",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Native Pi package exposing Expert Council tools and host guidance",
   "type": "module",
   "main": "./dist/extension.js",
@@ -17,8 +17,8 @@
     "skills": ["./skills"]
   },
   "dependencies": {
-    "@expert-council/core": "0.4.0",
-    "@expert-council/pi-runtime": "0.4.0"
+    "@expert-council/core": "0.5.1",
+    "@expert-council/pi-runtime": "0.5.1"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.84.0 <1",

package/skills/expert-council/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: expert-council
-description: Use a cost-aware Pi expert council for substantial bounded investigation, implementation, debugging, review, or verification when delegation is likely to save meaningful context, execution effort, or scarce-model quota. Do not use for trivial work.
+description: Use the Pi expert council by default for substantial work — code review, architecture analysis, bug investigation, feature implementation, refactoring, repository exploration, test writing, or verification — whenever delegation saves Main Agent context, execution effort, or scarce-model quota. Engage it in every conversation turn where such work appears, including later turns; skip it only for trivial single-file lookups or one-line edits.
 ---
 
 # Expert Council
@@ -11,8 +11,8 @@ Use Expert Council only when delegation is likely to save significant context, e
 2. Before building the first council in a new conversation, establish exactly one assembly preference. If the user has not already stated one, ask whether to optimize for `economy` (lowest effective marginal cost), `balanced` (cost, completion time, and success probability), or `speed` (fastest completion). Stop and wait for the answer. Reuse that choice for later councils in the same conversation; ask again only if the user changes it. The native Pi tool enforces this fallback and stores the choice in session state.
 3. The Main Agent, not the user, assesses which models fit each role. If `modelAssessment.status` is `required`, do not call `expert_build` or `expert_delegate` yet. Use an already available network research tool to cross-check current evidence only for keys in `researchModels`. Preserve saved scores for the remaining `requiredModels` entries. If no network research tool is available, stop and tell the user that the mandatory audit cannot be completed; never silently fall back to unaudited defaults. Never install a browser, Skill, plugin, or executable package automatically.
 4. For the mandatory audit, consider only models returned by `expert_inspect`. Prefer current primary or first-party evidence: Artificial Analysis for coding/agentic scores, price, throughput, and latency; LiveBench for coding and agentic coding; Arena for human preference; provider documentation for model/version/runtime and access-method facts. Treat OpenRouter usage rankings only as adoption evidence, not proof of quality. Triangulate into 1–12 consolidated source URLs, read the actual host clock for `asOf` (never synthesize a future timestamp), normalize only supported capability dimensions to 0–10, merge researched entries with saved entries to cover every `requiredModels` key, and include verified provider billing/access classifications when known; leave them `unknown` rather than guessing. Do not infer personal billing from published per-token prices. Pass the complete result as `modelAssessment` to `expert_build`. If the gate reports `future-dated`, retain the same evidence and scores, correct only `asOf`, and do not browse again. When `modelAssessment.status` is `current`, omit `modelAssessment` from `expert_build` so the saved snapshot is reused; do not send an empty or reconstructed table and do not browse again unless the user requests a re-audit.
-5. Call `expert_build` only after the assessment gate is current, with the task and established cost policy. If the tool still returns `model-assessment-required`, follow its instructions and retry once after completing the audit; do not repeatedly call it unchanged. Let deterministic routing combine the Main Agent assessment, objective Pi metadata, billing policy when known, and locally observed reliability. Do not make the user rank individual models manually and do not assume a newer or more popular model is automatically best for every role.
-6. Delegate bounded semantic assignments by role with `expert_delegate`. It starts background work and immediately returns execution IDs. Set an explicit finite `timeoutMs` for every assignment according to task difficulty instead of relying on the runtime fallback: normally 2–5 minutes for focused read-only work, 10–20 minutes for ordinary implementation/debugging, and at most 30–60 minutes for justified long-running work. When two or more independent assignments are ready, send them together in `assignments` as a real JSON array, never a quoted/stringified JSON value, so the entire batch is dispatched before the host turn ends. Add a short `taskDescription` when recognizing a task later would help.
+5. Call `expert_build` only after the assessment gate is current, with the task and the established cost policy passed as `constraints.costPolicy`. If the tool still returns `model-assessment-required`, follow its instructions and retry once after completing the audit; do not repeatedly call it unchanged. When the response warns that no costPolicy was supplied, stop and ask the user once for economy, balanced, or speed before the next build. Let deterministic routing combine the Main Agent assessment, objective Pi metadata, billing policy when known, and locally observed reliability. Do not make the user rank individual models manually and do not assume a newer or more popular model is automatically best for every role.
+6. Delegate bounded semantic assignments by role with `expert_delegate`. It starts background work and immediately returns execution IDs. If no cost policy has been established in this conversation, ask the user once (economy, balanced, or speed) before the first dispatch; an `expert_delegate` or `expert_build` response carrying `reminders` means the policy is still missing. Set an explicit finite `timeoutMs` for every assignment according to task difficulty instead of relying on the runtime fallback: normally 2–5 minutes for focused read-only work, 10–20 minutes for ordinary implementation/debugging, and at most 30–60 minutes for justified long-running work. When two or more independent assignments are ready, send them together in `assignments` as a real JSON array, never a quoted/stringified JSON value, so the entire batch is dispatched before the host turn ends. Add a short `taskDescription` when recognizing a task later would help. If a writable assignment is rejected because the runtime provides no mutation, retry once with `workspace` set to the target project's Git repository root inside the trusted boundary — the conversation's startup folder itself may not be a repository.
 7. After dispatching the complete batch, continue any independent Main Agent work. Follow the host-specific completion workflow appended by the distribution; do not poll repeatedly or spend model tokens on an idle loop.
 8. When the host reports a completed `executionId`, call `expert_result` with that exact ID before using the feedback. Prefer read-only investigation before mutation, retain architecture and final acceptance in the Main Agent, and never create a redundant lead expert when the host Main Agent already owns that role.
 9. Verify important results, then call `expert_feedback` so local routing can learn. Inspect isolated worktree changes before integration and call `expert_cleanup` after integrating or rejecting them. Do not delegate trivial work or allow recursive expert delegation.