The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
feat(agents): integrate isolated Pi conversion foundation from PR 3022
haelyraeb7ffd8d643e
diff --git a/.pi/extensions/index.ts b/.pi/extensions/index.tsindex 65810292d..241deabce 100644--- a/.pi/extensions/index.ts+++ b/.pi/extensions/index.ts@@ -24,7 +24,7 @@* degrades to a warning and never terminates the Pi session.*/-import { execFile } from "node:child_process"+import { execFile, execFileSync } from "node:child_process"import * as fs from "node:fs"import * as os from "node:os"import * as path from "node:path"@@ -556,11 +556,74 @@ function describeRulesStatus(): string {return `${cachedRuleFileCount}/${PORTABLE_RULE_FILES.length} rule file(s), ${rules.length} chars, from rules/common/${shortfall}`}+const AGENT_CHECK_TIMEOUT_MS = 5_000++type AgentPortability =+ | { status: "validated"; count: number }+ | { status: "failed"; reason: string }+ | { status: "unvalidated"; reason: string }++/**+ * Verify agent portability by actually running `agent-convert.js --check` rather+ * than trusting file existence. A converter that exists but fails (schema drift,+ * a frontmatter variant that fails ajv) must not report a green doctor line.+ */+function validateAgentPortability(converterScript: string): AgentPortability {+ if (!fs.existsSync(converterScript)) {+ return { status: "unvalidated", reason: "converter script not found" }+ }++ let nodeExec: string+ try {+ nodeExec = resolveHookRuntime()+ } catch (err) {+ return { status: "unvalidated", reason: `no node runtime: ${messageOf(err)}` }+ }++ try {+ const stdout = execFileSync(nodeExec, [converterScript, "--check"], {+ timeout: AGENT_CHECK_TIMEOUT_MS,+ encoding: "utf8",+ })+ const match = stdout.match(/OK: (\d+) agents parsed and validated/)+ if (match) {+ return { status: "validated", count: parseInt(match[1], 10) }+ }+ return { status: "failed", reason: `unexpected output: ${stdout.slice(0, 200).trim()}` }+ } catch (err) {+ return { status: "failed", reason: messageOf(err) }+ }+}++function messageOf(err: unknown): string {+ if (err && typeof err === "object" && "message" in err) {+ return String((err as { message: unknown }).message)+ }+ return "unknown error"+}++function describeAgentPortability(agentCount: number, portability: AgentPortability): string {+ if (agentCount === 0) {+ return "NOT FOUND"+ }+ if (portability.status === "validated") {+ return `${portability.count} agent(s) source schema validated; Pi conversion available via scripts/agent-convert.js`+ }+ if (portability.status === "failed") {+ return `${agentCount} agent(s) present but validation FAILED: ${portability.reason}`+ }+ return `${agentCount} agent(s) present (unvalidated — ${portability.reason})`+}+function buildDoctorReport(ctx: ExtensionContext): string {const skillsDir = path.join(ECC_ROOT, "skills")const commandsDir = path.join(ECC_ROOT, "commands")const skillCount = countDirectories(skillsDir)const commandCount = countMarkdownFiles(commandsDir)+ const agentsDir = path.join(ECC_ROOT, "agents")+ const agentCount = countMarkdownFiles(agentsDir)+ const converterScript = path.join(ECC_ROOT, "scripts", "agent-convert.js")+ const agentLine = describeAgentPortability(agentCount, validateAgentPortability(converterScript))const lines = ["ECC adapter for Pi",@@ -572,6 +635,7 @@ function buildDoctorReport(ctx: ExtensionContext): string {"Canonical resources",` skills/ ${skillCount > 0 ? `${skillCount} skill(s)` : "NOT FOUND"} (${skillsDir})`,` commands/ ${commandCount > 0 ? `${commandCount} command(s)` : "NOT FOUND"} (${commandsDir})`,+ ` agents/ ${agentLine} (${agentsDir})`,"","Engineering rules (injected into the system prompt)",` ${describeRulesStatus()}`,diff --git a/docs/architecture/harness-adapter-compliance.md b/docs/architecture/harness-adapter-compliance.mdindex 09061190d..97588546f 100644--- a/docs/architecture/harness-adapter-compliance.md+++ b/docs/architecture/harness-adapter-compliance.md@@ -39,7 +39,7 @@ The matrix below is rendered from| Claude Code | Native | Claude plugin assets; skills; commands; hooks; MCP config; local rules; statusline-oriented workflows | Claude-native hooks do not imply parity in other harnesses | `./install.sh --profile minimal --target claude`; Claude plugin install | `npm run harness:audit -- --format json`; `node scripts/session-inspect.js --list-adapters` | Avoid loading every skill by default; keep hooks opt-in and inspectable. || Codex | Instruction-backed | `AGENTS.md`; Codex plugin metadata; skills; MCP reference config; command patterns | Native hook enforcement and Claude slash-command semantics are not equivalent | `./install.sh --profile minimal --target codex`; repo-local `AGENTS.md` review | `npm run harness:audit -- --format json` | Treat hooks as policy text unless a native Codex hook surface exists. || OpenCode | Adapter-backed | OpenCode package/plugin metadata; shared skills; MCP config; event adapter patterns | Event names, plugin packaging, and command dispatch differ from Claude Code | OpenCode package or plugin surface from this repo | `node tests/scripts/build-opencode.test.js`; `npm run harness:audit -- --format json` | Keep hook logic in shared scripts and adapt only event shape at the edge. |-| Pi | Adapter-backed | Pi package manifest; canonical ECC skills (skills/); canonical ECC commands as prompt templates (commands/); canonical ECC engineering rules (rules/common/) injected into the system prompt; session lifecycle hook adapter; /ecc-doctor diagnostics command | Subagents, chains, approval prompts, and persistent todos require companion Pi packages and are not part of this adapter; Pi core has no MCP surface, though ECC MCP configs load verbatim through the community pi-mcp-adapter package, which ECC neither installs nor depends on | `pi install git:github.com/affaan-m/ECC`; `pi install /path/to/ECC` from a local checkout | `node tests/pi/pi-package-manifest.test.js`; `node tests/pi/pi-extension-adapter.test.js`; `npm run harness:adapters -- --check` | Pi extensions execute with full user permissions, and hooks run without a shell and resolve from the installed package rather than the user project; Keep canonical skills and commands as the single source of truth, and never generate copies under .pi/ |+| Pi | Adapter-backed | Pi package manifest; canonical ECC skills (skills/); canonical ECC commands as prompt templates (commands/); canonical ECC engineering rules (rules/common/) injected into the system prompt; session lifecycle hook adapter; /ecc-doctor diagnostics command; canonical ECC agents (agents/) portable via scripts/agent-convert.js (claude -> pi) | Agent chains, approval prompts, and persistent todos require companion Pi packages and are not part of this adapter (individual agent definitions are portable via scripts/agent-convert.js); Pi core has no MCP surface, though ECC MCP configs load verbatim through the community pi-mcp-adapter package, which ECC neither installs nor depends on | `pi install git:github.com/affaan-m/ECC`; `pi install /path/to/ECC` from a local checkout | `node tests/pi/pi-package-manifest.test.js`; `node tests/pi/pi-extension-adapter.test.js`; `node tests/pi/agent-convert.test.js`; `npm run harness:adapters -- --check` | Pi extensions execute with full user permissions, and hooks run without a shell and resolve from the installed package rather than the user project; Keep canonical skills and commands as the single source of truth, and never generate copies under .pi/ || Cursor | Adapter-backed | Cursor rules; project-local skills; hook adapter; shared scripts | Cursor hook events and rule loading differ from Claude Code | `./install.sh --profile minimal --target cursor` | `node tests/lib/install-targets.test.js`; `npm run harness:audit -- --format json` | Cursor adapters must preserve existing project rules and avoid silent overwrite. || Gemini | Instruction-backed | Gemini project-local instructions; shared skills; rules; compatibility docs | No full ECC hook parity; ecosystem ports must document drift from upstream ECC | `./install.sh --profile minimal --target gemini` | `node tests/lib/install-targets.test.js` | Treat Gemini ports as ecosystem adapters until validated end to end inside Gemini CLI. || Zed | Adapter-backed | Zed project settings; flattened project rules; shared skills; commands; agents | Zed external agents and native Agent Panel permissions are not Claude hooks | `./install.sh --profile minimal --target zed` | `node tests/lib/install-targets.test.js`; `npm run harness:audit -- --format json` | Keep project settings conservative and do not copy BYOK/OpenRouter secrets into `.zed/`. |diff --git a/package.json b/package.jsonindex ec14ccc57..fb9eb4f8e 100644--- a/package.json+++ b/package.json@@ -109,6 +109,7 @@"plugins/ecc/","rules/","schemas/",+ "scripts/agent-convert.js","scripts/catalog.js","scripts/ci/scan-supply-chain-iocs.js","scripts/ci/supply-chain-advisory-sources.js",diff --git a/schemas/agent.schema.json b/schemas/agent.schema.jsonnew file mode 100644index 000000000..a04cd56ca--- /dev/null+++ b/schemas/agent.schema.json@@ -0,0 +1,59 @@+{+ "$schema": "http://json-schema.org/draft-07/schema#",+ "$id": "ecc.agent-ir.v1",+ "title": "ECC Agent IR",+ "description": "Canonical harness-neutral representation of an ECC agent, produced from a source harness definition (e.g. agents/*.md Claude frontmatter). Emitters consume this IR and produce native agent/subagent definitions per harness. The `tools` array holds source tool names verbatim (lossless); each emitter maps them through its own tool table.",+ "type": "object",+ "additionalProperties": false,+ "required": [+ "schema",+ "id",+ "name",+ "description",+ "tools",+ "body"+ ],+ "properties": {+ "schema": {+ "const": "ecc.agent-ir.v1"+ },+ "id": {+ "type": "string",+ "description": "Stable canonical id; the source filename stem (kebab-case).",+ "pattern": "^[a-z0-9-]+$"+ },+ "name": {+ "type": "string",+ "description": "Agent name from the source frontmatter."+ },+ "description": {+ "type": "string",+ "description": "Agent description from the source frontmatter."+ },+ "model": {+ "type": "string",+ "description": "Source model tier, when present. Claude aliases only in v1.",+ "enum": ["haiku", "sonnet", "opus"]+ },+ "tools": {+ "type": "array",+ "description": "Source tool names verbatim (Claude tool identifiers such as Read, Grep, Glob, Bash, Edit, Write, WebSearch, WebFetch, mcp__*).",+ "items": {+ "type": "string"+ }+ },+ "color": {+ "type": "string",+ "description": "Optional source-only metadata (Claude color tag); emitters may ignore it."+ },+ "body": {+ "type": "string",+ "description": "The agent system prompt / markdown body after the frontmatter."+ },+ "frontmatter": {+ "type": "object",+ "description": "Lossless raw source frontmatter for round-trip fidelity and forward compatibility.",+ "additionalProperties": true+ }+ }+}diff --git a/scripts/agent-convert.js b/scripts/agent-convert.jsnew file mode 100644index 000000000..5274917f7--- /dev/null+++ b/scripts/agent-convert.js@@ -0,0 +1,175 @@+#!/usr/bin/env node+'use strict';++/**+ * ECC Agent IR — converter CLI.+ *+ * Converts ECC's canonical agents from one harness format to another. v1+ * supports a single direction: `claude -> pi`. Future emitters (cursor,+ * opencode, gemini, codex, zed) plug into the same IR.+ *+ * Usage:+ * node scripts/agent-convert.js --check+ * node scripts/agent-convert.js --from claude --to pi [--json]+ * node scripts/agent-convert.js --from claude --to pi --out <dir> [--dry-run]+ *+ * When `--json` is set, stdout carries only the machine-readable summary;+ * progress lines (wrote / would-write) go to stderr so automation can parse+ * stdout as JSON.+ */++const fs = require('fs');+const path = require('path');+const { parseAllAgents } = require('./lib/agent-ir');+const { emitAllPiAgents } = require('./lib/agent-emit-pi');++const SUPPORTED = { claude: ['pi'] };++const EMITTERS = {+ pi: emitAllPiAgents,+};++function requireValue(argv, index, flag) {+ const value = argv[index + 1];+ if (value === undefined || value === '' || value.startsWith('--')) {+ throw new Error(`missing value for ${flag}`);+ }+ return value;+}++function parseArgs(argv) {+ let args = { from: 'claude', to: 'pi', json: false, dryRun: false, check: false, out: null };+ for (let i = 0; i < argv.length; i++) {+ const a = argv[i];+ if (a === '--from') {+ args = { ...args, from: requireValue(argv, i, '--from') };+ i++;+ } else if (a === '--to') {+ args = { ...args, to: requireValue(argv, i, '--to') };+ i++;+ } else if (a === '--json') {+ args = { ...args, json: true };+ } else if (a === '--dry-run') {+ args = { ...args, dryRun: true };++ } else if (a === '--check') {+ args = { ...args, check: true };+ } else if (a === '--out') {+ args = { ...args, out: requireValue(argv, i, '--out') };+ i++;+ } else if (a === '--help' || a === '-h') {+ args = { ...args, help: true };+ } else {+ throw new Error(`unknown argument: ${a}`);+ }+ }+ return args;+}++function showHelp() {+ console.log(`ECC Agent IR converter (v1)++Usage:+ node scripts/agent-convert.js --check+ Parse and validate every agent under agents/ against the IR schema.++ node scripts/agent-convert.js --from claude --to pi [--json]+ Emit all agents as Pi subagent definitions and print a summary.++ node scripts/agent-convert.js --from claude --to pi --out <dir> [--dry-run]+ Write emitted Pi agent files (<dir>/<id>.md). --dry-run prints only.++Options:+ --from <claude> Source harness (v1: claude only)+ --to <pi> Target harness (v1: pi only)+ --json Machine-readable summary on stdout+ --out <dir> Write emitted files to a directory+ --dry-run With --out, report writes without writing+ --check Validate parsing only (no emit)+`);+}++function main() {+ let args;+ try {+ args = parseArgs(process.argv.slice(2));+ } catch (err) {+ console.error(`error: ${err.message}`);+ process.exit(2);+ }+ if (args.help) {+ showHelp();+ process.exit(0);+ }++ if (!SUPPORTED[args.from] || !SUPPORTED[args.from].includes(args.to)) {+ console.error(`error: unsupported conversion ${args.from} -> ${args.to}`);+ console.error(`supported: ${Object.entries(SUPPORTED).map(([f, ts]) => `${f} -> ${ts.join(',')}`).join('; ')}`);+ process.exit(2);+ }++ let irs;+ try {+ irs = parseAllAgents();+ } catch (err) {+ console.error(`error: ${err.message}`);+ process.exit(1);+ }++ if (args.check) {+ if (args.json) {+ console.log(JSON.stringify({ schema: 'ecc.agent-ir.v1', checked: irs.length, ok: true }, null, 2));+ } else {+ console.log(`OK: ${irs.length} agents parsed and validated against ecc.agent-ir.v1`);+ }+ process.exit(0);+ }++ const { results, warnings, notes, skipped } = EMITTERS[args.to](irs);++ // Progress lines must never corrupt machine-readable stdout.+ const progress = msg => {+ if (args.json) process.stderr.write(`${msg}\n`);+ else console.log(msg);+ };++ if (args.out) {+ const dir = path.resolve(args.out);+ if (!args.dryRun) fs.mkdirSync(dir, { recursive: true });+ for (const r of results) {+ const target = path.join(dir, `${r.id}.md`);+ if (args.dryRun) {+ progress(`[dry-run] would write ${target}`);+ } else {+ fs.writeFileSync(target, r.markdown);+ progress(`wrote ${target}`);+ }+ }+ }++ const summary = {+ schema: 'ecc.agent-ir.v1',+ from: args.from,+ to: args.to,+ converted: results.length,+ warnings: warnings.length,+ warningsDetail: warnings,+ skipped: skipped ? skipped.length : 0,+ notes,+ };++ if (args.json) {+ console.log(JSON.stringify(summary, null, 2));+ } else {+ console.log(`converted ${results.length} agents (${args.from} -> ${args.to})`);+ for (const note of notes) {+ console.log(` ${note}`);+ }+ if (warnings.length) {+ console.log(`\n${warnings.length} actionable warning(s):`);+ for (const w of warnings) console.log(` - ${w}`);+ }+ }+}++main();diff --git a/scripts/lib/agent-emit-pi.js b/scripts/lib/agent-emit-pi.jsnew file mode 100644index 000000000..1d8956332--- /dev/null+++ b/scripts/lib/agent-emit-pi.js@@ -0,0 +1,134 @@+#!/usr/bin/env node+'use strict';++/**+ * ECC Agent IR — Pi emitter.+ *+ * Turns one IR object into a native Pi subagent definition (markdown file with+ * Pi frontmatter). The frontmatter contract is verified against+ * `@tintinweb/[email protected]`: fields are `name` (the dispatch id),+ * `description`, `tools` (a comma-separated strict child allowlist), and+ * `prompt_mode` (`replace` keeps the body as the complete system prompt). The+ * prompt lives in the document body.+ *+ * v1 behavior:+ * - The source model tier is preserved as a YAML comment+ * (`# source model tier: opus`) rather than a `model:` field, because+ * Claude tiers are not valid Pi model ids. Pi's default child model+ * applies; the tier is lossless in the IR and visible in the emitted file.+ * - Unmapped tools (WebSearch, WebFetch, mcp__*) are never silently dropped;+ * they surface in per-agent `warnings`.+ * - Specialist isolation disables inherited extensions and skills, so the+ * builtin allowlist cannot silently inherit configured extension tools.+ * - The allowlist is always written. An empty allowlist is emitted as+ * `tools: none`, never blank, because the companion's `csvList` treats a+ * blank/missing `tools:` as *all* built-ins — which would escalate a+ * fully-unmapped agent to every tool.+ */++const { mapToolToPi } = require('./agent-tool-map');++// Pi core built-in agent names (case-sensitive). ECC agent names are kebab-case+// and do not collide today; warn if a future one ever does.+const RESERVED_AGENT_NAMES = new Set(['general-purpose', 'Explore', 'Plan']);++/**+ * Emit a Pi agent definition for one IR object.+ *+ * @param {object} ir+ * @returns {{ markdown: string, warnings: string[], tools: string[] }}+ */+function emitPiAgent(ir) {+ const warnings = [];+ const seen = new Set();+ const tools = [];++ for (const sourceTool of ir.tools) {+ const mapped = mapToolToPi(sourceTool);+ if (mapped.tool && !seen.has(mapped.tool)) {+ seen.add(mapped.tool);+ tools.push(mapped.tool);+ }+ if (mapped.note) {+ warnings.push(`${ir.id}: ${mapped.note}`);+ }+ }++ if (RESERVED_AGENT_NAMES.has(ir.name)) {+ warnings.push(`${ir.id}: name '${ir.name}' collides with a Pi built-in agent; rename to avoid shadowing`);+ }++ // Never emit a blank allowlist: `none` is the explicit "no tools" sentinel.+ const toolsValue = tools.length > 0 ? tools.join(', ') : 'none';++ const frontmatter = [+ '---',+ ...(ir.model ? [`# source model tier: ${ir.model}`] : []),+ `name: ${yamlScalar(ir.name)}`,+ `description: ${yamlScalar(ir.description)}`,+ `tools: ${toolsValue}`,+ 'prompt_mode: replace',+ 'isolated: true',+ 'extensions: false',+ 'skills: false',+ '---',+ ];++ const body = (ir.body || '').replace(/^\n+/, '').trimEnd();+ const markdown = frontmatter.join('\n') + '\n\n' + body + '\n';+ return { markdown, warnings, tools };+}++/** Emit a single-line YAML scalar, quoted only when needed. */+function yamlScalar(value) {+ const s = String(value);+ // Quote when it contains a leading/trailing space, a colon followed by a+ // space, a comment-starting hash, a leading special char, or a newline.+ if (/^\s|\s$|: |\n|\s#|^[-?*&|>#@`"'\][{}!,]/.test(s)) {+ return JSON.stringify(s);+ }+ return s;+}++/**+ * Emit the full set of Pi agents, sorted by id for determinism, plus notes on+ * the deliberate (documented) lossy conversions.+ *+ * @param {object[]} irs+ * @returns {{ results: object[], warnings: string[], notes: string[] }}+ */+function emitAllPiAgents(irs) {+ const results = [];+ const warnings = [];+ let modelTiers = {};+ let unsupported = 0;++ for (const ir of [...irs].sort((a, b) => a.id.localeCompare(b.id))) {+ const { markdown, warnings: w, tools } = emitPiAgent(ir);+ results.push({ id: ir.id, name: ir.name, tools, markdown });+ warnings.push(...w);++ if (ir.model) {+ modelTiers = { ...modelTiers, [ir.model]: (modelTiers[ir.model] || 0) + 1 };+ }+ unsupported += ir.tools.filter(t => mapToolToPi(t).unsupported).length;+ }++ const notes = [];+ if (Object.keys(modelTiers).length) {+ const tiers = Object.entries(modelTiers).map(([t, n]) => `${t} x${n}`).join(', ');+ notes.push(`model tiers preserved as comments (${tiers}) — Pi uses its default child model`);+ }+ if (unsupported) {+ notes.push(`unmapped tools: ${unsupported} (WebSearch/WebFetch/mcp__* are not Pi built-ins) — see warnings`);+ }++ return { results, warnings, notes };+}++module.exports = {+ RESERVED_AGENT_NAMES,+ emitPiAgent,+ emitAllPiAgents,+ yamlScalar,+};diff --git a/scripts/lib/agent-ir.js b/scripts/lib/agent-ir.jsnew file mode 100644index 000000000..5e35fdff9--- /dev/null+++ b/scripts/lib/agent-ir.js@@ -0,0 +1,157 @@+#!/usr/bin/env node+'use strict';++/**+ * ECC Agent IR — parser.+ *+ * Reads ECC's canonical agent files (Claude frontmatter markdown) and emits+ * harness-neutral IR objects validated against `schemas/agent.schema.json`.+ *+ * Design constraints:+ * - Deterministic: stable key order, no ambient state.+ * - Lossless: the raw frontmatter is retained so emitters can round-trip.+ * - Strict: invalid model tiers and non-string tool entries are rejected,+ * never silently coerced or dropped.+ * - No shell, no network, no new dependencies (uses `js-yaml` + `ajv`,+ * which are already in `package.json`).+ */++const fs = require('fs');+const path = require('path');+const yaml = require('js-yaml');+const Ajv = require('ajv');++const AGENTS_DIR = path.join(__dirname, '..', '..', 'agents');+const SCHEMA_PATH = path.join(__dirname, '..', '..', 'schemas', 'agent.schema.json');++const IR_SCHEMA_CONST = 'ecc.agent-ir.v1';+const VALID_MODELS = ['haiku', 'sonnet', 'opus'];++let _ajv = null;+function ajv() {+ if (!_ajv) {+ _ajv = new Ajv({ allErrors: true, strict: false });+ const schema = JSON.parse(fs.readFileSync(SCHEMA_PATH, 'utf8'));+ _ajv.addSchema(schema, IR_SCHEMA_CONST);+ }+ return _ajv;+}++/** Split frontmatter + body, tolerating UTF-8 BOM and LF/CRLF. */+function splitFrontmatter(content) {+ const clean = content.replace(/^\uFEFF/, '');+ const match = clean.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);+ if (!match) {+ return { frontmatter: null, body: null };+ }+ return { frontmatter: match[1], body: match[2] || '' };+}++/**+ * Normalize a frontmatter `tools` value to a string[].+ * Claude agents use comma-separated strings (e.g. `Read, Grep, Glob`).+ * Non-string scalars and non-string array entries are rejected.+ */+function normalizeTools(value, filename) {+ if (value === null || value === undefined) return [];++ const entries = Array.isArray(value)+ ? value+ : typeof value === 'string'+ ? value.split(',')+ : null;++ if (entries === null) {+ throw new Error(`${filename}: tools must be a comma-separated string or a list of strings`);+ }++ const tools = [];+ for (const entry of entries) {+ if (typeof entry !== 'string') {+ throw new Error(`${filename}: tools must contain only strings`);+ }+ const trimmed = entry.trim();+ if (trimmed) tools.push(trimmed);+ }+ return tools;+}++/** Parse one agent file into an IR object (throws on malformed input). */+function parseAgentFile(filePath) {+ const filename = path.basename(filePath);+ const id = filename.replace(/\.md$/, '');++ let content;+ try {+ content = fs.readFileSync(filePath, 'utf8');+ } catch (err) {+ throw new Error(`${filename}: cannot read: ${err.message}`);+ }++ const { frontmatter, body } = splitFrontmatter(content);+ if (frontmatter === null) {+ throw new Error(`${filename}: missing frontmatter (expected leading --- block)`);+ }++ let raw;+ try {+ raw = yaml.load(frontmatter);+ } catch (err) {+ throw new Error(`${filename}: invalid YAML frontmatter: ${err.message}`);+ }+ if (!raw || typeof raw !== 'object') {+ throw new Error(`${filename}: frontmatter must be a YAML mapping`);+ }++ const model = raw.model;+ if (model !== undefined && !VALID_MODELS.includes(model)) {+ throw new Error(`${filename}: invalid model tier '${model}' (expected haiku, sonnet, or opus)`);+ }++ const ir = {+ schema: IR_SCHEMA_CONST,+ id,+ name: typeof raw.name === 'string' ? raw.name : id,+ description: typeof raw.description === 'string' ? raw.description : '',+ tools: normalizeTools(raw.tools, filename),+ body,+ frontmatter: raw,+ ...(model !== undefined ? { model } : {}),+ ...(raw.color !== undefined ? { color: String(raw.color) } : {}),+ };++ validateIr(ir, filename);+ return ir;+}++function validateIr(ir, filename) {+ const validate = ajv().getSchema(IR_SCHEMA_CONST);+ const ok = validate(ir);+ if (!ok) {+ const detail = (validate.errors || []).map(e => `${e.instancePath} ${e.message}`).join('; ');+ throw new Error(`${filename}: IR validation failed: ${detail}`);+ }+}++/** Parse every agent under `agents/`, sorted for determinism. */+function parseAllAgents(dir = AGENTS_DIR) {+ if (!fs.existsSync(dir)) {+ throw new Error(`agents directory not found: ${dir}`);+ }+ const files = fs+ .readdirSync(dir)+ .filter(f => f.endsWith('.md'))+ .sort();+ return files.map(f => parseAgentFile(path.join(dir, f)));+}++module.exports = {+ AGENTS_DIR,+ SCHEMA_PATH,+ IR_SCHEMA_CONST,+ VALID_MODELS,+ parseAgentFile,+ parseAllAgents,+ splitFrontmatter,+ normalizeTools,+};diff --git a/scripts/lib/agent-tool-map.js b/scripts/lib/agent-tool-map.jsnew file mode 100644index 000000000..538c61c4c--- /dev/null+++ b/scripts/lib/agent-tool-map.js@@ -0,0 +1,69 @@+#!/usr/bin/env node+'use strict';++/**+ * ECC Agent IR — tool and model mapping tables.+ *+ * The IR stores source (Claude) tool names verbatim. Each emitter maps those+ * names to its own harness primitives through a table. Unmapped tools are+ * never silently dropped: they are surfaced as `unsupported` so the emitter+ * can warn and the conformance test can assert the mapping is complete.+ *+ * Pi tool names are verified against the installed+ * `@earendil-works/pi-coding-agent` `dist/core/tools/index.d.ts`:+ * read | bash | powershell | edit | write | grep | find | ls+ * (`powershell` is Windows-only and not emitted here.)+ *+ * Security invariant: a Claude tool must never map to a Pi tool with MORE+ * authority than the source. Read-only Claude tools (Read, Grep, Glob) map to+ * read-only Pi tools (read, grep, find), never to `bash`.+ */++/** Claude tool name -> Pi tool name. */+const CLAUDE_TO_PI_TOOLS = Object.freeze({+ Read: 'read',+ Grep: 'grep',+ Glob: 'find',+ Bash: 'bash',+ Edit: 'edit',+ Write: 'write',+ // WebSearch and WebFetch are intentionally NOT mapped: Pi exposes no+ // `web_search` or `fetch_content` built-in. They fall through to the+ // "unmapped tool" warning rather than being guessed.+});++/**+ * Map one Claude tool name to a Pi tool allowlist entry.+ *+ * @param {string} claudeTool+ * @returns {{ tool: string|null, unsupported: boolean, note?: string }}+ * `tool` is the Pi tool name, or null when unsupported. `unsupported` is+ * true only for source tools that have no Pi built-in equivalent in v1.+ */+function mapToolToPi(claudeTool) {+ const name = String(claudeTool).trim();+ if (Object.prototype.hasOwnProperty.call(CLAUDE_TO_PI_TOOLS, name)) {+ return { tool: CLAUDE_TO_PI_TOOLS[name], unsupported: false };+ }+ if (name.startsWith('mcp__')) {+ return {+ tool: null,+ unsupported: true,+ note: `MCP tool ${name} not a Pi built-in (configure the MCP server explicitly)`,+ };+ }+ return { tool: null, unsupported: true, note: `unmapped tool: ${name} (not a Pi built-in)` };+}++/**+ * Claude model tiers. Pi resolves its own child model; v1 does not emit a+ * `model` field, so Pi's default applies. The tier is retained in the IR for+ * lossless round-trips and for emitters that do have a model table.+ */+const CLAUDE_MODEL_TIERS = Object.freeze(['haiku', 'sonnet', 'opus']);++module.exports = {+ CLAUDE_TO_PI_TOOLS,+ CLAUDE_MODEL_TIERS,+ mapToolToPi,+};diff --git a/scripts/lib/harness-adapter-compliance.js b/scripts/lib/harness-adapter-compliance.jsindex e1aafd752..df3bbd86a 100644--- a/scripts/lib/harness-adapter-compliance.js+++ b/scripts/lib/harness-adapter-compliance.js@@ -133,27 +133,31 @@ const ADAPTER_RECORDS = Object.freeze(['canonical ECC engineering rules (rules/common/) injected into the system prompt','session lifecycle hook adapter','/ecc-doctor diagnostics command',+ 'canonical ECC agents (agents/) portable via scripts/agent-convert.js (claude -> pi)',],unsupported_surfaces: [- 'Subagents, chains, approval prompts, and persistent todos require companion Pi packages and are not part of this adapter',+ 'Agent chains, approval prompts, and persistent todos require companion Pi packages and are not part of this adapter (individual agent definitions are portable via scripts/agent-convert.js)','Pi core has no MCP surface, though ECC MCP configs load verbatim through the community pi-mcp-adapter package, which ECC neither installs nor depends on',],install_or_onramp: ['`pi install git:github.com/affaan-m/ECC`', '`pi install /path/to/ECC` from a local checkout'],verification_commands: ['`node tests/pi/pi-package-manifest.test.js`','`node tests/pi/pi-extension-adapter.test.js`',+ '`node tests/pi/agent-convert.test.js`','`npm run harness:adapters -- --check`',],risk_notes: ['Pi extensions execute with full user permissions, and hooks run without a shell and resolve from the installed package rather than the user project','Keep canonical skills and commands as the single source of truth, and never generate copies under .pi/',],- last_verified_at: '2026-08-10',+ last_verified_at: '2026-09-08',owner: 'ECC maintainers',source_docs: ['.pi/extensions/index.ts','.pi/README.md','package.json',+ 'schemas/agent.schema.json',+ 'scripts/agent-convert.js',],},{diff --git a/tests/pi/agent-convert.test.js b/tests/pi/agent-convert.test.jsnew file mode 100644index 000000000..dadc2783f--- /dev/null+++ b/tests/pi/agent-convert.test.js@@ -0,0 +1,122 @@+const AGENT_COUNT = require('fs').readdirSync(require('path').join(__dirname,'../../agents')).filter(f => f.endsWith('.md')).length;+/**+ * Tests for the ECC Agent IR converter CLI (scripts/agent-convert.js).+ *+ * Verifies the CLI contract: `--check`, `--json`, `--out` (write and+ * side-effect-free `--dry-run`), and argument/exit-code behavior.+ */++const assert = require("assert")+const fs = require("fs")+const os = require("os")+const path = require("path")+const { execFileSync } = require("child_process")++const CLI = path.join(__dirname, "..", "..", "scripts", "agent-convert.js")+const NODE = process.execPath++function runTest(name, fn) {+ try {+ fn()+ console.log(` ✓ ${name}`)+ return true+ } catch (error) {+ console.log(` ✗ ${name}`)+ console.error(` ${error.message}`)+ return false+ }+}++function runCli(args) {+ return execFileSync(NODE, [CLI, ...args], { encoding: "utf8" })+}++function tmpdir() {+ return fs.mkdtempSync(path.join(os.tmpdir(), "ecc-agent-convert-"))+}++function main() {+ let passed = 0+ let failed = 0++ const tests = [+ ["--check exits 0 and reports AGENT_COUNT agents", () => {+ const out = runCli(["--check"])+ assert.match(out, new RegExp(`OK: ${AGENT_COUNT} agents parsed and validated`))+ }],++ ["--json emits a machine-readable summary", () => {+ const out = runCli(["--from", "claude", "--to", "pi", "--json"])+ const summary = JSON.parse(out)+ assert.strictEqual(summary.schema, "ecc.agent-ir.v1")+ assert.strictEqual(summary.from, "claude")+ assert.strictEqual(summary.to, "pi")+ assert.strictEqual(summary.converted, AGENT_COUNT)+ assert.ok(Array.isArray(summary.warningsDetail))+ }],++ ["--out writes AGENT_COUNT files", () => {+ const dir = tmpdir()+ runCli(["--from", "claude", "--to", "pi", "--out", dir])+ const files = fs.readdirSync(dir).filter(f => f.endsWith(".md"))+ assert.strictEqual(files.length, AGENT_COUNT, "expected AGENT_COUNT emitted files")+ const planner = fs.readFileSync(path.join(dir, "planner.md"), "utf8")+ assert.match(planner, /name: planner\n/);+ assert.match(planner, /prompt_mode: replace/);+ }],++ ["--out --dry-run writes nothing", () => {+ const dir = tmpdir()+ const out = runCli(["--from", "claude", "--to", "pi", "--out", dir, "--dry-run"])+ assert.match(out, /\[dry-run\] would write/)+ assert.strictEqual(fs.readdirSync(dir).length, 0, "dry-run must not create files")+ }],++ ["unsupported conversion exits non-zero", () => {+ assert.throws(() => runCli(["--from", "claude", "--to", "zed"]), /unsupported conversion/);+ }],++ ["unknown flag exits non-zero", () => {+ assert.throws(() => runCli(["--bogus"]), /unknown argument/)+ }],++ ["--json --out keeps stdout parseable JSON", () => {+ const dir = tmpdir()+ const out = runCli(["--from", "claude", "--to", "pi", "--out", dir, "--json"])+ const summary = JSON.parse(out)+ assert.strictEqual(summary.converted, AGENT_COUNT)+ assert.strictEqual(summary.schema, "ecc.agent-ir.v1")+ }],++ ["missing value for --out exits non-zero", () => {+ assert.throws(() => runCli(["--from", "claude", "--to", "pi", "--out"]), /missing value for --out/)+ }],++ ["--check --json emits JSON", () => {+ const out = runCli(["--check", "--json"])+ const summary = JSON.parse(out)+ assert.strictEqual(summary.ok, true)+ assert.strictEqual(summary.checked, AGENT_COUNT)+ }],++ ["--out followed by a flag is rejected (no unintended write)", () => {+ const dir = tmpdir()+ assert.throws(() => runCli(["--from", "claude", "--to", "pi", "--out", "--dry-run"]), /missing value for --out/)+ assert.strictEqual(fs.readdirSync(dir).length, 0, "must not write anything")+ }],+ ]++ for (const [name, fn] of tests) {+ if (runTest(name, fn)) {+ passed += 1+ } else {+ failed += 1+ }+ }++ console.log(`\nPassed: ${passed}`)+ console.log(`Failed: ${failed}`)+ process.exit(failed > 0 ? 1 : 0)+}++main()diff --git a/tests/pi/agent-emit.test.js b/tests/pi/agent-emit.test.jsnew file mode 100644index 000000000..6c14ccf29--- /dev/null+++ b/tests/pi/agent-emit.test.js@@ -0,0 +1,176 @@+const AGENT_COUNT = require('fs').readdirSync(require('path').join(__dirname,'../../agents')).filter(f => f.endsWith('.md')).length;+/**+ * Tests for the ECC Agent IR → Pi emitter (scripts/lib/agent-emit-pi.js).+ *+ * Verifies that every IR object becomes a valid Pi subagent definition against+ * the verified `@tintinweb/[email protected]` surface: `name` / `description`+ * / `tools` (comma-separated allowlist) / `prompt_mode`, with the prompt in the+ * body. Also enforces the permission boundary and the empty-allowlist guard.+ */++const assert = require("assert")+const yaml = require("js-yaml")++const { parseAllAgents } = require("../../scripts/lib/agent-ir")+const { emitPiAgent, emitAllPiAgents, RESERVED_AGENT_NAMES } = require("../../scripts/lib/agent-emit-pi")+const { CLAUDE_TO_PI_TOOLS, mapToolToPi } = require("../../scripts/lib/agent-tool-map")++const VALID_PI_TOOLS = new Set(Object.values(CLAUDE_TO_PI_TOOLS))++function runTest(name, fn) {+ try {+ fn()+ console.log(` ✓ ${name}`)+ return true+ } catch (error) {+ console.log(` ✗ ${name}`)+ console.error(` ${error.message}`)+ return false+ }+}++function parseEmittedFrontmatter(markdown) {+ const match = markdown.match(/^---\r?\n([\s\S]*?)\r?\n---/)+ assert.ok(match, "emitted markdown must start with a frontmatter block")+ const out = {}+ for (const line of match[1].split(/\r?\n/)) {+ const idx = line.indexOf(":")+ if (idx <= 0) continue+ const key = line.slice(0, idx).trim()+ out[key] = line.slice(idx + 1).trim()+ }+ return out+}++function main() {+ let passed = 0+ let failed = 0++ let irs+ let results+ let warnings+ try {+ irs = parseAllAgents()+ ;({ results, warnings } = emitAllPiAgents(irs))+ } catch (error) {+ console.log(` ✗ setup failed: ${error.message}`)+ console.log("\nPassed: 0")+ console.log("Failed: 1")+ process.exit(1)+ }++ const byId = new Map(irs.map(ir => [ir.id, ir]))++ const tests = [+ ["emits all AGENT_COUNT agents", () => {+ assert.strictEqual(results.length, AGENT_COUNT)+ }],++ ["frontmatter uses the verified prompt_mode contract (no package, no systemPromptMode)", () => {+ for (const r of results) {+ const fm = parseEmittedFrontmatter(r.markdown)+ assert.strictEqual(fm.prompt_mode, "replace", `${r.id}: prompt_mode must be replace`)+ assert.strictEqual(fm.systemPromptMode, undefined, `${r.id}: systemPromptMode must not be emitted`)+ assert.strictEqual(fm.package, undefined, `${r.id}: package must not be emitted (name is the dispatch id)`)+ assert.strictEqual(fm.model, undefined, `${r.id}: model must be omitted (Pi default applies)`)+ assert.strictEqual(fm.name, r.name, `${r.id}: name mismatch`)+ assert.ok(fm.description.length > 0, `${r.id}: empty description`)+ }+ }],++ ["tool allowlist contains only verified Pi built-ins", () => {+ for (const r of results) {+ for (const tool of r.tools) {+ assert.ok(VALID_PI_TOOLS.has(tool), `${r.id}: invalid Pi tool '${tool}'`)+ }+ }+ }],++ ["no Claude tool name leaks into the Pi allowlist", () => {+ const claudeNames = new Set(["Read", "Grep", "Glob", "Bash", "Edit", "Write", "WebSearch", "WebFetch"])+ for (const r of results) {+ for (const tool of r.tools) {+ assert.ok(!claudeNames.has(tool), `${r.id}: leaked Claude tool '${tool}'`)+ }+ }+ }],++ ["read-only agents never gain bash", () => {+ for (const r of results) {+ const source = byId.get(r.id)+ if (!source.tools.includes("Bash")) {+ assert.ok(!r.tools.includes("bash"), `${r.id}: read-only agent must not emit 'bash'`)+ }+ }+ }],++ ["mcp__* tools are never mapped to a tool", () => {+ assert.ok(!results.some(r => r.tools.includes("mcp")), "no 'mcp' tool should be emitted")+ assert.ok(warnings.some(w => w.includes("docs-lookup") && w.includes("MCP tool")), "docs-lookup MCP must warn")+ }],++ ["every unsupported source tool is warned, never silently dropped", () => {+ const unsupportedCount = irs.flatMap(ir => ir.tools).filter(t => mapToolToPi(t).unsupported).length+ const warnedCount = warnings.filter(w => /not a Pi built-in|unmapped tool/.test(w)).length+ assert.strictEqual(warnedCount, unsupportedCount, "each unsupported source tool must warn exactly once")+ assert.ok(unsupportedCount > 0, "expected WebSearch/WebFetch/mcp__* to be unsupported")+ }],++ ["empty allowlist is emitted as tools: none (never blank, never escalates)", () => {+ const noTools = { id: "x", name: "x", description: "x", tools: ["WebSearch"], body: "hi" }+ const { markdown, tools } = emitPiAgent(noTools)+ assert.deepStrictEqual(tools, [], "WebSearch-only agent must have an empty allowlist")+ assert.match(markdown, /^tools: none$/m, "empty allowlist must be emitted as 'tools: none'")+ }],++ ["reserved built-in agent names are warned", () => {+ const colliding = { id: "general-purpose", name: "general-purpose", description: "x", tools: ["Read"], body: "hi" }+ const { warnings: w } = emitPiAgent(colliding)+ assert.ok(w.some(x => x.includes("collides with a Pi built-in agent")), "built-in name collision must warn")+ assert.ok(RESERVED_AGENT_NAMES.has("general-purpose"), "reserved set is pinned")+ }],++ ["body is preserved losslessly", () => {+ for (const ir of irs) {+ const emitted = results.find(r => r.id === ir.id)+ const body = ir.body.replace(/^\n+/, "").trimEnd()+ assert.ok(emitted.markdown.includes(body), `${ir.id}: body not preserved`)+ }+ }],++ ["planner maps to read, grep, find", () => {+ const planner = results.find(r => r.id === "planner")+ assert.deepStrictEqual(planner.tools, ["read", "grep", "find"])+ }],++ ["emission is deterministic", () => {+ const a = emitAllPiAgents(irs).results.map(r => r.markdown).join("\n")+ const b = emitAllPiAgents(irs).results.map(r => r.markdown).join("\n")+ assert.strictEqual(a, b)+ }],++ ["emitted frontmatter is valid YAML and round-trips key fields", () => {+ for (const r of results) {+ const match = r.markdown.match(/^---\r?\n([\s\S]*?)\r?\n---/)+ const fm = yaml.load(match[1])+ assert.strictEqual(fm.name, r.name, `${r.id}: name round-trip`)+ assert.strictEqual(fm.prompt_mode, "replace", `${r.id}: prompt_mode round-trip`)+ assert.deepStrictEqual(String(fm.tools).split(", "), r.tools, `${r.id}: tools round-trip`)+ }+ }],+ ]++ for (const [name, fn] of tests) {+ if (runTest(name, fn)) {+ passed += 1+ } else {+ failed += 1+ }+ }++ console.log(`\nPassed: ${passed}`)+ console.log(`Failed: ${failed}`)+ process.exit(failed > 0 ? 1 : 0)+}++main()diff --git a/tests/pi/agent-ir.test.js b/tests/pi/agent-ir.test.jsnew file mode 100644index 000000000..c66ede9ea--- /dev/null+++ b/tests/pi/agent-ir.test.js@@ -0,0 +1,130 @@+const AGENT_COUNT = require('fs').readdirSync(require('path').join(__dirname,'../../agents')).filter(f => f.endsWith('.md')).length;+/**+ * Tests for the ECC Agent IR parser (scripts/lib/agent-ir.js).+ *+ * Verifies the canonical-agent parse path: every Claude-format agent under+ * agents/ must parse into a valid ecc.agent-ir.v1 object, deterministically,+ * with lossless frontmatter retention.+ */++const assert = require("assert")+const fs = require("fs")+const path = require("path")++const { parseAgentFile, parseAllAgents, IR_SCHEMA_CONST } = require("../../scripts/lib/agent-ir")++const REPO_ROOT = path.join(__dirname, "..", "..")+const AGENTS_DIR = path.join(REPO_ROOT, "agents")++function runTest(name, fn) {+ try {+ fn()+ console.log(` ✓ ${name}`)+ return true+ } catch (error) {+ console.log(` ✗ ${name}`)+ console.error(` ${error.message}`)+ return false+ }+}++function main() {+ let passed = 0+ let failed = 0++ const tests = [+ ["parses all AGENT_COUNT agents", () => {+ const agents = parseAllAgents()+ assert.strictEqual(agents.length, AGENT_COUNT, "expected AGENT_COUNT agents")+ for (const ir of agents) {+ assert.strictEqual(ir.schema, IR_SCHEMA_CONST, `${ir.id}: wrong schema const`)+ assert.ok(/^[a-z0-9-]+$/.test(ir.id), `${ir.id}: id must be kebab-case`)+ assert.ok(ir.name.length > 0, `${ir.id}: empty name`)+ assert.ok(ir.description.length > 0, `${ir.id}: empty description`)+ assert.ok(Array.isArray(ir.tools) && ir.tools.length > 0, `${ir.id}: empty tools`)+ assert.ok(ir.body.length > 0, `${ir.id}: empty body`)+ }+ }],++ ["is deterministic (stable key order + sorted ids)", () => {+ const a = JSON.stringify(parseAllAgents())+ const b = JSON.stringify(parseAllAgents())+ assert.strictEqual(a, b, "parseAllAgents must be deterministic")+ }],++ ["retains current model tier distribution (61 sonnet / 6 haiku / 4 opus)", () => {+ const agents = parseAllAgents()+ for (const ir of agents) {+ assert.ok(ir.model, `${ir.id}: missing model tier`)+ }+ const tally = agents.reduce(+ (acc, ir) => ({ ...acc, [ir.model]: (acc[ir.model] || 0) + 1 }),+ {}+ )+ assert.strictEqual(tally.sonnet, 61, "sonnet count")+ assert.strictEqual(tally.haiku, 6, "haiku count")+ assert.strictEqual(tally.opus, 4, "opus count")+ }],++ ["retains source-only color metadata", () => {+ const agents = parseAllAgents()+ const withColor = agents.filter(ir => ir.color)+ assert.strictEqual(withColor.length, 5, "exactly 5 agents carry color")+ for (const ir of withColor) {+ assert.ok(typeof ir.color === "string" && ir.color.length > 0, `${ir.id}: bad color`)+ }+ }],++ ["parses a known agent losslessly", () => {+ const ir = parseAgentFile(path.join(AGENTS_DIR, "planner.md"))+ assert.strictEqual(ir.id, "planner")+ assert.strictEqual(ir.name, "planner")+ assert.strictEqual(ir.model, "opus")+ assert.deepStrictEqual(ir.tools, ["Read", "Grep", "Glob"])+ assert.ok(ir.frontmatter, "raw frontmatter must be retained")+ assert.strictEqual(ir.frontmatter.name, "planner", "frontmatter.name lossless")+ assert.ok(ir.body.includes("You are an expert planning specialist"), "body preserved")+ }],++ ["throws on a missing frontmatter block", () => {+ const badPath = path.join(__dirname, "..", "fixtures", "agent-no-frontmatter.md")+ fs.mkdirSync(path.dirname(badPath), { recursive: true })+ fs.writeFileSync(badPath, "# no frontmatter here\n")+ try {+ assert.throws(() => parseAgentFile(badPath), /missing frontmatter/)+ } finally {+ fs.rmSync(badPath, { force: true })+ }+ }],++ ["throws on an invalid model tier instead of silently dropping it", () => {+ const badPath = path.join(__dirname, "..", "fixtures", "agent-invalid-model.md")+ fs.mkdirSync(path.dirname(badPath), { recursive: true })+ fs.writeFileSync(badPath, "---\nname: x\ndescription: x\ntools: Read\nmodel: sonnet4\n---\n\nbody\n")+ try {+ assert.throws(() => parseAgentFile(badPath), /invalid model tier 'sonnet4'/)+ } finally {+ fs.rmSync(badPath, { force: true })+ }+ }],++ ["throws when the agents directory is absent", () => {+ const missingDir = path.join(__dirname, "..", "fixtures", "agents-does-not-exist")+ assert.throws(() => parseAllAgents(missingDir), /agents directory not found/)+ }],+ ]++ for (const [name, fn] of tests) {+ if (runTest(name, fn)) {+ passed += 1+ } else {+ failed += 1+ }+ }++ console.log(`\nPassed: ${passed}`)+ console.log(`Failed: ${failed}`)+ process.exit(failed > 0 ? 1 : 0)+}++main()diff --git a/tests/pi/pi-extension-adapter.test.js b/tests/pi/pi-extension-adapter.test.jsindex 08c957a8e..d03032baa 100644--- a/tests/pi/pi-extension-adapter.test.js+++ b/tests/pi/pi-extension-adapter.test.js@@ -319,6 +319,22 @@ function isDisabledByEnvMirror(value) {return typeof value === "string" && DISABLED_VALUES_MIRROR.has(value.trim().toLowerCase())}+/**+ * Mirror of the adapter's `describeAgentPortability` (same three states, same+ * exact strings). The source-text assertions in the matching test pin the real+ * function's wording out of `.pi/extensions/index.ts` so this copy cannot drift.+ */+function describeAgentPortabilityMirror(agentCount, portability) {+ if (agentCount === 0) return "NOT FOUND"+ if (portability.status === "validated") {+ return `${portability.count} agent(s) source schema validated; Pi conversion available via scripts/agent-convert.js`+ }+ if (portability.status === "failed") {+ return `${agentCount} agent(s) present but validation FAILED: ${portability.reason}`+ }+ return `${agentCount} agent(s) present (unvalidated — ${portability.reason})`+}+/** Run the Pi adapter regression suite. */async function main() {console.log("\n=== Testing .pi/extensions/index.ts (Pi thin adapter) ===\n")@@ -1495,6 +1511,48 @@ async function main() {)}],+ ["/ecc-doctor validates agent portability instead of trusting file existence (source contract)", () => {+ const start = extensionSource.indexOf("function validateAgentPortability")+ assert.ok(start !== -1, "expected .pi/extensions/index.ts to define validateAgentPortability")+ const end = extensionSource.indexOf("\nfunction ", start + 1)+ const src = end === -1 ? extensionSource.slice(start) : extensionSource.slice(start, end)++ assert.ok(src.includes("execFileSync("), "must use execFileSync (no shell) to run the check")+ assert.ok(src.includes('"--check"'), "must run agent-convert.js in --check mode")+ assert.ok(/timeout:\s*AGENT_CHECK_TIMEOUT_MS/.test(src), "must bound the check with a finite timeout")+ assert.ok(src.includes("resolveHookRuntime()"), "must reuse the node-runtime resolver, not hardcode 'node'")+ assert.ok(src.includes('"validated"'), "must model the validated state")+ assert.ok(src.includes('"failed"'), "must model the failed state")+ assert.ok(src.includes('"unvalidated"'), "must model the unvalidated state")+ assert.ok(/OK: \(\\d\+\) agents parsed and validated/.test(src), "must parse the real --check output")+ }],++ ["/ecc-doctor renders three honest agent states (behavioral mirror)", () => {+ assert.strictEqual(+ describeAgentPortabilityMirror(68, { status: "validated", count: 68 }),+ "68 agent(s) source schema validated; Pi conversion available via scripts/agent-convert.js"+ )+ assert.strictEqual(+ describeAgentPortabilityMirror(68, { status: "failed", reason: "boom" }),+ "68 agent(s) present but validation FAILED: boom"+ )+ assert.strictEqual(+ describeAgentPortabilityMirror(68, { status: "unvalidated", reason: "no node" }),+ "68 agent(s) present (unvalidated — no node)"+ )+ assert.strictEqual(+ describeAgentPortabilityMirror(0, { status: "unvalidated", reason: "none" }),+ "NOT FOUND"+ )++ assert.ok(+ extensionSource.includes("agent(s) source schema validated; Pi conversion available via scripts/agent-convert.js"),+ "expected the validated line pinned in the source"+ )+ assert.ok(extensionSource.includes("validation FAILED:"), "expected the failed line pinned in the source")+ assert.ok(extensionSource.includes("unvalidated —"), "expected the unvalidated line pinned in the source")+ }],+["isDisabledByEnv() behavioral mirror: recognizes 0/false/off/none/disabled case- and whitespace-insensitively, and the real function reads ECC_PI_RULES", () => {for (const disabledValue of ["0", "false", "off", "none", "disabled"]) {assert.strictEqual(diff --git a/tests/scripts/npm-publish-surface.test.js b/tests/scripts/npm-publish-surface.test.jsindex b176bd827..ce9afaae8 100644--- a/tests/scripts/npm-publish-surface.test.js+++ b/tests/scripts/npm-publish-surface.test.js@@ -67,6 +67,7 @@ function buildExpectedPublishPaths(repoRoot) {"scripts/eval-harness.js","examples/eval-harness","scripts/feedback.js",+ "scripts/agent-convert.js","scripts/catalog.js","scripts/ci/scan-supply-chain-iocs.js","scripts/ci/supply-chain-advisory-sources.js",@@ -303,6 +304,11 @@ function main() {"skills/backend-patterns/SKILL.md","skills/skill-comply/SKILL.md","skills/unified-memory/SKILL.md",+ "scripts/agent-convert.js",+ "scripts/lib/agent-ir.js",+ "scripts/lib/agent-tool-map.js",+ "scripts/lib/agent-emit-pi.js",+ "schemas/agent.schema.json",]) {assert.ok(packagedPaths.has(requiredPath),